Building a connector or host add-in? If you are connecting Speckle to or from a desktop
application, ETL pipeline, or enterprise system—not a browser-based product on Speckle—see
Connectivity instead.
What You Will Build
By the end of this guide, you’ll have a working application that can:- Authenticate users with Speckle Server
- Fetch and display user information
- Search and browse projects
- Display project versions
- Persist user preferences locally
Prerequisites
Before you begin, make sure you have:- Node.js (v16 or higher) installed
- Basic familiarity with JavaScript/TypeScript
- A Speckle account at app.speckle.systems or your own server
- A code editor (VS Code recommended)
Choose Your Framework
You can build Speckle applications with any web framework. Here are some popular options:Vue.js
Great for building interactive UIs. Works well with Speckle’s Vue components.
React
Popular choice for building modern web applications.
Next.js
React framework with server-side rendering and routing.
Nuxt.js
Vue framework with built-in support for Speckle UI components.
Getting Started
To build a Speckle application, you’ll need to:- Set up authentication - Choose between Personal Access Tokens or OAuth2
- Initialize a client - Use the appropriate SDK or API client
- Fetch data - Access user information, projects, models, versions, and version data
- Build your UI - Use the Viewer API or UI components to display data
Fetching Data
Your app needs to authenticate users with Speckle Server. See more information on authentication methods in the Authentication guide. Once authenticated, the GraphQL API gives you:- User Information: The current user’s profile, email, and account information.
- Projects and Models: Projects available to the authenticated user, project details, and the models within them.
- Versions: Version history for each model, with the message, author, source application, and creation date of each version.
My app renders models
You import
@speckle/viewer. Bridge the bundle to the object shape the viewer converts, with
sample code you copy into your app.My app only reads data
You read properties, quantities, or geometry without the viewer. Read the bundle directly. The
load mechanics are the same ones every non-SDK consumer uses.
Why there is no drop-in object-graph loader
If your app is built on@speckle/objectloader or @speckle/objectloader2, the natural ask is a
version of those packages that reads bundles and hands you the same object graph:
getRootObject(), __closure, getObjectIterator(), unchanged. That is not coming, on purpose.
Emulating that surface would mean rebuilding the object graph that bundles replace: a third
implementation of the receive fidelity contract, kept in step with the .NET and Python SDKs
forever, reconstructing hashes and closures that no longer exist in the data. It would also teach
new apps a shape the platform is moving away from.
What to do instead depends on what you were using the graph for.
The mechanics for all four are in Load a bundle in your own
code. That page is written for any non-SDK consumer,
which includes you. It is not connector-specific.
Writing Data
Publishing is the harder half. A version is a bundle built and uploaded through an ingestion, and there is no published JavaScript bundle builder. .NET and Python are the only SDKs that build bundles today.@speckle/objectsender sends an object graph
that the server converts to a bundle before the version appears. That path is superseded: do not
build new work on it.
For new work, consider these options in this order:
The wire sequence, the correctness rules, and a build order are in Publish a bundle from your own
code. Read it before choosing the second option: it is
a real piece of work, and unlike the read path there is no worked sample.
Building the UI
You can build your application’s user interface using any frontend framework. Here are some options for integrating Speckle’s capabilities into your UI:- Using Speckle Viewer: Embed the 3D viewer in your application to display interactive 3D models. The Viewer API provides full control over rendering, navigation, and interaction. The published package has no bundle loader, so follow Load a bundle in your Viewer app. For complete Viewer documentation and examples, see the Viewer API guide.
- Using Speckle UI Components For Vue.js and Nuxt.js applications, use the official UI components to quickly build Speckle-branded interfaces with pre-built components for projects, models, and authentication. See @speckle/ui-components and @speckle/ui-components-nuxt for available components and documentation.
Data Persistence
Store user preferences and application state to improve user experience. Consider:- User preferences - Selected projects, view settings, filters
- Authentication state - Token storage (use secure methods in production)
- Application state - Current selections, UI state, cached data
Deployment
Deploy your application to any hosting platform that supports static sites or server-side applications:- Static hosting - Netlify, Vercel, GitHub Pages
- Server applications - Heroku, Railway, AWS, Azure
- Container platforms - Docker, Kubernetes
Environment Variables
Configure these in your deployment platform:SPECKLE_SERVER_URL- Your Speckle server URLSPECKLE_APP_ID- Your OAuth app ID (if using OAuth)SPECKLE_APP_SECRET- Your OAuth app secret (server-side only, never expose in client code)
Next Steps
- Authentication Guide - Learn about tokens and OAuth
- GraphQL API - Direct API access
- Viewer API - Embed 3D models
- Load a bundle in your own code - Read version data without an SDK
- Python SDK - Server-side integrations
- NPM packages - Available JavaScript packages
Getting Help
Community Forum
Ask questions and share your apps
GitHub Examples
Explore example applications
Discord
Real-time developer discussions