Skip to main content
Build custom web applications that integrate with Speckle to display, analyze, and interact with your AEC data. This guide will walk you through creating a complete application using Speckle’s APIs.
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:
  1. Set up authentication - Choose between Personal Access Tokens or OAuth2
  2. Initialize a client - Use the appropriate SDK or API client
  3. Fetch data - Access user information, projects, models, versions, and version data
  4. Build your UI - Use the Viewer API or UI components to display data
For detailed implementation examples, see the SDK and API documentation linked below.

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.
Your token, the GraphQL API for projects, models, and versions, webhooks, permissions, and sharing work the same for every version. The version’s data is different: a version is a bundle of parquet files, not an object graph you fetch from the objects endpoints. Which path your app takes depends on whether it renders.

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.
Writing scripts with a Speckle SDK instead? The SDK applies every bundle rule for you. Start from the .NET or Python migration pages.
A loader that fetches referencedObject from the objects endpoints gets a 404 on every bundle version. Dispatch on Version.schemaVersion before you fetch (3 is a bundle, null is an object graph), and keep your existing reader for versions published before 2026.9.

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 URL
  • SPECKLE_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

Getting Help

Community Forum

Ask questions and share your apps

GitHub Examples

Explore example applications

Discord

Real-time developer discussions
Last modified on November 14, 2026