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
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.mdxindex 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 tSee 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.mdxindex 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 iThe 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).```bashnpx create-spree-app@latest my-storediff --git a/packages/create-spree-app/README.md b/packages/create-spree-app/README.mdindex 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