Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
import fs from 'node:fs'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import * as p from '@clack/prompts'
import type { Command } from 'commander'
import { execa } from 'execa'
import pc from 'picocolors'
import { isNotFound } from '../config.js'
import { DASHBOARD_PORT, SELLER_DASHBOARD_PORT } from '../constants.js'
import { detectProject } from '../context.js'
import {
AGENT_SKILLS_REPO,
addDocsMcpServer,
addDocsSectionToAgentInstructions,
dlxCommand,
installAgentSkills,
} from '../lib/ai.js'
import {
EXTENSIONS,
extensionNames,
isValidGemName,
isValidNpmName,
resolveExtension,
} from '../lib/extensions.js'
import { confirmOrExit } from '../lib/prompt.js'
import type { ProjectContext } from '../types.js'
import { type AddExtensionOptions, addExtension } from './add-extension.js'
/**
* The two admin SPAs `spree add` can scaffold. They differ only in where they
* live, which bundled template they come from, and which port they serve on —
* everything else (env file, install, recovery) is identical, so they share
* one implementation rather than two that drift.
*/
interface AppSpec {
/** Directory under `apps/`. */
dir: string
/** Template directory name inside the CLI's bundled `templates/`. */
template: string
/** Env var overriding the bundled template. */
templateEnvVar: string
/** Dev-server port, for the closing summary. */
port: number
/** Human name used in prompts and messages. */
label: string
}
const APPS: Record<string, AppSpec> = {
dashboard: {
dir: 'dashboard',
template: 'dashboard-starter',
templateEnvVar: 'SPREE_DASHBOARD_TEMPLATE',
port: DASHBOARD_PORT,
label: 'Dashboard',
},
'seller-dashboard': {
dir: 'seller-dashboard',
template: 'seller-dashboard-starter',
templateEnvVar: 'SPREE_SELLER_DASHBOARD_TEMPLATE',
port: SELLER_DASHBOARD_PORT,
label: 'Seller Panel',
},
}
interface AddDashboardOptions {
/** Git URL or local directory to copy the starter from. */
template: string
/** Run the package-manager install after scaffolding. */
install: boolean
/** Skip the final summary note — create-spree-app prints its own. */
quiet?: boolean
}
interface AddAiOptions {
/** Install the Spree agent skills. */
skills: boolean
/** Connect coding agents to the Spree docs MCP server. */
mcp: boolean
/** Skip the final summary note — create-spree-app prints its own. */
quiet?: boolean
}
// `spree add <thing>` — bolt an optional component or an extension onto an
// existing project. Components (dashboard, seller panel, AI coding agent
// setup) are built in; extensions come from the catalog in extensions.json
// (see docs/plans/6.0-cli-add-extensions.md).
export function registerAddCommand(program: Command) {
program
.command('add')
.description('Add an optional component or an extension to your project')
.argument(
'[thing]',
`Component (dashboard, seller-dashboard, ai) or extension (${extensionNames().join(', ')})`,
)
.option('--gem <name>', 'Install a gem that is not in the extension catalog')
.option('--npm <package>', 'Install a dashboard plugin that is not in the extension catalog')
.option('-y, --yes', 'Agree to ejecting the project and to installing outside the catalog')
.option(
'--template <src>',
'Starter template: git URL or local path (default: the template bundled with the CLI; env SPREE_DASHBOARD_TEMPLATE / SPREE_SELLER_DASHBOARD_TEMPLATE overrides)',
)
.option('--no-install', 'Skip dependency install')
.option('--no-skills', 'ai: skip installing the Spree agent skills')
.option('--no-mcp', 'ai: skip connecting coding agents to the Spree docs MCP server')
.option('--quiet', 'Skip the final summary note (for wrapping tools that print their own)')
.action(
async (
thing: string | undefined,
flags: {
template?: string
install: boolean
skills: boolean
mcp: boolean
quiet?: boolean
gem?: string
npm?: string
yes?: boolean
},
) => {
if (flags.gem || flags.npm) {
if (thing) usageError('Pass either a name or --gem/--npm, not both.')
await addUncataloguedExtension(flags.gem, flags.npm, { yes: Boolean(flags.yes) })
return
}
if (!thing) usageError('Name a component or an extension to add.')
if (thing === 'ai') {
if (!flags.quiet) p.intro(pc.bgCyan(pc.black(' Spree AI coding agents ')))
const ready = await addAi(detectProject(), flags)
if (!flags.quiet) p.outro(ready ? 'Done!' : 'Done, with warnings.')
if (!ready) process.exit(1)
return
}
const app = Object.hasOwn(APPS, thing) ? APPS[thing] : undefined
if (!app) {
const extension = resolveExtension(thing)
if (!extension) {
usageError(
[
`Unknown component or extension: ${thing}.`,
`Components: ${[...Object.keys(APPS), 'ai'].join(', ')}`,
`Extensions: ${extensionNames().join(', ')}`,
`For a gem that is not listed, use ${pc.bold('spree add --gem <name>')}.`,
].join('\n'),
)
}
p.intro(pc.bgCyan(pc.black(` Spree ${extension.label} `)))
await addExtension(detectProject(), extension, { yes: Boolean(flags.yes) })
p.outro('Done!')
return
}
p.intro(pc.bgCyan(pc.black(` Spree ${app.label} `)))
const ctx = detectProject()
await addApp(ctx, app, {
template:
flags.template ?? process.env[app.templateEnvVar] ?? resolveBundledTemplate(app),
install: flags.install,
quiet: flags.quiet,
})
p.outro('Done!')
},
)
}
function usageError(message: string): never {
console.error(`\n${pc.red('Error:')} ${message}\n`)
process.exit(2)
}
/**
* Install a gem or dashboard plugin named on the command line rather than
* through the catalog. Names are checked so neither can be read as a flag,
* and the developer confirms, since nothing vouches for the package.
*/
async function addUncataloguedExtension(
gem: string | undefined,
npm: string | undefined,
opts: AddExtensionOptions,
): Promise<void> {
if (gem && !isValidGemName(gem)) usageError(`Not a valid gem name: ${gem}`)
if (npm && !isValidNpmName(npm)) usageError(`Not a valid npm package name: ${npm}`)
// An official gem named with --gem still installs as the catalog says
// (pinned to the Spree version where it is released with Spree).
const catalogued = Object.values(EXTENSIONS).find((entry) => entry.gem === gem)
const uncatalogued = [catalogued ? undefined : gem, npm].filter(Boolean)
const label = catalogued?.label ?? uncatalogued.join(' and ')
p.intro(pc.bgCyan(pc.black(` ${label} `)))
if (uncatalogued.length > 0) {
await confirmOrExit(
`${uncatalogued.join(' and ')} ${uncatalogued.length > 1 ? 'are' : 'is'} not in the Spree extension catalog. Install anyway?`,
opts.yes,
)
}
await addExtension(
detectProject(),
{ ...catalogued, label, gem, dashboard: npm ?? catalogued?.dashboard },
opts,
)
p.outro('Done!')
}
/**
* Set a project up for AI coding agents: connect each agent to the Spree docs
* MCP server, point the agent instructions at it, and install the Spree agent
* skills. Safe to re-run — servers already configured are kept as they are.
*
* @return false when a step failed and the project is only partly set up
*/
export async function addAi(ctx: ProjectContext, opts: AddAiOptions): Promise<boolean> {
let ready = true
if (opts.mcp) {
const outcomes = addDocsMcpServer(ctx.projectDir)
for (const [file, outcome] of Object.entries(outcomes)) {
if (outcome === 'unreadable' || outcome === 'unwritable') {
ready = false
p.log.warn(
`Could not ${outcome === 'unreadable' ? 'read' : 'write'} ${pc.bold(file)}${outcome === 'unreadable' ? ' as JSON' : ''}, so it was left as it is. Add the server by hand: https://spreecommerce.org/docs/developer/agentic/mcp`,
)
} else if (!opts.quiet) {
p.log.info(
outcome === 'added'
? `Added the Spree docs MCP server to ${pc.bold(file)}`
: `${pc.bold(file)} already lists the Spree docs MCP server`,
)
}
}
const instructions = addDocsSectionToAgentInstructions(ctx.projectDir)
for (const file of instructions.updated) {
if (!opts.quiet) p.log.info(`Pointed ${pc.bold(file)} at the Spree docs MCP server`)
}
for (const file of instructions.failed) {
ready = false
p.log.warn(`Could not update ${pc.bold(file)}, so agents may not know about the docs server.`)
}
}
if (opts.skills) {
const packageManager = detectPackageManager(ctx.projectDir, ctx.projectDir)
const s = p.spinner()
s.start('Installing Spree agent skills...')
try {
await installAgentSkills(ctx.projectDir, packageManager)
s.stop('Spree agent skills installed.')
} catch (err) {
ready = false
s.stop(pc.yellow('Spree agent skills were not installed.'))
p.log.warn(
`Install them later with ${pc.bold(`${dlxCommand(packageManager).join(' ')} skills add ${AGENT_SKILLS_REPO}`)}.\n${err instanceof Error ? err.message : String(err)}`,
)
}
}
if (!opts.quiet && opts.mcp) {
p.note(
[
'Claude Code asks you to approve the docs server the first time you open',
'the project; Cursor and VS Code list it in their MCP settings.',
'Commit the new files so your team gets the same setup.',
].join('\n'),
'AI coding agents set up',
)
}
return ready
}
/**
* Clone the dashboard starter into `apps/dashboard/` and point it at the
* project's API. Writes no credentials — the dashboard authenticates admins
* interactively (email/password → JWT + refresh cookie), and `VITE_`-prefixed
* env values are compiled into the client bundle, so a key here would ship
* to every browser.
*
* Idempotent: an existing `apps/<dir>/` is left untouched (recovery mode
* rewrites a missing `.env.local` only).
*/
export async function addApp(
ctx: ProjectContext,
app: AppSpec,
opts: AddDashboardOptions,
): Promise<void> {
const appDir = path.join(ctx.projectDir, 'apps', app.dir)
const envPath = path.join(appDir, '.env.local')
if (fs.existsSync(appDir)) {
// Recovery: write a missing .env.local (interrupted earlier run) or
// repair a broken one (old scaffold output) — one gatekeeper for both.
const env = ensureAppDevEnv(ctx.projectDir, app.dir, ctx.port)
if (env === 'untouched') {
p.log.warn(`${pc.bold(`apps/${app.dir}/`)} already exists. Nothing to do.`)
return
}
p.log.info(
`${env === 'written' ? 'Wrote missing' : 'Repaired'} ${pc.bold(`apps/${app.dir}/.env.local`)}. Nothing else to do.`,
)
return
}
const s = p.spinner()
s.start(`Fetching ${app.label.toLowerCase()} starter...`)
try {
await fetchTemplate(opts.template, appDir)
restoreGitignore(appDir)
} catch (err) {
s.stop('Fetch failed.')
p.log.error(err instanceof Error ? err.message : String(err))
process.exit(1)
}
s.stop(`Created ${pc.cyan(`apps/${app.dir}/`)}`)
writeDashboardEnv(envPath, ctx.port)
const pm = detectPackageManager(ctx.projectDir, appDir)
if (opts.install) {
s.start(`Installing dependencies with ${pm}...`)
try {
await execa(pm, ['install'], { cwd: appDir })
s.stop('Dependencies installed.')
await generateRouteTree(appDir)
} catch (err) {
s.stop(pc.yellow(`${pm} install failed — run it manually in apps/${app.dir}/.`))
p.log.warn(err instanceof Error ? err.message : String(err))
}
}
if (opts.quiet) return
p.note(
[
`Start it with:`,
` ${pc.cyan(`${pm === 'npm' ? 'npx' : pm} spree dev`)}`,
` ${pc.dim('# runs the API and the dashboard together')}`,
...(opts.install
? []
: [` ${pc.dim(`# install dependencies first: cd apps/${app.dir} && ${pm} install`)}`]),
'',
`Then open ${pc.bold(`http://localhost:${app.port}`)} and sign in.`,
].join('\n'),
`${app.label} added!`,
)
}
/**
* A starter template bundled inside this package. Generated at build time
* from the monorepo's `packages/<name>` (workspace deps rewritten to the
* published versions — see `scripts/sync-starter.mjs`) and shipped in
* `dist/templates/`. Bundling them with the CLI keeps each template and the
* `@spree/*` versions it pins in lockstep with every release — there is no
* separate template repo to drift.
*/
function resolveBundledTemplate(app: AppSpec): string {
const here = path.dirname(fileURLToPath(import.meta.url))
// dev: src/commands/add.ts → ../../templates/<name>
// built: dist/index.js → dist/templates/<name>
const candidates = [
path.resolve(here, '../../templates', app.template),
path.resolve(here, 'templates', app.template),
]
for (const candidate of candidates) {
if (fs.existsSync(path.join(candidate, 'package.json'))) return candidate
}
console.error(
`\n${pc.red('Error:')} Bundled ${app.label.toLowerCase()} template not found. In the monorepo, ` +
`run ${pc.cyan('pnpm build')} in packages/cli first (it generates the templates), ` +
'or pass --template <path|git-url>.\n',
)
process.exit(1)
}
/**
* Writes the app's `src/routeTree.gen.ts` for the packages just installed.
*
* The template's copy was generated in the monorepo, so the first dev start
* would rewrite it — and Vite reloads the open page when it notices, which is
* the setup screen a new project opens straight into. Loading the app's own
* Vite config runs the same generator, with the same extensions, without
* starting a server, so that first start finds nothing to change.
*/
export async function generateRouteTree(appDir: string): Promise<void> {
// Best effort: the dev server generates the file on start regardless.
await execa(
'node',
[
'--input-type=module',
'-e',
"const { resolveConfig } = await import('vite'); await resolveConfig({}, 'serve')",
],
{ cwd: appDir, reject: false },
)
}
/**
* The bundled template ships its `.gitignore` as `gitignore.template`
* (npm never packs `.gitignore` files) — restore the real name on scaffold.
*/
function restoreGitignore(dir: string): void {
const template = path.join(dir, 'gitignore.template')
if (fs.existsSync(template)) fs.renameSync(template, path.join(dir, '.gitignore'))
}
/** Git-clone a URL template, or copy a local directory (used in tests/CI). */
async function fetchTemplate(template: string, dst: string): Promise<void> {
if (fs.existsSync(template) && fs.statSync(template).isDirectory()) {
fs.cpSync(template, dst, {
recursive: true,
filter: (src) => {
const base = path.basename(src)
return base !== 'node_modules' && base !== 'dist' && base !== '.git'
},
})
return
}
await execa('git', ['clone', '--depth', '1', '--', template, dst])
fs.rmSync(path.join(dst, '.git'), { recursive: true, force: true })
}
// Old scaffolds wrote the SDK's absolute-URL switch pointed at localhost —
// requests then bypassed the dev proxy and died on CORS + the SameSite=Lax
// cookie. A localhost value can only be that scaffold output, never a real
// cross-origin production URL, so it's safe to migrate in place.
const BROKEN_SCAFFOLD_ENV = /^VITE_SPREE_API_URL=(https?:\/\/localhost\S*)$/m
/**
* Writes or repairs `apps/dashboard/.env.local` so dashboard dev works out
* of the box. Idempotent and cheap — called from `spree add dashboard`,
* first-run setup, and every `spree dev` boot, covering fresh clones (the
* file is gitignored) and old scaffolds (see {@link BROKEN_SCAFFOLD_ENV};
* only that line is rewritten — everything else in the file is user-managed
* and preserved).
*/
export function ensureAppDevEnv(
projectDir: string,
appDirName: string,
port: number,
): 'written' | 'repaired' | 'untouched' {
const appDir = path.join(projectDir, 'apps', appDirName)
if (!fs.existsSync(path.join(appDir, 'package.json'))) return 'untouched'
const envPath = path.join(appDir, '.env.local')
let existing: string
try {
existing = fs.readFileSync(envPath, 'utf-8')
} catch (error) {
if (!isNotFound(error)) throw error // unreadable ≠ missing — never clobber
writeDashboardEnv(envPath, port)
return 'written'
}
if (!BROKEN_SCAFFOLD_ENV.test(existing)) return 'untouched'
fs.writeFileSync(
envPath,
existing.replace(BROKEN_SCAFFOLD_ENV, `VITE_API_PROXY_TARGET=http://localhost:${port}`),
)
return 'repaired'
}
/** Every SPA under `apps/` that `spree dev` and first-run setup keep in sync. */
export const APP_DIRS = Object.values(APPS).map((app) => app.dir)
/**
* Refresh the dev env file for every scaffolded SPA. Apps that aren't present
* report 'untouched', so this is safe to call unconditionally.
*/
export function ensureDashboardDevEnv(
projectDir: string,
port: number,
): 'written' | 'repaired' | 'untouched' {
let result: 'written' | 'repaired' | 'untouched' = 'untouched'
for (const dir of APP_DIRS) {
const outcome = ensureAppDevEnv(projectDir, dir, port)
if (outcome !== 'untouched') result = outcome
}
return result
}
function writeDashboardEnv(envPath: string, port: number): void {
fs.writeFileSync(
envPath,
[
'# Dev-server proxy target — where Vite forwards /api and /rails (your',
'# Rails backend). The SPA stays same-origin with the API: the SDK uses',
'# relative URLs and the proxy bridges the port gap.',
'#',
'# Do NOT set VITE_SPREE_API_URL for local dev — it switches the SDK to',
'# absolute cross-origin URLs, which breaks on CORS and the SameSite=Lax',
'# auth cookie. Set it only when building for a deploy where the',
'# dashboard is hosted on a different origin than the API.',
'#',
'# No credentials belong in this file — every VITE_-prefixed value is',
'# compiled into the client bundle.',
`VITE_API_PROXY_TARGET=http://localhost:${port}`,
'',
].join('\n'),
)
}
/** Prefer the project's own package manager (by lockfile); default to pnpm. */
export function detectPackageManager(projectDir: string, appDir: string): string {
for (const dir of [appDir, projectDir]) {
if (fs.existsSync(path.join(dir, 'pnpm-lock.yaml'))) return 'pnpm'
if (fs.existsSync(path.join(dir, 'yarn.lock'))) return 'yarn'
if (fs.existsSync(path.join(dir, 'package-lock.json'))) return 'npm'
}
return 'pnpm'
}