Setup & install

Packages on npm

The SDK ships as three packages under the @cadbuildr/ scope:

Package	What it does
`@cadbuildr/sdk-react`	The React surface — `CadbuildrProvider`, `CadbuildrViewer`, `CadbuildrParameterForm`, the parameter-substitution helpers, the kernel-exclusive run queue.
`@cadbuildr/cad-kernel-r3f`	Lower-level kernel-api client + R3F mesh utilities. Used by the SDK and exposed for partners who want manual control.
`@cadbuildr/cad-pyodide-runtime`	Pyodide bootstrap that loads `cadbuildr.foundation` and the project’s Python wheel into the browser. Optional — only needed if you want partners’ end users to author Python in the page.

Install

npm install @cadbuildr/sdk-react @cadbuildr/cad-kernel-r3f \
            @react-three/fiber @react-three/drei three react react-dom

The SDK declares react, react-dom, three, @react-three/fiber, and @react-three/drei as peer dependencies — supply them at the host versions you ship.

Two paths to your first render

Pick the one that matches your deployment shape. Both produce the same behavior — only how the SDK gets a session token differs. See Auth & session tokens for the details.

Browser flow — static / no backend

Best for GitHub Pages, S3, Vercel static, Netlify, partner storefronts that don’t have a server you control. Ship the publishable half of your partner key in the bundle; the SDK mints and refreshes the cbv1 on its own.

import { CadbuildrProvider, CadbuildrViewer } from "@cadbuildr/sdk-react";
 
export function App() {
  return (
    <CadbuildrProvider keyId="7ef7b4133ef1e6c2" projectKey="lego">
      <CadbuildrViewer dag={myDag} />
    </CadbuildrProvider>
  );
}

Server flow — partner has a backend

Mint the cbv1 server-side, pass it to the bundle. Best when you already have a backend that holds secrets.

<CadbuildrProvider sessionToken={tokenFromYourBackend} projectKey="lego">
  <CadbuildrViewer dag={myDag} />
</CadbuildrProvider>

Required configuration

Source	What you need
Hub Settings → SDK partner keys	The `cbsdk_<keyId>_<secret>` for your integration. You’ll use the `<keyId>` half in browser code, or the full key on your server.
kernel-api host	Defaults to `https://kernel-api.cadbuildr.com`; override via the `baseUrl` prop for a staging endpoint if CADbuildr has provided one.
Project key	The slug under your CADbuildr account — must be in the SDK key’s `allowed_projects`.
Allowed origins	Every origin you ship from (including `http://localhost:3007` for dev) must be in the key’s `allowed_origins` list.

Browser-side, the SDK posts JSON DAGs and reads JSON mesh responses over HTTPS — no WebSocket, no shared memory, no service worker.

Versioning policy

@cadbuildr/sdk-react follows semver. Breaking surface area changes bump the major. New props and new components bump the minor. Bug fixes bump the patch.
The cbv1 token format is versioned in the prefix. Any change to the payload shape bumps to cbv2.* and runs both verifiers in parallel during the migration window.
The parameters.schema.json shape is versioned via a top-level schema_version field. The decorator stamps the current version at emit time; the SDK refuses to render unknown versions.

Overview Auth & session tokens