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
Default new create-spree-app projects to pnpm
Damian Legawiec4de684c07d0e
diff --git a/packages/create-spree-app/.changeset/dashboard-scaffold-phase.md b/packages/create-spree-app/.changeset/dashboard-scaffold-phase.mdindex 0ea1d6eaa4..71f670e4a7 100644--- a/packages/create-spree-app/.changeset/dashboard-scaffold-phase.md+++ b/packages/create-spree-app/.changeset/dashboard-scaffold-phase.md@@ -4,6 +4,14 @@Offer the React Dashboard (Developer Preview) as an optional component: a newprompt (and `--no-dashboard` flag) scaffolds it into `apps/dashboard/` by-delegating to the project-local `npx spree add dashboard` (the CLI bundles the+delegating to the project-local `spree add dashboard` (the CLI bundles thestarter template with version pins matching its release), and wires theREADME, CLAUDE.md, and Dependabot config.++New projects now default to **pnpm** when it's installed — it's what the+Spree packages and docs are built around. An explicit invoking agent+(`pnpm create spree-app`, `yarn create spree-app`) and the+`--use-npm`/`--use-yarn`/`--use-pnpm` flags still win, and npm remains the+fallback when pnpm is absent. The generated README, CLAUDE.md, and next-steps+output now render commands for the chosen package manager instead of+hardcoding npm.diff --git a/packages/create-spree-app/src/dashboard.ts b/packages/create-spree-app/src/dashboard.tsindex d1e9de80b3..b9c372a59f 100644--- a/packages/create-spree-app/src/dashboard.ts+++ b/packages/create-spree-app/src/dashboard.ts@@ -1,8 +1,10 @@import { execa } from 'execa'+import type { PackageManager } from './types.js'+import { runCommand } from './utils.js'/*** Scaffold the React Dashboard into `apps/dashboard/` by delegating to the- * project-local CLI: `npx spree add dashboard`. The generated project already+ * project-local CLI: `spree add dashboard`. The generated project already* depends on `@spree/cli` (installed with the root deps, before this phase),* and the CLI bundles the dashboard-starter template with version pins* matching its release — one template source, no copy in this package. The@@ -11,9 +13,9 @@ import { execa } from 'execa'*/export async function scaffoldDashboard(projectDir: string,- opts: { install: boolean },+ opts: { install: boolean; packageManager: PackageManager },): Promise<void> {const args = ['spree', 'add', 'dashboard']if (!opts.install) args.push('--no-install')- await execa('npx', args, { cwd: projectDir, stdio: 'inherit' })+ await execa(runCommand(opts.packageManager), args, { cwd: projectDir, stdio: 'inherit' })}diff --git a/packages/create-spree-app/src/index.ts b/packages/create-spree-app/src/index.tsindex bd6e6ff4d0..8adb441bfc 100644--- a/packages/create-spree-app/src/index.ts+++ b/packages/create-spree-app/src/index.ts@@ -23,10 +23,15 @@ const program = new Command().action(async (directory: string | undefined, flags: Record<string, unknown>) => {p.intro(pc.bold('Create Spree App'))- let packageManager: PackageManager = detectPackageManager()+ let packageManager: PackageManager = await detectPackageManager()if (flags.useNpm) packageManager = 'npm'if (flags.useYarn) packageManager = 'yarn'if (flags.usePnpm) packageManager = 'pnpm'+ if (packageManager === 'npm' && !flags.useNpm) {+ p.log.info(+ `Using npm (pnpm not found — run ${pc.cyan('corepack enable')} to get pnpm, which Spree recommends).`,+ )+ }try {const options = await runPrompts({diff --git a/packages/create-spree-app/src/scaffold.ts b/packages/create-spree-app/src/scaffold.tsindex 7174a334a3..ac9db899e1 100644--- a/packages/create-spree-app/src/scaffold.ts+++ b/packages/create-spree-app/src/scaffold.ts@@ -18,8 +18,14 @@ import { envContent } from './templates/env.js'import { gitignoreContent } from './templates/gitignore.js'import { rootPackageJsonContent } from './templates/package-json.js'import { readmeContent } from './templates/readme.js'-import type { ScaffoldOptions } from './types.js'-import { generateSecretKeyBase, isDockerRunning } from './utils.js'+import type { PackageManager, ScaffoldOptions } from './types.js'+import {+ dlxCommand,+ generateSecretKeyBase,+ installCommand,+ isDockerRunning,+ runCommand,+} from './utils.js'export async function scaffold(options: ScaffoldOptions): Promise<void> {const projectDir = path.resolve(options.directory)@@ -82,10 +88,13 @@ export async function scaffold(options: ScaffoldOptions): Promise<void> {fs.writeFileSync(path.join(projectDir, 'package.json'), rootPackageJsonContent(projectName))fs.writeFileSync(path.join(projectDir, 'README.md'),- readmeContent(projectName, storefront, port, dashboard),+ readmeContent(projectName, storefront, port, dashboard, options.packageManager),)fs.writeFileSync(path.join(projectDir, '.gitignore'), gitignoreContent())- fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), rootClaudeMdContent(storefront, dashboard))+ fs.writeFileSync(+ path.join(projectDir, 'CLAUDE.md'),+ rootClaudeMdContent(storefront, dashboard, options.packageManager),+ )fs.writeFileSync(path.join(projectDir, 'AGENTS.md'), agentsMdContent())const githubDir = path.join(projectDir, '.github')@@ -117,7 +126,7 @@ export async function scaffold(options: ScaffoldOptions): Promise<void> {// (root deps, above) and bundles the dashboard-starter template. It reads// the port from the project's .env and prints its own progress.if (dashboard) {- await scaffoldDashboard(projectDir, { install: true })+ await scaffoldDashboard(projectDir, { install: true, packageManager: options.packageManager })}// Phase 4: Initialize and start services@@ -125,23 +134,23 @@ export async function scaffold(options: ScaffoldOptions): Promise<void> {const initArgs = ['spree', 'init']if (!options.sampleData) initArgs.push('--no-sample-data')- await execa('npx', initArgs, {+ await execa(runCommand(options.packageManager), initArgs, {cwd: projectDir,stdio: 'inherit',})if (storefront) {p.log.info(- `${pc.bold('Storefront')}: ${pc.cyan(`cd ${projectName}/apps/storefront && npm run dev`)}`,+ `${pc.bold('Storefront')}: ${pc.cyan(`cd ${projectName}/apps/storefront && ${options.packageManager} run dev`)}`,)}if (dashboard) {p.log.info(- `${pc.bold('React Dashboard')}: ${pc.cyan(`cd ${projectName}/apps/dashboard && npm run dev`)} → http://localhost:${DASHBOARD_PORT}`,+ `${pc.bold('React Dashboard')}: ${pc.cyan(`cd ${projectName}/apps/dashboard && ${options.packageManager} run dev`)} → http://localhost:${DASHBOARD_PORT}`,)}} else {- printSuccessWithoutDocker(projectName, storefront, dashboard, port)+ printSuccessWithoutDocker(projectName, storefront, dashboard, port, options.packageManager)}}@@ -150,12 +159,14 @@ function printSuccessWithoutDocker(hasStorefront: boolean,hasDashboard: boolean,port: number,+ pm: PackageManager,): void {+ const run = runCommand(pm)const lines: string[] = ['',`${pc.bold('Next steps:')}`,` cd ${projectName}`,- ` npx spree dev`,+ ` ${run} spree dev`,]if (hasStorefront) {@@ -163,8 +174,8 @@ function printSuccessWithoutDocker('',` ${pc.dim('# In another terminal:')}`,` cd ${projectName}/apps/storefront`,- ` npm install`,- ` npm run dev`,+ ` ${installCommand(pm)}`,+ ` ${pm} run dev`,)}@@ -173,8 +184,8 @@ function printSuccessWithoutDocker('',` ${pc.dim('# React Dashboard (Developer Preview), in another terminal:')}`,` cd ${projectName}/apps/dashboard`,- ` npm install`,- ` npm run dev`,+ ` ${installCommand(pm)}`,+ ` ${pm} run dev`,)}@@ -186,11 +197,11 @@ function printSuccessWithoutDocker(` Password: ${DEFAULT_ADMIN_PASSWORD}`,'',`${pc.bold('Customize the backend')}`,- ` npx spree eject`,+ ` ${run} spree eject`,` ${pc.dim('# Then edit backend/Gemfile, backend/app/, backend/config/')}`,'',`${pc.bold('Agent skills (optional)')}`,- ` npx skills add spree/agent-skills`,+ ` ${dlxCommand(pm)} skills add spree/agent-skills`,` ${pc.dim('# Adds 23 Spree skills to whichever AI agent(s) you use')}`,` ${pc.dim('# (Claude Code, Codex, Cursor, Copilot, Cline, Aider, +60 others)')}`,'',diff --git a/packages/create-spree-app/src/templates/claude-md.ts b/packages/create-spree-app/src/templates/claude-md.tsindex 82b305ebf2..e56580b963 100644--- a/packages/create-spree-app/src/templates/claude-md.ts+++ b/packages/create-spree-app/src/templates/claude-md.ts@@ -1,3 +1,6 @@+import type { PackageManager } from '../types.js'+import { runCommand } from '../utils.js'+export function agentsMdContent(): string {return `# Agent Instructions@@ -19,7 +22,12 @@ full skill list.`}-export function rootClaudeMdContent(hasStorefront: boolean, hasDashboard = false): string {+export function rootClaudeMdContent(+ hasStorefront: boolean,+ hasDashboard = false,+ pm: PackageManager = 'npm',+): string {+ const run = runCommand(pm)const lines = ['# Spree Commerce Application','',@@ -90,25 +98,25 @@ export function rootClaudeMdContent(hasStorefront: boolean, hasDashboard = false'inspect live data instead of guessing at the schema:','','```bash',- 'npx spree api get products # list products',- 'npx spree api get "orders?q[state_eq]=complete" # Ransack filters',- 'npx spree api endpoints # every endpoint + its required scope',- 'npx spree api schema "POST /products" # request/response schema for an operation',+ `${run} spree api get products # list products`,+ `${run} spree api get "orders?q[state_eq]=complete" # Ransack filters`,+ `${run} spree api endpoints # every endpoint + its required scope`,+ `${run} spree api schema "POST /products" # request/response schema for an operation`,'```','','The default key is read-only. For writes, create a scoped key and pass it via',- '`SPREE_API_KEY`: `npx spree api-key create --scopes write_products`, then',- '`SPREE_API_KEY=sk_... npx spree api post products --data \'{"name":"New product","prices":[{"currency":"USD","amount":"29.99"}]}\'`.',+ `\`SPREE_API_KEY\`: \`${run} spree api-key create --scopes write_products\`, then`,+ `\`SPREE_API_KEY=sk_... ${run} spree api post products --data '{"name":"New product","prices":[{"currency":"USD","amount":"29.99"}]}'\`.`,'','## Common Commands','','```bash',- 'npm run dev # Start backend (Docker)',- 'npm run stop # Stop services',- 'npm run console # Rails console',- 'npm run logs # Backend logs',- 'npx spree api get products # Query the Admin API (read-only key preconfigured)',- 'npx spree eject # Switch to local backend builds',+ `${pm} run dev # Start backend (Docker)`,+ `${pm} run stop # Stop services`,+ `${pm} run console # Rails console`,+ `${pm} run logs # Backend logs`,+ `${run} spree api get products # Query the Admin API (read-only key preconfigured)`,+ `${run} spree eject # Switch to local backend builds`,'```','',)diff --git a/packages/create-spree-app/src/templates/readme.ts b/packages/create-spree-app/src/templates/readme.tsindex 72bfce1c5f..06952c23dc 100644--- a/packages/create-spree-app/src/templates/readme.ts+++ b/packages/create-spree-app/src/templates/readme.ts@@ -4,13 +4,17 @@ import {DEFAULT_ADMIN_PASSWORD,STOREFRONT_PORT,} from '../constants.js'+import type { PackageManager } from '../types.js'+import { globalAddCommand, runCommand } from '../utils.js'export function readmeContent(name: string,hasStorefront: boolean,port: number,hasDashboard = false,+ pm: PackageManager = 'npm',): string {+ const run = runCommand(pm)let content = `# ${name}A [Spree Commerce](https://spreecommerce.org) project.@@ -25,7 +29,7 @@ A [Spree Commerce](https://spreecommerce.org) project.\`\`\`bashcd ${name}-npx spree dev+${run} spree dev\`\`\`Wait for the services to be healthy, then open:@@ -44,7 +48,7 @@ Dependencies are already installed during setup — just start it:\`\`\`bashcd apps/storefront-npm run dev+${pm} run dev\`\`\`Open http://localhost:${STOREFRONT_PORT}@@ -64,7 +68,7 @@ Dependencies are already installed during setup — just start it:\`\`\`bashcd apps/dashboard-npm run dev+${pm} run dev\`\`\`Open http://localhost:${DASHBOARD_PORT} and sign in with the admin email and password above.@@ -80,7 +84,7 @@ To learn how to add pages, tweak tables, or build plugins, see theThe \`backend/\` directory contains a full Rails application with Spree installed. By default, the project uses a prebuilt Docker image. To switch to building from your local backend:\`\`\`bash-npx spree eject+${run} spree eject\`\`\`This rebuilds the Docker image from \`backend/\` and restarts services. You can then:@@ -136,17 +140,17 @@ This project uses [\`@spree/cli\`](https://spreecommerce.org/docs/developer/cli/Project setup mints a read-only secret key into \`.spree/credentials.json\` (gitignored), so the Admin API client works out of the box. If you skipped the setup step, \`spree api\` mints the key on first use instead:\`\`\`bash-npx spree api get products-npx spree api get "orders?q[state_eq]=complete"-npx spree api endpoints # list endpoints + required scopes-npx spree api status # show resolved credentials + server reachability+${run} spree api get products+${run} spree api get "orders?q[state_eq]=complete"+${run} spree api endpoints # list endpoints + required scopes+${run} spree api status # show resolved credentials + server reachability\`\`\`The pre-configured key is read-only. To write, create a scoped secret key and pass it via \`SPREE_API_KEY\`:\`\`\`bash-npx spree api-key create --scopes write_products-SPREE_API_KEY=sk_... npx spree api post products --data '{"name":"New product","prices":[{"currency":"USD","amount":"29.99"}]}'+${run} spree api-key create --scopes write_products+SPREE_API_KEY=sk_... ${run} spree api post products --data '{"name":"New product","prices":[{"currency":"USD","amount":"29.99"}]}'\`\`\`| Command | Description |@@ -155,10 +159,10 @@ SPREE_API_KEY=sk_... npx spree api post products --data '{"name":"New product","| \`spree api endpoints\` | List Admin API endpoints with required scopes || \`spree auth login --profile <name>\` | Save named credentials for a remote store |-> **Running \`spree\` directly.** The commands above use \`npx\` because \`@spree/cli\` is a local project dependency. You can also run any of the package scripts (e.g. \`npm run api -- get products\`), or install the CLI globally for a bare \`spree\` command:+> **Running \`spree\` directly.** The commands above use \`${run}\` because \`@spree/cli\` is a local project dependency. You can also run any of the package scripts (e.g. \`${pm} run api -- get products\`), or install the CLI globally for a bare \`spree\` command:>> \`\`\`bash-> npm install -g @spree/cli+> ${globalAddCommand(pm)} @spree/cli> spree api get products> \`\`\`diff --git a/packages/create-spree-app/src/utils.ts b/packages/create-spree-app/src/utils.tsindex 2d3241d75e..667cc64837 100644--- a/packages/create-spree-app/src/utils.ts+++ b/packages/create-spree-app/src/utils.ts@@ -1,12 +1,31 @@import crypto from 'node:crypto'-import { execaCommand } from 'execa'+import { execa, execaCommand } from 'execa'import type { PackageManager } from './types.js'-export function detectPackageManager(): PackageManager {+/**+ * Pick the package manager for the generated project. An explicit invoking+ * agent wins (`pnpm create spree-app` → pnpm, `yarn create` → yarn).+ * Otherwise — including plain `npx create-spree-app`, where the npm user+ * agent signals the default runner rather than a choice — prefer pnpm when+ * it's installed: it's what the Spree packages and docs are built around+ * (strict peer resolution, single-instance dedupe). Fall back to npm when+ * pnpm isn't available; `--use-npm`/`--use-yarn`/`--use-pnpm` override+ * everything.+ */+export async function detectPackageManager(): Promise<PackageManager> {const agent = process.env.npm_config_user_agent ?? ''if (agent.startsWith('yarn')) return 'yarn'if (agent.startsWith('pnpm')) return 'pnpm'- return 'npm'+ return (await isPnpmAvailable()) ? 'pnpm' : 'npm'+}++async function isPnpmAvailable(): Promise<boolean> {+ try {+ await execa('pnpm', ['--version'], { stdio: 'ignore' })+ return true+ } catch {+ return false+ }}export async function isDockerRunning(): Promise<boolean> {@@ -26,8 +45,23 @@ export function installCommand(pm: PackageManager): string {return pm === 'yarn' ? 'yarn' : `${pm} install`}+/** Runner for a locally-installed bin (e.g. `npx spree`, `pnpm spree`). */export function runCommand(pm: PackageManager): string {if (pm === 'npm') return 'npx'if (pm === 'yarn') return 'yarn'return 'pnpm'}++/** Runner for a one-off remote package (e.g. `npx skills`, `pnpm dlx skills`). */+export function dlxCommand(pm: PackageManager): string {+ if (pm === 'npm') return 'npx'+ if (pm === 'yarn') return 'yarn dlx'+ return 'pnpm dlx'+}++/** Global-install command for a package (e.g. `npm install -g`, `pnpm add -g`). */+export function globalAddCommand(pm: PackageManager): string {+ if (pm === 'npm') return 'npm install -g'+ if (pm === 'yarn') return 'yarn global add'+ return 'pnpm add -g'+}diff --git a/packages/create-spree-app/tests/scaffold.test.ts b/packages/create-spree-app/tests/scaffold.test.tsindex 352298be16..81b056f1cc 100644--- a/packages/create-spree-app/tests/scaffold.test.ts+++ b/packages/create-spree-app/tests/scaffold.test.ts@@ -235,7 +235,10 @@ describe('scaffold (no-start)', () => {port: 4567,})- expect(scaffoldDashboard).toHaveBeenCalledWith(projectDir, { install: true })+ expect(scaffoldDashboard).toHaveBeenCalledWith(projectDir, {+ install: true,+ packageManager: 'npm',+ })expect(fs.readFileSync(path.join(projectDir, 'README.md'), 'utf-8')).toContain('React Dashboard',)diff --git a/packages/create-spree-app/tests/templates.test.ts b/packages/create-spree-app/tests/templates.test.tsindex c6072f3cf2..28d67f6f8b 100644--- a/packages/create-spree-app/tests/templates.test.ts+++ b/packages/create-spree-app/tests/templates.test.ts@@ -134,6 +134,15 @@ describe('readmeContent', () => {expect(content).toContain('npm install -g @spree/cli')})+ it('renders commands for the chosen package manager', () => {+ const content = readmeContent('my-store', true, 3000, true, 'pnpm')+ expect(content).toContain('pnpm spree dev')+ expect(content).toContain('pnpm run dev')+ expect(content).toContain('pnpm add -g @spree/cli')+ expect(content).not.toContain('npx')+ expect(content).not.toMatch(/\bnpm /)+ })+it('includes the React Dashboard section when included', () => {const content = readmeContent('my-store', true, 3000, true)expect(content).toContain('### Start the React Dashboard (Developer Preview)')@@ -154,6 +163,13 @@ describe('rootClaudeMdContent', () => {expect(content).toContain('docs/developer/dashboard')})+ it('renders commands for the chosen package manager', () => {+ const content = rootClaudeMdContent(true, true, 'pnpm')+ expect(content).toContain('pnpm run dev')+ expect(content).toContain('pnpm spree api get products')+ expect(content).not.toContain('npx spree')+ })+it('omits apps/dashboard by default', () => {expect(rootClaudeMdContent(true)).not.toContain('apps/dashboard')})diff --git a/packages/create-spree-app/tests/utils.test.ts b/packages/create-spree-app/tests/utils.test.tsindex 4e2ef587eb..3579579542 100644--- a/packages/create-spree-app/tests/utils.test.ts+++ b/packages/create-spree-app/tests/utils.test.ts@@ -13,24 +13,27 @@ describe('detectPackageManager', () => {process.env.npm_config_user_agent = originalEnv})- it('detects yarn', () => {+ it('respects an explicit yarn agent', async () => {process.env.npm_config_user_agent = 'yarn/1.22.0 npm/? node/v20.0.0'- expect(detectPackageManager()).toBe('yarn')+ await expect(detectPackageManager()).resolves.toBe('yarn')})- it('detects pnpm', () => {+ it('respects an explicit pnpm agent', async () => {process.env.npm_config_user_agent = 'pnpm/8.0.0 npm/? node/v20.0.0'- expect(detectPackageManager()).toBe('pnpm')+ await expect(detectPackageManager()).resolves.toBe('pnpm')})- it('defaults to npm', () => {+ // An npm agent is the default runner (`npx create-spree-app`), not a+ // choice — prefer pnpm when installed. These tests run under the pnpm+ // workspace, so pnpm is always on PATH here.+ it('prefers pnpm over an npm agent when pnpm is installed', async () => {process.env.npm_config_user_agent = 'npm/10.0.0 node/v20.0.0'- expect(detectPackageManager()).toBe('npm')+ await expect(detectPackageManager()).resolves.toBe('pnpm')})- it('defaults to npm when env var is missing', () => {+ it('prefers pnpm when the agent is unknown', async () => {delete process.env.npm_config_user_agent- expect(detectPackageManager()).toBe('npm')+ await expect(detectPackageManager()).resolves.toBe('pnpm')})})