Start

Start a campaign build.

A Map ID is what the Workspace gives a saved map, such as summer-v1-a1b2. No map yet: Path 1. Map in hand: Path 2.

Path 1 · No map yet

Make a map in the Workspace.

  1. Set up the campaign in the Campaigns App in your Next Commerce dashboard (guide): products, prices, API key.
  2. Map the funnel in the Workspace: funnel flow, products, preview.
  3. Save; you get a Map ID.
Open Workspace
Path 2 · Build from a Map ID

Hand the build to your agent.

  1. Have Node.js 20.19 or newer, and Claude Code or Codex.
  2. In the Workspace, open your map, go to Handoff, and press "Copy start prompt". It carries everything your agent needs, pinned to the toolkit version your map was saved with.
  3. Make an empty folder for the campaign and open it in Claude Code or Codex.
  4. Paste the prompt. The agent creates the campaign, pins the toolkit, and runs the first check, then stops and asks for the things only you have (below).
  5. When it says QA passed, the verdict is on your map in the Workspace. That is the moment to launch.
Open Workspace

Commands: For agents, below.

01 / Your part

What you'll be asked for.

  • The campaign's API key, from the Campaigns App in your Next Commerce dashboard.
  • Your page designs, or "use the template as-is".
  • A preview site, where the built pages go for QA's test orders.
For agents (and people who want the commands)

The same build, as the commands your agent runs. The pin is stamped from this portal's toolkit dependency.

  1. Check the prerequisites.

    Node.js 20.19 or newer with npm 10 or 11 (node --version && npm --version), Git, a POSIX shell, and the campaign's Campaign Cart API key from the Campaigns App (public; stored in the map).

  2. Agents: read the orientation contract first.

    Before installing or running anything, read AGENTS.md at the pinned commit; it sets the reading order.

  3. Create the campaign folder.

    A page-kit project. Replace <route> with the campaign's public route (its folder name), <family> with the starter design to clone (compare; the map may name one). For an existing page-kit campaign, cd into it instead; if it already holds a matching src/<route>/, the toolkit skips its own setup stage.

    create
    mkdir -p "<route>" && cd "<route>" && npm init -y && npm i next-campaign-page-kit &&
  npx campaign-init --non-interactive --template <family> --slug "<route>" --name "<campaign name>"

  4. Pin the toolkit in the campaign.

    Commit package.json and package-lock.json; CI and Netlify install the pin from them.

    pin
    npm i -D "github:NextCommerceCo/campaigns-os#bbff33d12c3d92bdbef25a29ea4b75c5d3e899d2"

  5. Install the skills into your agent, then restart it.

    Pick one. Writes the five lifecycle skills into ~/.claude/skills or ~/.codex/skills, replacing same-name folders. Restart the agent.

    install-skills
    npx campaigns-os install-skills --platform claude
npx campaigns-os install-skills --platform codex

  6. Prepare the source folder.

    start needs an existing ./source folder even for template-only builds. Create it, then:

    • Bespoke pages: Page Kit-ready HTML, one file per page (source adapters), listed in a source manifest with desktop and mobile screenshots (design source package).
    • Template pages as shipped: leave it empty and set build_scope.mode: "partial" in the map, which takes every page without a design_source out of source scope so the build copies it from the family; a page that keeps a design_source still needs its source or an explicit manifest skip_reason (template-stock pages).
    source
    mkdir -p source

  7. Run start.

    start writes the Build Packet (campaign-runtime.build.json, read by every later stage) and runtime files into the folder, opens a run session, and by default sends its Run Record to NEXT's telemetry endpoint; npx campaigns-os telemetry off first keeps it local.
    start
    npx campaigns-os start --map-id <map-id> --target . --source ./source --template-family <family>

    Add --proxy-base <origin> when the map was saved on a non-production map store. After a fresh scaffold the first readiness check names two routine blockers: _data/campaigns.json still carries the template's demo store profile and SDK version. Replace them with the map's values (your agent's next-campaigns-os skill, step 5, does this), then run next again. For source blocks see clearing the readiness block.

  8. Install the browser, then hand the folder to your agent.

    Polish capture and QA drive Chromium; install it once. Open the folder in Claude Code or Codex and have the agent run next after every stage, following the skill it names (setup → build → polish → preview → QA). Prefix commands it prints that begin with campaigns-os with npx; for the browser install and QA use this page's commands (the toolkit at this pin prints a checkout-only npm run qa:install-browser); to re-run intake, re-run the full start line above.

    next
    npx playwright install chromium
npx campaigns-os next --packet ./campaign-runtime.build.json --json

    QA against the deployed preview: npx campaigns-os qa run --packet ./campaign-runtime.build.json --base-url "<preview-url>" --browser --test-order common --post-verdict. common samples the usual checkout paths; full follows every terminal offer path from the selected checkout; tiers:full adds each declared package tier. Stage reports land under .campaign-runtime/; posting the verdict to your Map ID is attempted.

The template pages' npx campaign-init quick start is step 3 here. Contributors on a toolkit checkout replace npx campaigns-os with npm run campaigns-os -- and the browser install with npm run qa:install-browser.

Next step

Get your Map ID, then copy the start prompt.

Open Workspace Browse templates