Quickstart

1. Paste this

<div id="foldkit" style="min-height:640px"></div>

<script src="https://cdn.jsdelivr.net/npm/@foldkit/embed@0.1.0/dist/foldkit-embed.umd.js"></script>
<script>
  Foldkit.mount("#foldkit", {
    publishableKey: "pk_test_foldkit_public_sandbox_publishable_key_0001",
    baseUrl: "https://foldkit.theboxes.asia",
  }).then(function (editor) {
    editor.on('saved', function (event) {
      console.log('design saved', event.designId)
    })
  })
</script>

Open the page. You should see a box style, a dieline you can draw on, and a 3D preview that follows it. Everything you save goes into the public sandbox tenant and is thrown away — it is there to be experimented with.

2. Or in React

import { useEffect, useRef } from 'react'
import { Foldkit } from '@foldkit/embed'

export function Designer({ onSaved }) {
  const container = useRef(null)

  useEffect(() => {
    let editor
    let cancelled = false

    Foldkit.mount(container.current, {
      publishableKey: "pk_test_foldkit_public_sandbox_publishable_key_0001",
      baseUrl: "https://foldkit.theboxes.asia",
    }).then((mounted) => {
      // React 18's StrictMode runs effects twice in development, so the mount
      // that resolves after the cleanup ran has to tear itself down.
      if (cancelled) return void mounted.destroy()
      editor = mounted
      editor.on('saved', ({ designId }) => onSaved?.(designId))
    })

    return () => {
      cancelled = true
      editor?.destroy()
    }
  }, [onSaved])

  return <div ref={container} style={{ minHeight: 640 }} />
}

The cleanup return is not optional: without `destroy()` a Fast Refresh or a route change leaves the old iframe listening, and you get two editors racing to save the same design.

3. Get the design out

A design is only useful to you once your own system has its id. There are two ways, and you almost certainly want both.

1. In the page, immediately: the saved event fires with a designId as soon as the customer saves. Use it to attach the design to a cart line and to render a thumbnail.
2. To your backend, reliably: the design.saved webhook. The page event is lost if the tab closes at the wrong moment; the webhook is retried. See the webhook guide.

<img src="https://foldkit.theboxes.asia/api/v1/designs/DESIGN_ID/preview.png?width=400" alt="Custom box" />

The preview endpoint needs a secret key, so render it from your server rather than from the page — or take a snapshot in the browser with editor.getSnapshot(), which needs no credential at all.

4. Move to your own tenant

When you are ready, we give you a tenant with your own keys. Two things change, and only one of them is a code change.

• Swap the key. Your pk_live_… replaces the sandbox one. That is the code change.
• Declare your origins. Every origin that will host the editor — https://shop.example.com, your staging host, your local dev URL — goes on your allow-list in the console. Until an origin is on it, the key is refused there and the browser refuses to frame the editor at all.

Where to go next

• The SDK guide — commands, events, error handling, and how token renewal works.
• Server-to-server — mint a session token so we know which of your customers is designing.
• Branding — make it yours, including the 2D canvas, which CSS cannot reach.
• Errors — every code, keyed by exactly the string the SDK gives you.