create-commercengine

Scaffold a Commerce Engine storefront — from a production starter, or by adding Commerce Engine to a project you already have.

npm  create commercengine@latest
pnpm create commercengine@latest
bun  create commercengine@latest
yarn create commercengine

What it does

Clone a starter. Downloads one of the production storefronts and turns it into a standalone project you can install and run.

Start from scratch. Writes the Commerce Engine integration layer — client, config, capability wiring, .env — into a project you already scaffolded with your framework's own tool.

Options

Every prompt has a flag, so CI and coding agents never hit an interactive question.

| Flag | | |---|---| | --mode <starter\|existing> | what to start from | | --template <slug> | linea · little-things · soja | | --framework <id> | react · next · tanstack · astro · sveltekit · node | | --no-checkout | omit Hosted Checkout | | --no-seo | omit SEO & AEO | | --no-agent-tools | omit agent tools | | --store-id <id> | Commerce Engine store ID | | --api-key <key> | Storefront API key | | --env <sandbox\|live> | defaults to sandbox | | --tooling <id> | biome · oxlint · eslint · none — defaults to biome | | --workspace | keep the monorepo shape instead of flattening | | -y, --yes | accept defaults, skip prompts | | -h, --help | |

Capabilities are opt-out rather than a list, so --yes and the default answer cannot disagree. They apply to --mode existing only: a starter arrives with all four wired into its pages, and there is no honest way to subtract one at download time. Passing them with a starter prints a warning saying so.

# a full storefront
npm create commercengine@latest my-store -- \
  --template soja --framework next --tooling biome --yes

# add Commerce Engine to a project you already have
npm create commercengine@latest . -- \
  --mode existing --framework next --no-agent-tools --yes

Why starters need more than a subdirectory download

The starters live in a monorepo, and each app depends on sibling workspace packages:

// apps/soja-next/package.json
"@ce/soja-shared": "workspace:*",
"@ce/soja-ui":     "workspace:*"

Extracting the app on its own produces a directory that cannot install — workspace: only resolves inside the workspace that declares it, so npm install fails on EUNSUPPORTEDPROTOCOL before downloading anything.

So the CLI walks that dependency closure, downloads every package the app needs, and flattens the result into a single package:

my-store/
├── package.json          no workspaces, no workspace: ranges
├── biome.json
└── src/
    ├── app/ …            the app
    ├── ui/               was packages/soja-ui
    └── shared/           was packages/soja-shared

Import specifiers are rewritten onto the app's existing @/* alias, the vendored packages' own dependencies are merged into the manifest, and stylesheet @imports become relative paths — PostCSS resolves those itself and does not understand the tsconfig alias.

The result installs with npm, pnpm, yarn or bun alike, because nothing workspace-shaped survives. Pass --workspace to keep the monorepo layout instead; it is useful mainly for tracking upstream changes to the starter.

The catalog lives in the starter repo

Templates and frameworks are read from starters.json at the root of tark-ai/ce-starter-projects at runtime, with a bundled fallback for offline use.

Adding a template or a framework is therefore a one-file change in the starter repo and needs no release of this CLI.

Capabilities

| | | |---|---| | Storefront SDK | @commercengine/storefront — always installed | | Hosted Checkout | @commercengine/checkout | | SEO & AEO | @commercengine/seo | | Agent tools | @commercengine/ai |

All optional capabilities are selected by default. An SEO-first, AI-first storefront is the intended shape; opting out should be deliberate.

Credentials

Store ID and Storefront API key come from the Admin Portal at https://<your-subdomain>.commercengine.io/organisation/apikeys.

The API key is scoped to a single channel. Products assigned to a different channel will not appear, and the API returns an empty list rather than an error — so an empty catalog usually means channel scoping, not a broken integration. See Credentials & channels.

Development

pnpm build
node dist/index.js my-store --template soja --framework nextjs --yes

Testing locally

Everything below runs your local build rather than the published package.

The non-interactive path. Fastest loop — every prompt is supplied by a flag, so it runs to completion without a TTY:

pnpm build
cd /tmp && rm -rf smoke && mkdir smoke && cd smoke
node ~/ce-ts-sdk/packages/create-commercengine/dist/index.js my-store \
  --template soja --framework next --tooling biome --yes

The interactive TUI. Just drop the flags and run it from a real terminal:

node ~/ce-ts-sdk/packages/create-commercengine/dist/index.js

Piping its output (| tee, | head) hides the prompts, because clack needs a TTY. To capture a transcript, give it a pseudo-terminal:

script -q /dev/null node ~/ce-ts-sdk/.../dist/index.js

As the real command. pnpm link puts create-commercengine on PATH, so npm create commercengine resolves to the local build — this is the only way to test the npm create entry point itself:

cd ~/ce-ts-sdk/packages/create-commercengine && pnpm link --global
cd /tmp && npm create commercengine my-store
pnpm unlink --global create-commercengine   # when finished

Verifying the output actually works. Scaffolding succeeding is not the same as the project building — the interesting bugs live past that line:

cd my-store
npm install          # proves nothing workspace-shaped leaked into the manifest
npm run check        # proves the tooling preset is installed and configured
npm run build        # proves the flattened imports and CSS paths resolve

Worth running across the matrix rather than one combination: the templates differ in which shared packages they pull in, and the frameworks differ in how they resolve them.