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.

Document Node.js/npm requirements and npm troubleshooting (#14998)

Damian Legawiec4ed1d0d7634c
diff --git a/docs/developer/create-spree-app/quickstart.mdx b/docs/developer/create-spree-app/quickstart.mdx
index ea38a45916..f25eb1cf9e 100644
--- a/docs/developer/create-spree-app/quickstart.mdx
+++ b/docs/developer/create-spree-app/quickstart.mdx
@@ -23,7 +23,7 @@ The **admin dashboard** is included in every project (skip it with `--no-dashboa
## Prerequisites
-- [Node.js](https://nodejs.org/) 20 or later
+- [Node.js](https://nodejs.org/) 20 or later, with npm 9 or later (check with `node -v` and `npm -v`)
- [Docker](https://docs.docker.com/get-docker/) (for running the Spree backend, PostgreSQL, and Meilisearch)
## CLI Flags
@@ -183,6 +183,21 @@ The project deploys as **one image**: `server/Dockerfile` builds the Spree API t
See the [Deployment Guide](/developer/deployment) and the [dashboard deployment docs](/developer/dashboard/deployment).
+## Troubleshooting
+
+### `npm ERR! cb.apply is not a function`
+
+Your npm is too old for the Node.js version installed on your machine (npm 6 or earlier running on a newer Node.js). npm crashes while it downloads the installer, before `create-spree-app` starts. This usually happens when an old global npm or a Node.js version manager points at a different version than the one you expect.
+
+Reinstall a current Node.js from [nodejs.org](https://nodejs.org/) or with your version manager (for example `nvm install --lts && nvm use --lts`). It ships with a matching npm. Running `npm install -g npm@latest` usually fails with the same error, because the broken npm runs the upgrade.
+
+If the error remains, clear npm's cache and run the installer again:
+
+```bash
+rm -rf ~/.npm/_npx ~/.npm/_cacache
+npx create-spree-app@latest my-store
+```
+
## Next Steps
<CardGroup cols={2}>
diff --git a/docs/developer/getting-started/quickstart.mdx b/docs/developer/getting-started/quickstart.mdx
index 35449ba93d..533db001f3 100644
--- a/docs/developer/getting-started/quickstart.mdx
+++ b/docs/developer/getting-started/quickstart.mdx
@@ -8,7 +8,7 @@ description: "Install Spree Commerce locally, run your first store, and deploy i
The quickest way to get started. Scaffolds a full Spree project with React admin dashboard and Next.js Storefront (optional).
- **Requirements:** [Node.js](https://nodejs.org/) 24+ and [Docker](https://docs.docker.com/get-docker/) running.
+ **Requirements:** [Node.js](https://nodejs.org/) 24+ with npm 9+, and [Docker](https://docs.docker.com/get-docker/) running. Seeing an npm error before setup starts? See [Troubleshooting](/developer/create-spree-app/quickstart#troubleshooting).
```bash
npx create-spree-app@latest my-store
diff --git a/packages/create-spree-app/README.md b/packages/create-spree-app/README.md
index 8779d42805..f5d6b1a9ed 100644
--- a/packages/create-spree-app/README.md
+++ b/packages/create-spree-app/README.md
@@ -2,6 +2,13 @@
Scaffold a new [Spree Commerce](https://spreecommerce.org) project with a single command — a full Rails backend (the Spree API) running via Docker, an optional Next.js storefront, the Admin Dashboard and an optional marketplace seller panel, and the `spree` CLI for day-to-day work. Setup completes automatically: image pulled, database seeded, API keys configured.
+## Requirements
+
+- [Node.js](https://nodejs.org/) 20 or later, with npm 9 or later
+- [Docker](https://docs.docker.com/get-docker/) running
+
+`npm ERR! cb.apply is not a function` means your npm is too old for your Node.js version. Reinstall a current Node.js (it ships with a matching npm) and run the command again. See [Troubleshooting](https://spreecommerce.org/docs/developer/create-spree-app/quickstart#troubleshooting).
+
## Quick Start
```bash