Get running

SDK quickstart: a running 3D configurator in fifteen minutes

Get a catalog in and publish it, create a key, install the package, add a token route, call mount() once. Nine steps, on a page of their own.

, imagine.io ·

Install @imagineio/configurator-sdk, add a small server route that exchanges your API key for a session token, and call mount() once with the system id. From an empty Vite app to a live configurator with live pricing in about fifteen minutes. Rules, constraints and pricing run on the server; the browser only renders.

You need a catalog with a published layout (import a sample catalog, a sofa or a kitchen, or upload your own) and two values: your organisation's API key and the system id of the configurator (a system is one configurable product line). All of it comes from the imagine.io dashboard; steps 4 to 6 show where.

Nine steps

  1. Create a Vite React app

    Skip this if you are adding the SDK to an existing Vite app. Vite is the supported path: the SDK ships ES modules and a Vite plugin that serves its static files and keeps react and three deduped.

    npm create vite@latest my-configurator -- --template react
    cd my-configurator
  2. Install the SDK

    Version 0.1.6 and later support React 18 and React 19. The 3D packages (three, fiber, drei) are installed for you, at the versions that match your React.

    React 19, which a fresh Vite template ships: install the package on its own. npm adds three.js 0.186, @react-three/fiber 9 and @react-three/drei 10. Keep React at 19.3 or earlier; @react-three/fiber 9 does not accept 19.4 yet.

    npm install @imagineio/configurator-sdk

    React 18: name the React 18 versions in the same command, so npm installs three.js 0.159, @react-three/fiber 8 and @react-three/drei 9. A fresh Vite template ships React 19 types, so install the React 18 ones too.

    npm install @imagineio/configurator-sdk react@^18.2 react-dom@^18.2 three@~0.159.0 @react-three/fiber@^8.15 @react-three/drei@^9.88 @react-three/postprocessing@^2.16 postprocessing@~6.36.0
    npm install -D @types/react@^18.2 @types/react-dom@^18.2

    One visible difference: three.js 0.186 lights the same HDR environment slightly differently from 0.159, so a scene can look a little different on React 19 than on React 18. That comes from three.js; no setting changes it.

  3. Add the Vite plugin

    One plugin, two jobs. It serves the SDK's static files in development and copies them into your build: mainly the Draco decoder, which the browser needs to unpack the compressed 3D models, so without it models fail silently. And it keeps react and three deduped, so a second copy pulled in by another dependency cannot blank the canvas.

    // vite.config.js
    import imagineConfigurator from '@imagineio/configurator-sdk/vite';
    
    export default defineConfig({
      plugins: [react(), imagineConfigurator()],
    });
  4. Get a catalog in: import a sample or upload your own

    The configurator shows nothing until the organisation has a catalog. Sign in to the imagine.io dashboard, or sign up first if your organisation has no account yet, then get a catalog in, either way:

    • Import a sample catalog. A sectional sofa or a kitchen, with models, textures, rules and prices, ready in a few minutes: download, extract, drop the folder on Catalog › Import Catalog. The sample catalogs page has the links and the five steps. The fastest way to see the SDK running.
    • Upload your own. Products and variants, materials, components, option sets and options, then a configurable system that ties them together. The admin guide walks through each in order, or the same importer takes your own spreadsheet and assets.
    The imagine.io dashboard sign-in screen
    Sign in, or create the account, at the dashboard.
  5. Publish the layout

    Both routes end in a draft. Open the system under Scenes › Configurable Systems, then Layouts › Publish. Until you do, the configurator mounts into an empty scene with no error, because nothing failed.

    While the system is open, note its system id: the number at the end of the address bar, also listed next to each system. The mount step needs it.

    The Layouts tab of a configurable system, with the Publish button
    Layouts › Publish. The system id is the number at the end of the address bar.
  6. Get your API key

    Go to Settings › API Keys and press Create key. Name it after the site that will use it, choose Read & write or Read only, and list the websites that may use it: shop.example.com for a site, *.example.com for its subdomains, and for your machine localhost with its port, localhost:5173. A key with an empty list works nowhere. One key serves every system in the organisation.

    The API Keys page: one key listed with its masked value, a permission selector and a Revoke action
    Settings › API Keys. Copy the key when it is shown; its permission and websites can be changed later.
  7. Add the key and mount

    Put the key in an env file, not in your source. Create .env.local next to package.json; Vite loads it and git ignores it.

    VITE_API_KEY=YOUR_ORG_API_KEY

    The SDK reads VITE_API_KEY on its own. Replace src/main.jsx with this; the SDK brings its own styles.

    import { mount, config } from '@imagineio/configurator-sdk';
    
    // Optional: a sales channel, for per-channel prices, hidden options and a theme
    config.setChannelId('dealer-42');
    
    // Boot the system, load catalog and scene, render the full default UI
    const app = mount('#root', { systemId: 1 });
    // later: app.unmount();
  8. Production: a session token instead of the key

    The API key is long-lived and reads your whole catalog, so it must never reach a browser. In production your server asks imagine.io for a session token, which lasts 30 minutes and is safe for the browser to hold, and the SDK uses that instead. One route on your server:

    // server.js
    app.post('/configurator-token', async (req, res) => {
      const r = await fetch('https://api-configurator.imagine.io/api/v1/auth/token/', {
        method: 'POST',
        headers: { 'X-Api-Key': process.env.CONFIGURATOR_API_KEY, 'Content-Type': 'application/json' },
        body: JSON.stringify({ scope: 'session', system_id: 12, origin: 'https://www.your-site.com' }),
      });
      res.status(r.status).json(await r.json());
    });

    The three body fields are optional and each narrows what the token can do: scope is session (can save projects and upload renders) or catalog (load, configure and price only); system_id locks it to one system; origin locks it to your site. Then hand mount() the route. No VITE_API_KEY exists in this build.

    const app = mount('#root', {
      systemId: 12,
      getToken: async () => (await fetch('/configurator-token', { method: 'POST' })).json(),
    });

    The SDK sends the token as Authorization: Bearer on every request, calls your route again shortly before the token expires and once more on a 401. If the key ever leaks, revoke it in the dashboard: every token made from it stops working within about 30 seconds. More in how session tokens work.

  9. Run

    npm run dev

    What you should see: a brief loader, then the customisation options on the left and the 3D scene on the right. A different systemId is a different configurator, a sofa, a kitchen, a wardrobe, with no frontend change. An empty scene with no error means the layout was never published: step 5. Blank page or missing models? The troubleshooting section covers every known cause.

What next

You have a running configurator. The three things most teams do next each have a walkthrough in the SDK docs:

Frequently asked questions

Do I have to use Vite?

For the quickstart, yes: it is the documented and tested path, and the SDK's Vite plugin does two things for you, serving the static files (mainly the Draco decoder) and keeping react and three deduped. The package itself is compiled ES modules, so another bundler can load it if you do those two things by hand; the React guide's FAQ lists them.

Why does npm install fail with ERESOLVE?

Two causes. A React 18 app that installed the package on its own: npm picked the React 19 versions, so name the React 18 ones in the same command: npm install @imagineio/configurator-sdk react@^18.2 react-dom@^18.2 three@~0.159.0 @react-three/fiber@^8.15 @react-three/drei@^9.88 @react-three/postprocessing@^2.16 postprocessing@~6.36.0. A React 19 app that already has three.js 0.187 or newer, which the SDK does not accept yet: run npm install @imagineio/configurator-sdk three@~0.186.0. Do not use --legacy-peer-deps; it only hides the conflict.

Which React versions does the SDK support?

React 18 and React 19, in version 0.1.6 and later. One package covers both; your React version decides which 3D packages npm adds: three.js 0.186, @react-three/fiber 9 and @react-three/drei 10 on React 19; three.js 0.159, @react-three/fiber 8 and @react-three/drei 9 on React 18. On React 19, keep React at 19.3 or earlier; @react-three/fiber 9 does not accept 19.4 yet.

How do I move an app from React 18 to React 19?

Remove the React 18 3D packages and reinstall from scratch; installing React 19 over them stops with ERESOLVE, because package-lock.json still holds @react-three/fiber 8. Run npm uninstall three @react-three/fiber @react-three/drei @react-three/postprocessing postprocessing, delete node_modules and package-lock.json, then run npm install react@^19.3.1 react-dom@^19.3.1 and npm install -D @types/react@^19.3.0 @types/react-dom@^19.3.0. npm then adds the React 19 versions for the SDK.

Can I ship VITE_API_KEY to production?

No. The API key is long-lived and reads the whole catalog. In production a route on your server exchanges it for a 30-minute session token, and mount() gets that route as getToken. The browser only ever holds the token.

Where does the system id come from?

Scenes › Configurable Systems in the dashboard. Each configurator built for your organisation is listed with its id; it is also the number at the end of the address bar when a system is open.

Why is the scene empty after I mount?

Almost always because the layout was not published. A catalog, imported or built by hand, stops at a draft; open the system under Scenes › Configurable Systems and press Publish on the Layouts tab. The other cause is a systemId that names a different system.

Full SDK documentation · Sample project on GitHub