@spree/docs 0.1.30 → 0.1.32

package/dist/developer/contributing/developing-spree.md

@@ -13,12 +13,18 @@ Spree is a big monorepo. For a faster clone, use a **partial clone** which downl
 git clone --filter=blob:none https://github.com/spree/spree.git
 ```
 
+## Prerequisites
+
+You need **Node.js 20+** to run the workspace scripts (including `pnpm server:setup`, which both backend and TypeScript contributors use). Install it via [nvm](https://github.com/nvm-sh/nvm), [mise](https://mise.jdx.dev), [fnm](https://github.com/Schniz/fnm), or your package manager (`brew install node` on macOS).
+
+`pnpm` is provisioned automatically via [Corepack](https://nodejs.org/api/corepack.html) (bundled with Node) — the repository pins its version in `package.json`, and the first `pnpm` command will fetch the matching release. If Corepack is disabled in your environment, run `corepack enable` once.
+
 ## Spree codebase
 
 Spree is a monorepo with three main areas:
 
 - **`spree/`** — Ruby gems (core, api, admin, emails) distributed as separate packages via RubyGems
-- **`packages/`** — TypeScript packages (SDK, Next.js helpers)
+- **`packages/`** — TypeScript packages (SDKs, CLI, project scaffolding, docs)
 - **`server/`** — A Rails application cloned from [spree-starter](https://github.com/spree/spree-starter) that mounts the Spree gems (not checked in — run `pnpm server:setup` to create it)
 
 ## Backend Development (Ruby)
@@ -42,15 +48,7 @@ All Spree models, controllers and other Ruby classes are namespaced by the `Spre
 
 The server app is not checked into the monorepo. It's cloned from [spree-starter](https://github.com/spree/spree-starter) on first setup, with `SPREE_PATH=..` automatically configured so it uses your local Spree gems.
 
-**Step 1: Start infrastructure**
-
-```bash
-docker compose up -d     # starts Postgres, Redis, Meilisearch
-```
-
-Or install PostgreSQL and Redis locally if you prefer.
-
-**Step 2: Clone the server app**
+**Step 1: Clone the server app**
 
 ```bash
 pnpm server:setup
@@ -58,19 +56,34 @@ pnpm server:setup
 
 This clones [spree-starter](https://github.com/spree/spree-starter) into `server/` and sets `SPREE_PATH=..` in `server/.env` so it uses your local Spree gems.
 
-**Step 3: Configure and run**
+**Step 2: Configure and run**
 
 ```bash
 cd server
 # Edit .env if needed (e.g. DATABASE_USERNAME, DATABASE_HOST, DATABASE_PORT)
-bin/setup        # installs Ruby (via mise), system packages, gems, prepares database
+bin/setup        # installs Ruby (via mise), Postgres/Redis/Meilisearch (via brew), gems, prepares database
 bin/dev          # starts Rails + Sidekiq + CSS watchers via overmind
 ```
 
+`bin/setup` installs system services natively (PostgreSQL, Redis, Meilisearch) via `brew bundle` on macOS or `apt-get` on Linux. If you'd rather run those services in Docker, start them from the repo root before running `bin/setup`:
+
+```bash
+docker compose up -d postgres redis meilisearch
+```
+
 Use `bin/setup --reset` to drop and recreate the database.
 
 The app runs at [http://localhost:3000](http://localhost:3000). Admin Panel is at [http://localhost:3000/admin](http://localhost:3000/admin).
 
+**Step 3 (optional): Load sample data**
+
+To populate your store with sample products, customers, orders, and configuration:
+
+```bash
+pnpm server:load_sample_data    # from repo root
+# or, from server/: bin/rails spree:load_sample_data
+```
+
 ### Running engine tests
 
 Each engine has its own test suite. First install the shared dependencies at the `spree/` level, then navigate into the specific engine to set up and run its tests:
@@ -180,7 +193,12 @@ pnpm dev
 
 | Package | Path | Description |
 |---|---|---|
-| `@spree/sdk` | `packages/sdk` | TypeScript SDK for the Spree Storefront API |
+| `@spree/sdk` | `packages/sdk` | TypeScript SDK for the Spree Store API |
+| `@spree/cli` | `packages/cli` | CLI for managing Spree Commerce projects |
+| `create-spree-app` | `packages/create-spree-app` | Project scaffolding (`npm create spree-app`) |
+| `@spree/docs` | `packages/docs` | Developer documentation for AI agents and local reference |
+
+Internal packages (`@spree/admin-sdk`, `@spree/sdk-core`) are also part of the workspace but are not published to npm.
 
 ### Common commands
 
@@ -189,7 +207,7 @@ Run from the repository root — [Turborepo](https://turbo.build/) orchestrates
 | Command | Description |
 |---|---|
 | `pnpm dev` | Start Docker backend + watch mode for all packages |
-| `pnpm build` | Build all packages (SDK first, then Next.js) |
+| `pnpm build` | Build all packages (Turbo resolves dependency order) |
 | `pnpm test` | Run tests in all packages |
 | `pnpm lint` | Lint all packages |
 | `pnpm typecheck` | Type-check all packages |
@@ -226,9 +244,10 @@ pnpm --filter @spree/sdk generate:zod
 
 ### Releasing packages
 
-Packages use [Changesets](https://github.com/changesets/changesets) for version management:
+Published packages use [Changesets](https://github.com/changesets/changesets) for version management. Each package owns its own `.changeset/` folder, so changesets must be created from inside the package directory:
 
 ```bash
+cd packages/sdk    # or packages/cli, packages/create-spree-app
 pnpm changeset
 ```
 
@@ -238,7 +257,7 @@ This creates a changeset file describing your changes. Commit it with your PR. W
 
 Consistent code style is enforced via automated linters. Please make sure your changes pass linting before submitting a PR.
 
-**Ruby:** We use [RuboCop](https://rubocop.org/) for Ruby code. Configuration lives in `server/.rubocop.yml`. Run it from the `server/` directory:
+**Ruby:** We use [RuboCop](https://rubocop.org/) for Ruby code. The configuration lives in `server/.rubocop.yml` and is shipped with [spree-starter](https://github.com/spree/spree-starter), so it's only available after running `pnpm server:setup`. Run it from the `server/` directory:
 
 ```bash
 cd server
@@ -276,20 +295,6 @@ A few tips:
 - Keep the first line under 72 characters
 - If your change references a GitHub issue, include `Fixes #<number>` in the commit message or PR description to auto-close it on merge
 
-### Using AI tools for development
-
-Spree comes with an [AGENTS.md](https://github.com/spree/spree/blob/main/AGENTS.md) file that instructs coding agents like Claude Code or Codex to help you with your development.
-
-We also have an MCP server built on top of our Documentation website to help you with your development.
-
-Add this URL to your AI tools:
-
-```
-https://spreecommerce.org/docs/mcp
-```
-
-In Claude Code you need to go to [Connectors](https://claude.ai/settings/connectors) settings and add the URL.
-
 ## Submitting Changes
 
 We use [GitHub Actions](https://github.com/spree/spree/actions) to run CI.
@@ -314,7 +319,7 @@ To help us review your PR quickly:
 - **Describe your changes.** Explain what you changed and why. Include screenshots for UI changes.
 - **Add tests.** All new features and bug fixes should include appropriate test coverage.
 - **Update documentation.** If your change affects user-facing behavior, update the relevant docs.
-- **Include a changeset** (TypeScript packages only). Run `pnpm changeset` if your change affects `@spree/sdk`.
+- **Include a changeset** if your change affects a published TypeScript package (`@spree/sdk`, `@spree/cli`, or `create-spree-app`). Run `pnpm changeset` from inside that package's directory — each package owns its own `.changeset/` folder.
 - **Ensure CI passes.** PRs with failing CI will not be reviewed.
 
 ## Reporting Bugs
@@ -329,8 +334,24 @@ When reporting a bug, please include:
 - **Relevant logs or stack traces** (formatted with triple backticks)
 - **Your environment** (Ruby version, database, OS)
 
+We have an [issue template](https://github.com/spree/spree/blob/main/.github/ISSUE_TEMPLATE.md) that will guide you through this.
+
 Issues that are open for 14 days without actionable information or activity will be marked as stale and then closed. They can be re-opened if the requested information is provided.
 
+## Using AI Tools for Development
+
+Spree comes with an [AGENTS.md](https://github.com/spree/spree/blob/main/AGENTS.md) file that instructs coding agents like Claude Code or Codex to help you with your development.
+
+We also have an MCP server built on top of our Documentation website to help you with your development.
+
+Add this URL to your AI tools:
+
+```
+https://spreecommerce.org/docs/mcp
+```
+
+In Claude Code you need to go to [Connectors](https://claude.ai/settings/connectors) settings and add the URL.
+
 ## That's a wrap!
 
 Thank you for participating in Open Source and improving Spree - you're awesome!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",