Building Custom Apps

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:

​

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.

​

Fetching Data

Your app needs to authenticate users with Speckle Server. See more information on authentication methods in the Authentication guide. 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

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. 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

• Authentication Guide - Learn about tokens and OAuth
• GraphQL API - Direct API access
• Viewer API - Embed 3D models
• Python SDK - Server-side integrations
• NPM Packages - Available JavaScript packages

​

Getting Help