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.

Add `spree restart` command and improve the monorepo workflow

Damian Legawiec0f3e7cdabf07
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 687ba2a0dc..3b08c53d0c 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -10,20 +10,22 @@ Please read our [Code of Conduct](../CODE_OF_CONDUCT.md) before contributing.
- [Cloning the repository](#cloning-the-repository)
- [Prerequisites](#prerequisites)
- [Spree codebase](#spree-codebase)
+ - [Setup](#setup)
+ - [Running a backend day-to-day](#running-a-backend-day-to-day)
+ - [Native Ruby (advanced)](#native-ruby-advanced)
- [Backend Development (Ruby)](#backend-development-ruby)
- [Engines overview](#engines-overview)
- [Spree namespace](#spree-namespace)
- - [Setup](#setup)
- [Running engine tests](#running-engine-tests)
- [Running tests in parallel](#running-tests-in-parallel)
- - [Integration tests (Admin Panel)](#integration-tests-admin-panel)
+ - [Integration tests (legacy Rails admin)](#integration-tests-legacy-rails-admin)
- [Performance in development mode](#performance-in-development-mode)
- [TypeScript Development](#typescript-development)
- - [Setup](#setup-1)
- [Packages](#packages)
- [Common commands](#common-commands)
- [Package-specific commands](#package-specific-commands)
- - [Admin SPA E2E tests](#admin-spa-e2e-tests)
+ - [Working on the React dashboard](#working-on-the-react-dashboard)
+ - [Dashboard E2E tests](#dashboard-e2e-tests)
- [Type generation](#type-generation)
- [Releasing packages](#releasing-packages)
- [Code Style](#code-style)
@@ -56,65 +58,81 @@ You need **Node.js 20+** to run the workspace scripts (including `pnpm server:se
Spree is a monorepo with three main areas:
- **`spree/`** — Ruby gems (core, api, admin, emails) distributed as separate packages via RubyGems
-- **`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)
+- **`packages/`** — TypeScript packages (SDKs, CLI, project scaffolding, docs, React dashboard)
+- **`server/`** — A Rails application cloned from [spree-starter](https://github.com/spree/spree-starter) that mounts the local Spree gems (not checked in — `pnpm server:setup` creates it)
-## Backend Development (Ruby)
+### Setup
-### Engines overview
+A single command bootstraps the whole monorepo for both backend and frontend work. You need **Docker** running locally (Docker Desktop, OrbStack, or any compatible runtime) — no Ruby, Postgres, or Redis on your host.
-The Spree [Rails engines](https://guides.rubyonrails.org/engines.html) live inside `spree/` and are distributed as separate gems (Ruby packages installed via Bundler):
+```bash
+pnpm install # workspace dependencies
+pnpm server:setup # ~5–10 min on first run; idempotent
+```
-| Engine | Gem | Description |
-|---|---|---|
-| `core` | `spree_core` | Models, services, business logic |
-| `api` | `spree_api` | REST APIs |
-| `admin` | `spree_admin` | Admin dashboard |
-| `emails` | `spree_emails` | Transactional emails |
+`pnpm server:setup` clones [spree-starter](https://github.com/spree/spree-starter) into `./server/`, wires it to load Spree gems from the monorepo via a Docker compose overlay, builds the dev image, starts the stack (Postgres + Redis + Meilisearch + Rails `web` + Sidekiq `worker`), and prepares the database. The full sequence lives in `scripts/server-setup.sh`.
-### Spree namespace
+When it's done, the backend is up at [http://localhost:3000](http://localhost:3000) and the admin is at [http://localhost:3000/admin](http://localhost:3000/admin). Sign in with the seed admin: **`[email protected]`** / **`spree123`** (override at seed time with `ADMIN_EMAIL` / `ADMIN_PASSWORD` env vars — see `spree/core/app/services/spree/seeds/admin_user.rb`).
-All Spree models, controllers and other Ruby classes are namespaced by the `Spree` keyword, eg. `Spree::Product`. This means that those files are also located in `spree` sub-directories eg. [app/models/spree/product.rb](https://github.com/spree/spree/blob/main/spree/core/app/models/spree/product.rb).
+Optionally load sample products, taxonomies, and option types:
-### Setup
+```bash
+pnpm server:load_sample_data
+```
-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.
+### Running a backend day-to-day
-**Step 1: Clone the server app**
+After the one-time setup, use these to bring the stack up and down:
```bash
-pnpm server:setup
+pnpm server:start # boot the Docker stack (fast — image cached, DB persisted)
+pnpm server:stop # tear down
+pnpm server:logs # follow web container logs
+pnpm server:console # open a Rails console inside the container
```
-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 2: Configure and run**
+Run any CLI command against the running backend from `server/`:
```bash
cd server
-# Edit .env if needed (e.g. DATABASE_USERNAME, DATABASE_HOST, DATABASE_PORT)
-bin/setup # installs Ruby (via mise), Postgres/Redis/Meilisearch (via brew), gems, prepares database
-bin/dev # starts Rails + Sidekiq + CSS watchers via overmind
+pnpm exec spree rails db:migrate
+pnpm exec spree generate model Brand name:string
+pnpm exec spree upgrade --plan
```
-`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`:
+See the [`@spree/cli` README](../packages/cli/README.md) for the full command surface.
+
+Re-run `pnpm server:setup` **only** to fully reset — it does `docker compose down -v` + `rm -rf ./server`, wiping all DB data.
+
+### Native Ruby (advanced)
+
+If you prefer the fastest possible inner loop and don't mind installing Ruby, Postgres, Redis, and Meilisearch on your host directly, you can skip Docker:
```bash
-docker compose up -d postgres redis meilisearch
+pnpm server:create # clones spree-starter, writes server/.env with SPREE_PATH=..
+cd server
+bin/setup # installs Ruby (via mise), Postgres/Redis/Meilisearch (via brew bundle on macOS), gems, prepares the database
+bin/dev # starts Rails + Sidekiq + CSS watchers via Foreman
```
-Use `bin/setup --reset` to drop and recreate the database.
+This path is faster per request but means more on your host. It also runs against your installed system services, not a sandboxed Docker stack.
-The app runs at [http://localhost:3000](http://localhost:3000). Admin Panel is at [http://localhost:3000/admin](http://localhost:3000/admin).
+## Backend Development (Ruby)
-**Step 3 (optional): Load sample data**
+### Engines overview
-To populate your store with sample products, customers, orders, and configuration:
+The Spree [Rails engines](https://guides.rubyonrails.org/engines.html) live inside `spree/` and are distributed as separate gems (Ruby packages installed via Bundler):
-```bash
-pnpm server:load_sample_data # from repo root
-# or, from server/: bin/rails spree:load_sample_data
-```
+| Engine | Gem | Description |
+|---|---|---|
+| `core` | `spree_core` | Models, services, business logic |
+| `api` | `spree_api` | REST APIs |
+| `admin` | `spree_admin` | Admin dashboard |
+| `emails` | `spree_emails` | Transactional emails |
+
+### Spree namespace
+
+All Spree models, controllers and other Ruby classes are namespaced by the `Spree` keyword, eg. `Spree::Product`. This means that those files are also located in `spree` sub-directories eg. [app/models/spree/product.rb](https://github.com/spree/spree/blob/main/spree/core/app/models/spree/product.rb).
### Running engine tests
@@ -180,7 +198,7 @@ bundle exec parallel_rspec -n 4 spec
After schema changes, re-run `bundle exec rake parallel_setup` to update the worker databases.
-### Integration tests (Admin Panel)
+### Integration tests (legacy Rails admin)
The legacy Rails admin (`spree/admin`) ships feature specs that run in a real browser via chromedriver. You only need this if you're touching the legacy admin UI.
@@ -190,49 +208,35 @@ Install chromedriver on macOS:
brew install chromedriver
```
-The 6.0 React admin SPA (`packages/admin`) has its own end-to-end test suite running on Playwright against a real Rails backend — see [Admin SPA E2E tests](#admin-spa-e2e-tests) under TypeScript Development.
+The 6.0 React dashboard (`packages/dashboard`) has its own end-to-end test suite running on Playwright against a real Rails backend — see [Dashboard E2E tests](#dashboard-e2e-tests) under TypeScript Development.
### Performance in development mode
-You may notice that your Spree store runs slower in development environment. This is caused by disabled caching and automatic reloading of code after each change.
-
-Caching is disabled by default. To turn on caching please run:
+Spree runs slower in development because caching is disabled and code reloads on each request. To turn on caching:
```bash
-cd server && bin/rails dev:cache
+cd server && pnpm exec spree rails dev:cache
```
-You will need to restart rails server after this change.
+Restart the Rails server after running this (`pnpm server:stop && pnpm server:start`).
## TypeScript Development
-### Setup
-
-TypeScript developers don't need Ruby installed. Docker Compose from the repository root starts the backend using a prebuilt image:
-
-```bash
-docker compose up -d
-```
-
-This boots PostgreSQL, Redis, Meilisearch, and the Spree backend automatically (no `pnpm server:setup` needed). The API is available at `http://localhost:3000`.
-
-Then install dependencies and start all packages in watch mode:
-
-```bash
-pnpm install
-pnpm dev
-```
+The backend setup is the same as for Ruby work — see [Setup](#setup) above. With `pnpm server:setup` done, the Rails backend is running and you can start the packages you want to work on.
### Packages
-| Package | Path | Description |
-|---|---|---|
-| `@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.
+| Package | Path | Published | Description |
+|---|---|---|---|
+| `@spree/sdk` | `packages/sdk` | yes | TypeScript SDK for the Spree Store API |
+| `@spree/admin-sdk` | `packages/admin-sdk` | yes | TypeScript SDK for the Spree Admin API |
+| `@spree/cli` | `packages/cli` | yes | CLI for managing Spree Commerce projects |
+| `create-spree-app` | `packages/create-spree-app` | yes | Project scaffolding (`npm create spree-app`) |
+| `@spree/docs` | `packages/docs` | yes | Developer documentation for AI agents and local reference |
+| `@spree/dashboard` | `packages/dashboard` | no | React SPA admin dashboard (Spree 6.0, replaces the legacy Rails admin) |
+| `@spree/dashboard-core` | `packages/dashboard-core` | no | Framework: registries, providers, generic infra hooks for the dashboard |
+| `@spree/dashboard-ui` | `packages/dashboard-ui` | no | Design system used by the dashboard |
+| `@spree/sdk-core` | `packages/sdk-core` | no | Shared HTTP/retry/error layer used by both SDKs |
### Common commands
@@ -240,7 +244,7 @@ Run from the repository root — [Turborepo](https://turbo.build/) orchestrates
| Command | Description |
|---|---|
-| `pnpm dev` | Start Docker backend + watch mode for all packages |
+| `pnpm dev` | Watch mode for all packages (does not boot the backend — use `pnpm server:start` for that) |
| `pnpm build` | Build all packages (Turbo resolves dependency order) |
| `pnpm test` | Run tests in all packages |
| `pnpm lint` | Lint all packages |
@@ -259,11 +263,34 @@ pnpm --filter @spree/sdk generate:zod
Tests use [Vitest](https://vitest.dev/) with [MSW](https://mswjs.io/) for API mocking at the network level.
-### Admin SPA E2E tests
+### Working on the React dashboard
-The 6.0 React admin (`packages/admin`) has an end-to-end suite running on [Playwright](https://playwright.dev/) against a real Rails backend — no mocks. The spec files exercise the full UI: login form, staff invitation flow, invitee signup. CI runs the same suite via the `admin-e2e` job in `.github/workflows/packages.yml`.
+The dashboard runs as a Vite dev server (port 5173) that proxies `/api/*` to the Rails backend on port 3000 — required for the auth refresh cookie to work over plain HTTP.
-To run locally you need Ruby (the suite boots a Rails server) and a one-time browser install:
+```bash
+# Terminal 1: backend
+pnpm server:start
+
+# Terminal 2: dashboard
+cd packages/dashboard
+pnpm dev # http://localhost:5173
+```
+
+Sign in with `[email protected]` / `spree123`. To point at a non-default backend, set `VITE_SPREE_API_URL` (also needs to be set at build time for production bundles, not just dev):
+
+```bash
+VITE_SPREE_API_URL=https://my-spree.example.com pnpm dev
+```
+
+**Gotcha:** the dashboard imports `@spree/admin-sdk` from its **built** `dist/`, not source. If you edit `admin-sdk` (or `sdk-core`, or `sdk`) and want the dashboard to see the changes, run `pnpm build` from the monorepo root first (Turbo-cached). Editing dashboard code alone doesn't need this.
+
+See `packages/dashboard/README.md` for the full architecture (auth, permissions, extension points, the three-package split between `dashboard`, `dashboard-core`, and `dashboard-ui`).
+
+### Dashboard E2E tests
+
+The React dashboard ships an end-to-end suite running on [Playwright](https://playwright.dev/) against a real Rails backend — no mocks. The spec files exercise the full UI: login, staff invitation, invitee signup. CI runs the same suite via the `dashboard-e2e` job in `.github/workflows/packages.yml`.
+
+To run locally you need Ruby (the suite boots a real Rails server) and a one-time browser install:
```bash
# Make sure the dummy Rails app exists (one-time, after a fresh checkout).
@@ -272,7 +299,7 @@ bundle install
bundle exec rake test_app
# Install Playwright's Chromium (one-time per machine).
-cd ../../packages/admin
+cd ../../packages/dashboard
pnpm test:e2e:install
# Run the suite. Boots Rails on :3010 + Vite on :5174, runs all specs, tears
@@ -293,23 +320,29 @@ pnpm test:e2e e2e/auth.spec.ts
pnpm test:e2e -g "invites a teammate"
```
-When a test fails, Playwright drops a screenshot, video, and DOM snapshot in `packages/admin/test-results/<spec>/` — usually enough to diagnose without re-running.
+When a test fails, Playwright drops a screenshot, video, and DOM snapshot in `packages/dashboard/test-results/<spec>/` — usually enough to diagnose without re-running.
### Type generation
-TypeScript types in `packages/sdk/src/types/generated/` are auto-generated from the Rails API serializers using [typelizer](https://github.com/skryukov/typelizer). To regenerate after changing serializers:
+TypeScript types in `packages/sdk/src/types/generated/` (Store API) and `packages/admin-sdk/src/types/generated/` (Admin API) are auto-generated from the Rails serializers using [typelizer](https://github.com/skryukov/typelizer). Zod schemas in `packages/sdk/src/zod/generated/` are derived from the TS types.
+
+A **Lefthook pre-commit hook** regenerates both whenever you commit a change to `spree/api/app/serializers/**/*.rb` and re-stages the generated output. You don't need to run anything manually for the common case.
+
+To regenerate manually (useful when iterating on serializers before committing):
```bash
-cd spree/api
-mise install --yes # to install Ruby if you don't have it already
-bundle install # to install dependencies
-bundle exec rake typelizer:generate
+cd server
+pnpm exec spree rake typelizer:generate # regenerate TS types
+cd ../packages/sdk
+pnpm generate:zod # regenerate Zod schemas
```
-After regenerating types, update the Zod schemas:
+If you'd rather avoid the Docker round-trip and have Ruby on your host, the native equivalent works too:
```bash
-pnpm --filter @spree/sdk generate:zod
+cd spree/api
+bundle install
+bundle exec rake typelizer:generate
```
### Releasing packages
@@ -317,29 +350,33 @@ pnpm --filter @spree/sdk generate:zod
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
+cd packages/sdk # or packages/admin-sdk, packages/cli, packages/create-spree-app
pnpm changeset
```
This creates a changeset file describing your changes. Commit it with your PR. When merged to `main`, a GitHub Action creates a "Version Packages" PR that bumps the version and publishes to npm.
+Private packages (`@spree/dashboard`, `@spree/dashboard-core`, `@spree/dashboard-ui`, `@spree/sdk-core`) don't need changesets.
+
## Code Style
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. 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:
+**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 inside the container via the CLI:
```bash
cd server
-bundle exec rubocop
+pnpm exec spree exec bundle exec rubocop
```
To auto-fix correctable offenses:
```bash
-bundle exec rubocop -a
+pnpm exec spree exec bundle exec rubocop -a
```
+(On the native path, drop the `pnpm exec spree exec` prefix and run `bundle exec rubocop` directly.)
+
**TypeScript:** We use [Biome](https://biomejs.dev/) for linting and formatting TypeScript code. Run it from the repository root:
```bash
@@ -389,7 +426,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** 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.
+- **Include a changeset** if your change affects a published TypeScript package (`@spree/sdk`, `@spree/admin-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
diff --git a/CLAUDE.md b/CLAUDE.md
index a3bfd18614..938710c463 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -454,7 +454,7 @@ cd packages/dashboard
pnpm dev # http://localhost:5173 (proxies /api/* to :3000)
```
-`VITE_SPREE_API_URL` overrides the backend URL (default `http://localhost:3000`). Sign in with the seed admin user (`[email protected]` / `spree123` — check `db/seeds.rb`).
+`VITE_SPREE_API_URL` overrides the backend URL (default `http://localhost:3000`). Sign in with the seed admin user (`[email protected]` / `spree123` — override at seed time with `ADMIN_EMAIL` / `ADMIN_PASSWORD`; see `spree/core/app/services/spree/seeds/admin_user.rb`).
**When implementing a new admin feature:**
diff --git a/docker-compose.yml b/docker-compose.yml
deleted file mode 100644
index ab884aa2ec..0000000000
--- a/docker-compose.yml
+++ /dev/null
@@ -1,80 +0,0 @@
-# Local development services.
-# Just works: pnpm dev (uses prebuilt Spree image)
-# Rails devs: pnpm server:setup, then pnpm server:dev (runs natively)
-x-app: &app
- image: ghcr.io/spree/spree:latest
- depends_on:
- postgres:
- condition: service_healthy
- redis:
- condition: service_healthy
- meilisearch:
- condition: service_healthy
- environment: &app-env
- DATABASE_URL: postgres://postgres@postgres:5432/spree_development
- REDIS_URL: redis://redis:6379/0
- SECRET_KEY_BASE: development_secret_key_base_not_for_production_use_only
- RAILS_FORCE_SSL: "false"
- RAILS_ASSUME_SSL: "false"
- MEILISEARCH_URL: http://meilisearch:7700
- # Admin/system emails use letter_opener in development (opens in browser).
- # Customer transactional emails are handled by the storefront via webhooks.
-
-services:
- postgres:
- image: postgres:18-alpine
- environment:
- POSTGRES_HOST_AUTH_METHOD: trust
- volumes:
- - postgres_data:/var/lib/postgresql
- ports:
- - "5432:5432"
- healthcheck:
- test: pg_isready -U postgres
- interval: 5s
- timeout: 5s
- retries: 5
-
- redis:
- image: redis:7-alpine
- volumes:
- - redis_data:/data
- ports:
- - "6379:6379"
- healthcheck:
- test: redis-cli ping
- interval: 5s
- timeout: 5s
- retries: 5
-
- meilisearch:
- image: getmeili/meilisearch:latest
- volumes:
- - meilisearch_data:/meili_data
- ports:
- - "7700:7700"
- healthcheck:
- test: curl -f http://localhost:7700/health || exit 1
- interval: 5s
- timeout: 5s
- retries: 5
-
- web:
- <<: *app
- ports:
- - "3000:3000"
- healthcheck:
- test: curl -f http://localhost:3000/up || exit 1
- interval: 10s
- timeout: 5s
- retries: 10
- start_period: 30s
-
- worker:
- <<: *app
- command: bundle exec sidekiq
-
-volumes:
- postgres_data:
- redis_data:
- meilisearch_data:
diff --git a/package.json b/package.json
index e62782d4c7..077fd7b7c0 100644
--- a/package.json
+++ b/package.json
@@ -3,7 +3,7 @@
"private": true,
"scripts": {
"preinstall": "npx only-allow pnpm",
- "dev": "docker compose up -d && turbo dev",
+ "dev": "turbo dev",
"build": "turbo build",
"test": "turbo test",
"lint": "turbo lint",
@@ -14,11 +14,12 @@
"server:create": "git clone --depth 1 https://github.com/spree/spree-starter.git server && rm -rf server/.git server/.gitignore && printf 'SPREE_PATH=..\\nSECRET_KEY_BASE=%s\\n' \"$(openssl rand -hex 64)\" > server/.env",
"server:setup": "bash scripts/server-setup.sh",
"server:start": "SPREE_PATH=$PWD docker compose -f server/docker-compose.dev.yml -f scripts/docker-compose.edge.yml up -d --force-recreate web worker",
+ "server:restart": "SPREE_PATH=$PWD docker compose -f server/docker-compose.dev.yml -f scripts/docker-compose.edge.yml restart web worker",
"server:stop": "SPREE_PATH=$PWD docker compose -f server/docker-compose.dev.yml -f scripts/docker-compose.edge.yml down",
- "server:console": "cd server && node ../packages/cli/dist/index.js console",
- "server:logs": "cd server && tail -f log/development.log",
- "server:seed": "cd server && node ../packages/cli/dist/index.js rails db:seed",
- "server:load_sample_data": "cd server && node ../packages/cli/dist/index.js task load_sample_data"
+ "server:console": "cd server && pnpm exec spree console",
+ "server:logs": "cd server && pnpm exec spree logs",
+ "server:seed": "cd server && pnpm exec spree rails db:seed",
+ "server:load_sample_data": "cd server && pnpm exec spree task load_sample_data"
},
"devDependencies": {
"@biomejs/biome": "^2.4.14",
@@ -29,6 +30,7 @@
"node": ">=22"
},
"dependencies": {
- "@base-ui/react": "^1.4.1"
+ "@base-ui/react": "^1.4.1",
+ "@spree/cli": "workspace:*"
}
}
diff --git a/packages/cli/src/commands/restart.ts b/packages/cli/src/commands/restart.ts
new file mode 100644
index 0000000000..b6ea27315e
--- /dev/null
+++ b/packages/cli/src/commands/restart.ts
@@ -0,0 +1,29 @@
+import * as p from '@clack/prompts'
+import type { Command } from 'commander'
+import { detectProject } from '../context.js'
+import { dockerCompose } from '../docker.js'
+
+// `docker compose restart` sends SIGTERM, the container's PID 1 exits, Docker
+// re-launches it. Same image, same volumes, fresh Rails process — fast and
+// matches the "just restart the app" intent.
+//
+// Right for: config/initializers/*.rb changes, code that's loaded once at
+// boot, any change Zeitwerk doesn't auto-reload.
+//
+// NOT right for: Gemfile changes (need `spree bundle install` first, then
+// `spree stop && spree dev` to recreate the container from the updated
+// bundle), Dockerfile / .ruby-version changes (need `spree build`), or
+// compose file changes (need recreate). For those, use the heavier path.
+export function registerRestartCommand(program: Command): void {
+ program
+ .command('restart')
+ .description('Restart web + worker in place (does not reload Gemfile or compose changes)')
+ .action(async () => {
+ const ctx = detectProject()
+
+ const s = p.spinner()
+ s.start('Restarting web + worker...')
+ await dockerCompose(['restart', 'web', 'worker'], ctx.projectDir)
+ s.stop('Services restarted.')
+ })
+}
diff --git a/packages/cli/src/commands/upgrade.ts b/packages/cli/src/commands/upgrade.ts
index b81b33a63a..20ce91ad48 100644
--- a/packages/cli/src/commands/upgrade.ts
+++ b/packages/cli/src/commands/upgrade.ts
@@ -35,51 +35,49 @@ export function registerUpgradeCommand(program: Command): void {
.description('Walk through a Spree version upgrade (bundle + migrate + spree:upgrade)')
.option('--plan', 'print the plan via spree:upgrade DRY_RUN=1; skip bundle + migrate')
.option('--step <id>', 'run a single rake step by id (skips bundle + migrate)')
- .option('--to <version>', 'explicit target version (auto-detected from installed gem otherwise)')
+ .option(
+ '--to <version>',
+ 'explicit target version (auto-detected from installed gem otherwise)',
+ )
.option('--yes', 'skip prompts on automated steps')
- .action(
- async (flags: {
- plan?: boolean
- step?: string
- to?: string
- yes?: boolean
- }) => {
- const ctx = detectProject()
+ .action(async (flags: { plan?: boolean; step?: string; to?: string; yes?: boolean }) => {
+ const ctx = detectProject()
- // --plan and --step both opt out of the universal pre-steps:
- // --plan: we're not running anything anyway.
- // --step: the operator is retrying one rake step after a fix;
- // bundle/migrate already happened in the original run.
- const skipUniversal = Boolean(flags.plan || flags.step)
+ // --plan and --step both opt out of the universal pre-steps:
+ // --plan: we're not running anything anyway.
+ // --step: the operator is retrying one rake step after a fix;
+ // bundle/migrate already happened in the original run.
+ const skipUniversal = Boolean(flags.plan || flags.step)
- if (!skipUniversal) {
- await runBundleUpdate(ctx.projectDir, flags)
- await runMigrate(ctx.projectDir, flags)
- }
+ if (!skipUniversal) {
+ await runBundleUpdate(ctx.projectDir, flags)
+ await runMigrate(ctx.projectDir, flags)
+ }
- await runRakeUpgrade(ctx.projectDir, flags)
+ await runRakeUpgrade(ctx.projectDir, flags)
- // Closing reminder: the manifest only covers rake-runnable steps.
- // Anything human (cron scheduling, breaking-change review) is in
- // the upgrade doc — point there so the operator doesn't forget.
- printPostUpgradeReminder()
- },
- )
+ // Closing reminder: the manifest only covers rake-runnable steps.
+ // Anything human (cron scheduling, breaking-change review) is in
+ // the upgrade doc — point there so the operator doesn't forget.
+ printPostUpgradeReminder()
+ })
}
-async function runBundleUpdate(
- projectDir: string,
- flags: { yes?: boolean },
-): Promise<void> {
+async function runBundleUpdate(projectDir: string, flags: { yes?: boolean }): Promise<void> {
if (!flags.yes) {
const confirmed = await p.confirm({
message: 'Run `bundle update` to bump Spree gems?',
initialValue: true,
})
- if (p.isCancel(confirmed) || !confirmed) {
+ // Ctrl+C aborts the whole upgrade; "No" just skips this step.
+ if (p.isCancel(confirmed)) {
p.cancel('Upgrade aborted.')
process.exit(0)
}
+ if (!confirmed) {
+ p.log.info('Skipping `bundle update`.')
+ return
+ }
}
p.log.step(pc.bold('bundle update'))
await dockerComposeExec(['bundle', 'update'], projectDir)
@@ -91,17 +89,22 @@ async function runMigrate(projectDir: string, flags: { yes?: boolean }): Promise
message: 'Install + run pending migrations?',
initialValue: true,
})
- if (p.isCancel(confirmed) || !confirmed) {
+ // Ctrl+C aborts the whole upgrade; "No" just skips this step.
+ // Skipping `db:migrate` is risky — the rake `spree:upgrade` step that
+ // follows often assumes fresh schema. We let the user proceed anyway;
+ // if rake fails they'll see why.
+ if (p.isCancel(confirmed)) {
p.cancel('Upgrade aborted.')
process.exit(0)
}
+ if (!confirmed) {
+ p.log.info('Skipping migrations.')
+ return
+ }
}
p.log.step(pc.bold('spree:install:migrations + db:migrate'))
// Compound rails invocation matches the canonical upgrade doc.
- await dockerComposeExec(
- ['bin/rails', 'spree:install:migrations', 'db:migrate'],
- projectDir,
- )
+ await dockerComposeExec(['bin/rails', 'spree:install:migrations', 'db:migrate'], projectDir)
}
async function runRakeUpgrade(
@@ -125,7 +128,7 @@ function printPostUpgradeReminder(): void {
[
`The manifest only ran ${pc.bold('rake-automatable')} steps.`,
'',
- 'Don\'t forget the manual parts from the upgrade doc:',
+ "Don't forget the manual parts from the upgrade doc:",
` ${pc.dim('- Schedule Spree::StockReservations::ExpireJob (cron)')}`,
` ${pc.dim('- Review behavior changes (cart, availability, payment-method types)')}`,
` ${pc.dim('- Audit custom decorators against renamed APIs')}`,
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index feb9922444..4d678fa35d 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -15,6 +15,7 @@ import { registerMigrateCommand } from './commands/migrate.js'
import { registerOpenCommand } from './commands/open.js'
import { registerRailsCommand } from './commands/rails.js'
import { registerRakeCommand } from './commands/rake.js'
+import { registerRestartCommand } from './commands/restart.js'
import { registerRoutesCommand } from './commands/routes.js'
import { registerSampleDataCommand } from './commands/sample-data.js'
import { registerSeedCommand } from './commands/seed.js'
@@ -37,6 +38,7 @@ const program = new Command()
registerInitCommand(program)
registerDevCommand(program)
registerStopCommand(program)
+registerRestartCommand(program)
registerUpdateCommand(program)
registerLogsCommand(program)
registerEjectCommand(program)
diff --git a/packages/dashboard/README.md b/packages/dashboard/README.md
index 8a43d0abd2..1b17010f0c 100644
--- a/packages/dashboard/README.md
+++ b/packages/dashboard/README.md
@@ -75,7 +75,7 @@ cd packages/dashboard
pnpm dev # http://localhost:5173
```
-Vite proxies `/api/*` to `http://localhost:3000`. The first time you load the admin, sign in with the seed admin user (default: `[email protected]` / `spree123` — see your server's `db/seeds.rb`). If you need to reset an admin password, run `pnpm server:console` and update the user from the Rails console.
+Vite proxies `/api/*` to `http://localhost:3000`. The first time you load the admin, sign in with the seed admin user (default: `[email protected]` / `spree123` — override at seed time with `ADMIN_EMAIL` / `ADMIN_PASSWORD`; see `spree/core/app/services/spree/seeds/admin_user.rb`). If you need to reset an admin password, run `pnpm server:console` and update the user from the Rails console.
### Configuration
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index fcdf70bf85..5d4e7564a4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -11,6 +11,9 @@ importers:
'@base-ui/react':
specifier: ^1.4.1
+ '@spree/cli':
+ specifier: workspace:*
+ version: link:packages/cli
devDependencies:
'@biomejs/biome':
specifier: ^2.4.14