Skip to content

armgit / spree

Public Imported from GitHub
0

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.

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.md
index 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 new
prompt (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 the
starter template with version pins matching its release), and wires the
README, 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.
\`\`\`bash
cd ${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:
\`\`\`bash
cd 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:
\`\`\`bash
cd 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 the
The \`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.ts
index 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.ts
index 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.ts
index 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.ts
index 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')
})
})