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.

​
What You’ll 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 and commits
  • 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, and versions
  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.

​
Authentication

Your app needs to authenticate users with Speckle Server. You have two main options:

​
Personal Access Tokens (PATs)

Best for: Server-side applications or single-user tools PATs are simple tokens that provide direct API access. They’re ideal for scripts, automation, and server-side applications where you control the token storage.
Security: Never expose PATs in client-side code. Use environment variables or secure storage for server-side applications.

​
OAuth2 with PKCE

Best for: Multi-user web applications OAuth2 with PKCE is the recommended method for web applications that need to authenticate multiple users. It provides secure, user-consented access without exposing credentials.
For detailed authentication information, see the Authentication guide or use the speckle-auth community package.

​
Fetching Data

Once authenticated, you can fetch data from Speckle:

​
User Information

Access the current user’s profile, email, and account information through the API.

​
Projects and Models

List projects available to the authenticated user, access specific project details, and browse models within projects.

​
Versions and Data

Retrieve version history for models, access specific version data, and load the actual Speckle objects referenced by versions.
For detailed API documentation and code examples, see the GraphQL API or Python SDK documentation.

​
Building the 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.
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
Security: Never store sensitive tokens in localStorage for production apps. Use secure HTTP-only cookies or server-side sessions instead.

​
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