create-detach-app

Scaffold a Detach storefront in one command: the reference Next.js storefront, renamed under your own namespace, with its CMS workspace created and provisioned — keys, live preview, revalidation, component manifest, and a starter draft page.

npm create detach-app@latest my-store -- --base-url https://cms.example.com
# or: pnpm create detach-app my-store --base-url https://cms.example.com

What you need

• Node 24+ (the CLI and build scripts run TypeScript directly).
• A Detach admin you can sign in to — its URL is --base-url. No API key needed: the scaffolder starts a cms login device flow and you approve it in the browser.

What one run does

1. Scaffolds the app into ./my-store from the bundled template — the same reference storefront the Detach repo develops against, snapshotted at release time. Your namespace replaces the demo's everywhere it is an identifier (section types like acme.hero, cookie and metaobject prefixes, the workspace slug); @usedetach/* dependencies are pinned to the versions published with this release.
2. Signs you in if this machine has no stored credential (device flow — approve in the browser).
3. Creates the workspace (three environments, five roles), or adopts one that already has your slug.
4. Provisions it: a delivery API key, the preview configuration, and the revalidation webhook, all pointed at your dev server's port; writes .env.local with the results.
5. Installs and registers: pnpm install (or npm), then cms init — type generation and the component manifest push, so every section is in the editor's library immediately.
6. Seeds starter content from the reference storefront's configured content, all of it published so nothing on the fresh site reads as broken: the header and footer global frames (the chrome around every page), the default product and collection templates (how Shopify routes render), the cart and account pages (the header links straight to them), and a Home page (a hero and a newsletter) — edit and republish it as your first act.

Then:

cd my-store
pnpm run dev          # storefront on your chosen port

Open your admin's workspace dashboard and edit Home. While cms dev runs in the app, the editor also offers your local server as a live preview target.

Options

| Flag | Default | Meaning | | ------------------ | -------------------------------- | ---------------------------------------------- | | --namespace <ns> | first word of the name | Component-type namespace (<ns>.hero) | | --workspace <s> | the namespace | Workspace slug to create or adopt | | --base-url <url> | prompted for (see below) | Your Detach admin's origin — where you sign in | | --port <n> | 3001 (next free in a monorepo) | Dev-server port; preview + webhooks follow it | | --skip-provision | off | Scaffold only — no CMS calls, no sign-in |

Without --base-url, the command asks for your admin's URL — the Detach portal you sign in at. (Inside the Detach monorepo it defaults to the local dev fleet's http://localhost:3000 instead.)

If provisioning fails partway — the admin was down, the network dropped — the scaffold is kept. Re-run the same command and it resumes where it stopped: already-seeded content is adopted, and an existing .env.local keeps its delivery key and webhook secret.

Useful afterwards

cms dev                # your local server as an editor preview target, manifest auto-synced
cms content validate   # CI gate: would this build break published content?
cms mcp --write        # let an agent (e.g. Claude Code) read your workspace's schema & content

Shopify env vars are deliberately absent from the scaffold: the storefront runs fully (loaders answer null, sections fall back to snapshots) until you connect a shop from the workspace's settings.

Inside the Detach monorepo

Run inside the Detach repo, the same command scaffolds into apps/<name> from the live example app with workspace:* dependencies — pnpm and turbo pick it up with zero wiring. --standalone forces the standalone output anywhere.