Guide

How to add a 3D product configurator to a React app

, imagine.io ·

Install the SDK, add a small server route that exchanges your API key for a session token, and call mount() once with the system id. The browser only ever holds the short-lived token, never the key. Rules, constraints and pricing run on the server; your React app renders the result and can restyle or extend every part of it.

This guide is the SDK route. It fits a React app of your own, or a React storefront such as Shopify Hydrogen or a Next.js shop. On a Shopify theme, WordPress or Webflow there is no React to mount into: either embed a sharing link and build your own buttons around it through the bridge (the Shopify, WordPress, WooCommerce and Webflow guides), or build your page with this SDK, host it, and embed that page with the same iframe; the bridge activates on any page that mounts the SDK inside an iframe. All three routes: which route fits which site.

The whole integration

npm install @imagineio/configurator-sdk

import { mount } from '@imagineio/configurator-sdk';

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

Step by step

  1. Create or open the app

    A fresh app: npm create vite@latest my-configurator -- --template react. An existing app: Vite is the supported path, because the SDK's Vite plugin serves its static files and keeps react and three deduped. Another bundler is possible by hand; see the FAQ.

  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

    // vite.config.js
    import imagineConfigurator from '@imagineio/configurator-sdk/vite';
    
    export default defineConfig({
      plugins: [react(), imagineConfigurator()],
    });

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

  4. Get an API key and the system id

    In the dashboard, Settings › API Keys › Create key: name it, choose Read & write or Read only, and list the websites that may use it, including localhost:5173 for development. The system id is under Scenes › Configurable Systems. No catalog yet? Import a sample catalog first. See the quickstart for the screenshots.

  5. Add the token route on your server

    The key never reaches the browser. One route exchanges it for a 30-minute session token:

    // 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: 'catalog', system_id: 12, origin: 'https://www.your-site.com' }),
      });
      res.status(r.status).json(await r.json());
    });

    Two values to get right. origin must be the exact origin the page is served from, scheme, host and port, for example http://localhost:5173 in development, and that origin must also be in the key's websites list under Settings › API Keys; otherwise every request from the page is refused with ORIGIN_NOT_ALLOWED. scope: 'catalog' is enough for an anonymous product page (configure, price, add to cart); use 'session', with a read-and-write key, when shoppers save and share designs or generate images. For local development you can skip this step and put the key in .env.local as VITE_API_KEY; the SDK reads it on its own.

  6. Mount it

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

    That is the whole integration. The SDK brings its own styles, renders the customisation options and the 3D scene, sends every click to the engine and draws what comes back. It calls your route again before the token expires and once on a 401.

  7. Make it yours

    Theme it, replace parts of the UI, or listen to every event: the SDK docs have twelve walkthroughs. Start with theming and layout and events.

Hand the configuration to your cart

With the SDK on the page there is no iframe and no bridge: call the functions directly. The price arrives through the price.changed event or the usePrice() hook, and quote.read() gives the cart payload with every line's selections resolved to names.

import { on, quote, project, usePrice } from '@imagineio/configurator-sdk';

// Live price in your own component
function PriceBadge() {
  const { grandTotal, currency } = usePrice();
  return <b>{grandTotal} {currency}</b>;
}

// Your Add to cart button
async function addToCart() {
  const q = quote.read();                    // lines, totals, system, formatted prices
  const token = project.getShareToken();     // only a saved design has a link worth attaching
  await fetch('/cart/add', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ title: q.system.name, price: q.totals.grandTotal, currency: q.currency, lines: q.lines,
                           design_url: token ? project.shareUrl() : null }),
  });
}

// Rebuild a cart preview on every change that can affect billing
for (const e of ['product.added', 'product.removed', 'option.selected', 'layout.changed', 'price.changed']) {
  on(e, () => refreshCartPreview(quote.read()));
}

Never sum catalog prices yourself; the engine's pricing is the only price. The e-commerce walkthrough shows the Shopify mapping from a configurator line to a store variant, and the bridge chapter covers the case where your React page is itself inside an iframe on a store.

Other platforms

Frequently asked questions

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 use Next.js or another framework?

Vite is the documented and tested path. The package ships compiled ES modules, so another bundler can load it, but you then do by hand what the Vite plugin does: copy node_modules/@imagineio/configurator-sdk/static into your public folder so the Draco decoder is served at /assets/draco/, make sure the bundle holds one copy of react, react-dom and three, and set the key with config.setApiKey(process.env.NEXT_PUBLIC_CONFIGURATOR_KEY) because import.meta.env does not exist outside Vite. We have not tested Next.js ourselves; tell us if you run it and we will document it.

Does my page decide any prices or rules?

No. Every change goes to the engine, which applies the matching rules, re-checks every constraint, prices the result and returns one resolved state. Your app reads pricing from the response; it never computes a price locally.

Troubleshooting

npm install fails 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.

The canvas is blank.

Usually a second copy of react or three pulled in by another dependency. Make sure the Vite plugin from @imagineio/configurator-sdk/vite is in vite.config.js; it dedupes both. Then check the console for a 401 (token route) or a 403 (the site is not in the key's websites list).

Requests fail with 401 or 403.

401: the token route returned an error or the key was revoked; the SDK retries your route once. 403 with the code ORIGIN_NOT_ALLOWED: the page's origin is not in the API key's websites list in Settings › API Keys, or the token was minted with an origin that is not the page's. For local development the entry must include the port, localhost:5173, not localhost.

The browser console shows a CORS error on every request.

That is how an origin refusal looks from the page: the backend answers 403 with ORIGIN_NOT_ALLOWED and no CORS headers, so the browser reports CORS while the response body stays readable in the Network tab. Fix the key's websites list, or the origin in the token body, rather than the CORS setup.

SDK documentation · Admin guide