@spree/docs 0.1.81 → 0.1.83

package/dist/developer/create-spree-app/quickstart.md

@@ -1,7 +1,7 @@
 ---
 title: "create-spree-app"
 sidebarTitle: Overview
-description: "Scaffold a new Spree Commerce project with a single command. Includes a full Rails backend app for customization."
+description: "Scaffold a new Spree Commerce project with a single command — bootstraps a full Rails backend, Docker dev stack, and the @spree/cli for customization."
 ---
 
 ## Quick Start
@@ -21,7 +21,7 @@ Once complete, your store is running at [http://localhost:3000](http://localhost
 ## Prerequisites
 
 - [Node.js](https://nodejs.org/) 20 or later
-- [Docker](https://docs.docker.com/get-docker/) (for running the Spree backend, PostgreSQL, and Redis)
+- [Docker](https://docs.docker.com/get-docker/) (for running the Spree backend, PostgreSQL, Redis, and Meilisearch)
 
 ## CLI Flags
 
@@ -49,9 +49,9 @@ npx create-spree-app@latest my-store --no-storefront --no-sample-data --no-start
 
 ```text
 my-store/
-├── docker-compose.yml        # Spree backend (prebuilt image) + Postgres + Redis
+├── docker-compose.yml        # Spree backend (prebuilt image) + Postgres + Redis + Meilisearch
 ├── docker-compose.dev.yml    # Alternative: build from local backend/
-├── .env                      # SECRET_KEY_BASE, SPREE_PORT
+├── .env                      # SECRET_KEY_BASE, SPREE_PORT, SPREE_VERSION_TAG
 ├── .gitignore
 ├── package.json              # Convenience scripts
 ├── README.md
@@ -69,10 +69,11 @@ my-store/
 
 ### What's in docker-compose.yml
 
-- **Spree** — runs the `ghcr.io/spree/spree:latest` image on the configured port (default `3000`)
+- **Spree** — `web` (Rails) + `worker` (Sidekiq) running the `ghcr.io/spree/spree:latest` image on the configured port (default `3000`)
 - **PostgreSQL 18** — database with persistent volume
 - **Redis 7** — caching, background jobs, and Action Cable
-- Health checks on all services
+- **Meilisearch** — search engine
+- Health checks on postgres, redis, meilisearch, and web
 
 ## Customizing the Backend
 
@@ -88,7 +89,7 @@ This replaces `docker-compose.yml` with a version that builds from `backend/`, r
 - **Override models** with decorators in `backend/app/models/`
 - **Add controllers** in `backend/app/controllers/`
 - **Configure Spree** in `backend/config/initializers/spree.rb`
-- **Add migrations** with `cd backend && bin/rails generate migration`
+- **Add migrations** with `spree generate migration AddFooToSpreeBars foo:string` (runs inside the container)
 
 See the [Customization Guide](../customization.md) for more details.
 
@@ -98,7 +99,7 @@ The project includes [@spree/cli](../cli/quickstart.md) for managing your Spree
 
 | Command | Description |
 |---------|-------------|
-| `spree dev` | Start backend services and stream logs |
+| `spree dev` | Run the backend in the foreground — streams logs, Ctrl+C stops it |
 | `spree stop` | Stop backend services |
 | `spree update` | Pull latest Spree image and restart (runs migrations automatically) |
 | `spree eject` | Switch from prebuilt image to building from `backend/` |

package/dist/developer/customization/checkout.md

@@ -1,6 +1,6 @@
 ---
 title: Checkout Flow
-description: Learn how to customize the checkout process in Spree.
+description: Customize the Spree checkout flow with the checkout DSL — add, remove, or conditionally skip address, delivery, payment, and confirmation steps.
 version: v5
 ---
 
@@ -108,7 +108,7 @@ module MyApp
     subscribes_to 'order.completed'
 
     def handle(event)
-      order = Spree::Order.find_by(id: event.payload['id'])
+      order = Spree::Order.find_by_prefix_id(event.payload['id'])
       return unless order
 
       # Sync to fulfillment system, notify warehouse, etc.

package/dist/developer/customization/decorators.md

@@ -1,6 +1,6 @@
 ---
 title: Decorators
-description: Decorators allow you to add or modify behavior of Spree classes in your application.
+description: Use Spree decorators to add or modify behavior on core models, controllers, and helpers without forking the gem — patterns, file layout, and pitfalls.
 ---
 
 > **WARNING:** **Decorators should be a last resort.** They tightly couple your code to Spree internals and can break during upgrades. Before using decorators, consider these modern alternatives that are safer and easier to maintain:
@@ -113,19 +113,21 @@ bin/rails g spree:controller_decorator Spree::Admin::ProductsController
 This creates `app/controllers/spree/admin/products_controller_decorator.rb`:
 
 ```ruby
-module Spree
-  module Admin
-    module ProductsControllerDecorator
-      def self.prepended(base)
-        # Class-level configurations go here
-      end
+module Spree::Admin
+  module ProductsControllerDecorator
+    def self.prepended(base)
+      # base.before_action :my_filter
     end
 
-    ProductsController.prepend(ProductsControllerDecorator)
+    # add custom methods here
   end
 end
+
+Spree::Admin::ProductsController.prepend Spree::Admin::ProductsControllerDecorator
 ```
 
+The generator accepts any namespace depth. `Spree::ProductsController` produces a top-level `module Spree` wrapper; `Spree::Api::V3::Store::ProductsController` produces a `module Spree::Api::V3::Store` wrapper. The final `.prepend` line is always fully qualified.
+
 ## Decorating Models
 
 ### Changing Behavior of Existing Methods
@@ -487,7 +489,7 @@ module MyApp
     subscribes_to 'product.updated'
 
     def handle(event)
-      product = Spree::Product.find_by(id: event.payload['id'])
+      product = Spree::Product.find_by_prefix_id(event.payload['id'])
       return unless product
 
       # The payload includes changes, check if name changed

package/dist/developer/customization/quickstart.md

@@ -1,7 +1,7 @@
 ---
 title: Quickstart
 og:title: Spree Customization Quickstart
-description: Learn how to customize every part of the Spree stack
+description: Recommended ways to customize Spree — store settings, configuration, events, webhooks, dependencies, admin extensions, and decorators as a last resort.
 ---
 
 Spree is a flexible platform allowing you to customize every part of it to suit your business needs. This guide presents customization options **in order of recommendation** - start from the top and only move down if simpler options don't meet your needs.
@@ -62,7 +62,7 @@ Spree is a flexible platform allowing you to customize every part of it to suit
         subscribes_to 'order.completed'
 
         def handle(event)
-          order = Spree::Order.find_by(id: event.payload['id'])
+          order = Spree::Order.find_by_prefix_id(event.payload['id'])
           return unless order
 
           # Sync to external service, send notification, etc.

package/dist/developer/deployment/environment_variables.md

@@ -1,5 +1,6 @@
 ---
 title: Environment Variables
+description: Reference for Spree deployment environment variables — database, Redis, SMTP, web server, file storage, and application configuration settings.
 ---
 
 Spree uses environment variables for all deployment configuration. No secrets or credentials are stored in the codebase.
@@ -19,7 +20,7 @@ These variables are required to run Spree in production.
 
 > **TIP:** This configuration is used for system emails (e.g. staff invitations, report ready, export complete). Customer facing emails are handled by the [storefront via webhooks](../storefront/nextjs/customization.md#transactional-emails).
 
-Spree works with any SMTP provider (Resend, Postmark, Mailgun, SendGrid, Amazon SES, etc.). Set `SMTP_HOST` to enable email delivery — when not set, emails are logged to stdout.
+Spree works with any SMTP provider (Resend, Postmark, Mailgun, SendGrid, Amazon SES, etc.). Set `SMTP_HOST` to enable email delivery — when not set, no delivery method is configured and production email delivery fails (development opens emails in the browser via `letter_opener`).
 
 | Variable | Default | Description |
 | --- | --- | --- |

package/dist/developer/sdk/store/markets.md

@@ -1,6 +1,6 @@
 ---
 title: Markets
-description: Fetch markets, resolve by country, and list market countries with the Spree SDK
+description: Use the Spree Storefront SDK to list markets, resolve a market by country, and fetch the countries available within each market for checkout.
 ---
 
 ## List Markets
@@ -25,7 +25,7 @@ markets.forEach(market => {
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/markets' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -76,7 +76,7 @@ market.countries // [{ iso: "DE", ... }, { iso: "FR", ... }]
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/markets/mkt_gbHJdmfrXB' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -95,7 +95,7 @@ market.currency // "EUR"
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/markets/resolve?country=DE' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -119,7 +119,7 @@ countries.forEach(country => {
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/markets/mkt_gbHJdmfrXB/countries' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -140,7 +140,7 @@ country.states // [{ id: "st_xxx", name: "New York", abbr: "NY" }, ...]
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/markets/mkt_gbHJdmfrXB/countries/US?expand=states' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 

package/dist/developer/tutorial/extending-models.md

@@ -1,6 +1,6 @@
 ---
 title: Extending Core Models
-description: Learn how to extend Spree's core models to connect Brands with Products
+description: Tutorial — extend Spree's core models with a custom Brand resource, generate a migration, and associate it with Products via a decorator.
 ---
 
 In this tutorial, we'll connect our custom Brand model with Spree's core Product model. This is a common pattern when building features that need to integrate with existing Spree functionality.
@@ -289,7 +289,7 @@ module MyApp
     subscribes_to 'product.updated'
 
     def handle(event)
-      product = Spree::Product.find_by(id: event.payload['id'])
+      product = Spree::Product.find_by_prefix_id(event.payload['id'])
       return unless product
 
       ExternalSyncService.sync(product)

package/dist/developer/upgrades/5.4-to-5.5.md

@@ -5,23 +5,51 @@ description: Step-by-step guide to upgrading a Spree 5.4 application to Spree 5.
 
 > **INFO:** Before proceeding to upgrade, please ensure you're at [Spree 5.4](5.3-to-5.4.md).
 
-## Upgrade steps
+The upgrade is usually completed in five steps:
 
-### Update gems
+1. **Update the Ruby gems** which power Spree API
+2. **Run database migrations** — to migrate your existing schema to the new version
+3. **Run data backfills** — to move your existing data into the new schema and power new features
+4. Apply optional configuration and review behavior changes — to take advantage of new features and avoid surprises
 
-  ```bash
-  bundle update
-  ```
+## How to upgrade
 
-### Fetch and run missing migrations
+For applications created via `create-spree-app` command we greatly recommend using the Spree CLI to perform the upgrade. It provides a guided experience with prompts and handles the first three steps for you. If you prefer to run the commands manually or not using docker for local development, you can follow the "Without Spree CLI" path.
 
-  ```bash
-  bin/rake spree:install:migrations && bin/rails db:migrate
-  ```
+
+```bash Spree CLI
+spree upgrade
+```
+
+```bash Without Spree CLI
+# cd backend if you're in the monorepo root
+bundle update
+bin/rake spree:install:migrations && bin/rails db:migrate
+bin/rake spree:upgrade
+```
+
+
+The **Spree CLI** path runs all three commands for you with prompts. Recommended for local development. If you don't have the CLI yet, either install it globally or run it through `npx`:
+
+```bash
+# install once and use `spree …` everywhere
+npm install -g @spree/cli
+
+# or invoke without installing (each command runs through npx)
+npx @spree/cli upgrade
+```
+
+The **Without Spree CLI** path is the bare equivalent. Use this on production: `bundle update` and `db:migrate` are part of your existing deploy pipeline (Heroku release phase, K8s init container, Capistrano hook, Render auto-migrate). Once the 5.5 release is up, run `bin/rake spree:upgrade` from a one-off dyno / job container / `kubectl exec` to perform the data backfills.
+
+Skipping versions and re-running are both safe — `bin/rake spree:upgrade` figures out what still needs to happen and does nothing on data that's already migrated.
+
+## What the upgrade does
+
+This is reference material — what `bin/rake spree:upgrade` (and equivalently `spree upgrade`) actually executes on your data. Skip if you trust the tool; read on if something failed or you're curious.
 
 ### Migrate legacy variant-pinned media
 
-In 5.5 the [product is the default owner of media](../core-concepts/media.md#product-level-gallery). Existing variant-pinned images keep rendering, but new admin uploads attach to the product. To consolidate both into a single gallery, run:
+In 5.5 the [product is the default owner of media](../core-concepts/media.md#product-level-gallery). Existing variant-pinned images keep rendering, but new admin uploads attach to the product. To consolidate both into a single gallery, the upgrade runs:
 
 ```bash
 bin/rails spree:media:migrate_master_images_to_product_media
@@ -41,7 +69,7 @@ bin/rails spree:media:migrate_master_images_to_product_media BATCH_SIZE=1000
 
 Spree 5.5 introduces [Sales Channels](../core-concepts/channels.md) — a per-store distribution surface (online storefront, POS, marketplace integration, wholesale portal). Products are published to a channel via the new `spree_product_publications` join table, and orders are attributed to a channel via `spree_orders.channel_id`.
 
-The migrations add a `default` boolean on `spree_channels`, a `store_id` column on `spree_products`, and create the new `spree_product_publications` table — **but they do not seed default channels, attach existing products to a store, or backfill order channels**. That work is done by an idempotent rake task you must run after `db:migrate`:
+The migrations add a `default` boolean on `spree_channels`, a `store_id` column on `spree_products`, and create the new `spree_product_publications` table — **but they do not seed default channels, attach existing products to a store, or backfill order channels**. That work is done by an idempotent rake task:
 
 ```bash
 bin/rake spree:channels:upgrade
@@ -58,13 +86,23 @@ The task is fully idempotent — safe to re-run if it fails partway, and a no-op
 
 > **WARNING:** Until `spree:channels:upgrade` runs, every product has `store_id IS NULL` and is invisible to `Product.for_store(store)`. The admin product list, storefront catalog, and search indexer all return empty. Run the task immediately after `db:migrate`.
 
+### Reindex products
+
+The last step rebuilds the search index against the configured [search provider](../core-concepts/search-filtering.md):
+
+```bash
+bin/rake spree:search:reindex
+```
+
+This is a no-op on the default Database provider (there is no external index to maintain). For Meilisearch — or any other external search provider — it is required, and it must run **after** the Channels upgrade: products only become visible to `Product.for_store` once they have a `store_id`, so reindexing before the channels step would index zero products. The manifest orders the steps accordingly.
+
 #### Multi-store catalogs
 
 If you have products attached to multiple stores via the legacy `spree_products_stores` join, the `populate_publications` task picks **one** "home" store per product and creates publications on every store's default channel. The `spree_products_stores` table is **kept** as legacy compat surface — the upcoming `spree_multi_store` extension restores the full `Product has_many :stores` association on top of it.
 
 For single-store deployments this is invisible; you can move on without touching `spree_products_stores` again.
 
-#### Behavioral changes
+#### Behavioral changes from the Channels upgrade
 
 - Newly-created products in **the dashboard SPA** are auto-published on the store's default channel; the merchant can untick channels post-create via the Publishing card.
 - Newly-created products via the **Admin API** are NOT auto-published — the caller must supply `product_publications: [{ channel_id }]` on create or use `POST /api/v3/admin/channels/:id/add_products` afterwards.
@@ -73,6 +111,29 @@ For single-store deployments this is invisible; you can move on without touching
 
 Orders modified after the upgrade auto-set `channel_id` via the model's `before_validation :ensure_channel_presence` callback, so `backfill_order_channel_ids` is only strictly required for orders that aren't touched again post-upgrade — but running it at upgrade time avoids surprises later. The legacy `channel` string column is **kept** on `spree_orders` and ignored by ActiveRecord (`Spree::Order` declares it in `ignored_columns`). It will be dropped in a later Spree release once everyone has had a chance to run the backfill.
 
+## Update the Spree SDK
+
+Spree 5.5 ships alongside `@spree/sdk` 1.1. The backend upgrade never touches your frontend source — bump the SDK in every JavaScript consumer of the Store API and take it through your normal PR/CI cycle:
+
+```bash
+# create-spree-app projects: the Next.js storefront
+cd apps/storefront
+npm install @spree/sdk@^1.1
+```
+
+If you maintain a separate storefront repo or other integrations, repeat there. The `spree upgrade` command detects the conventional `apps/storefront` and reminds you with the currently-declared version in its "Next steps" panel.
+
+| Spree backend | `@spree/sdk` |
+|---|---|
+| 5.4 | 1.0.x |
+| 5.5 | 1.1+ |
+
+The SDK bump pairs with one storefront code change in this release: the [payment method `type` shorthand](#payment-method-type-on-the-wire-is-now-a-shorthand-not-a-rails-class-name) — update your gateway map when you bump.
+
+## Required post-upgrade configuration
+
+`bin/rake spree:upgrade` doesn't touch your job-runner config — every app uses a different scheduler, so this one is on you.
+
 ### Schedule the Stock Reservations expiry job
 
 Spree 5.5 introduces time-limited stock reservations during checkout to prevent two customers from buying the same last unit at the same time. Abandoned checkouts leave behind expired reservation rows, and Spree does **not** auto-schedule the cleanup — your application's job runner must run `Spree::StockReservations::ExpireJob` periodically (every minute is the recommended cadence).
@@ -112,7 +173,11 @@ Rails.application.configure do
 end
 ```
 
-### (Optional) Tune the reservation TTL
+## Optional tuning
+
+Defaults are sensible for most stores. Reach for these only if you have a specific reason.
+
+### Tune the reservation TTL
 
 The default reservation TTL is **10 minutes**. To override globally:
 
@@ -129,7 +194,7 @@ store.update!(preferred_stock_reservation_ttl_minutes: 20)
 
 The per-Store value, when set, takes precedence over the global default.
 
-### (Optional) Disable Stock Reservations
+### Disable Stock Reservations
 
 Stock reservations are enabled by default. To opt out and revert to pre-5.5 behavior (no holds during checkout, Quantifier returns raw `count_on_hand`):
 
@@ -140,7 +205,7 @@ Spree::Config[:stock_reservations_enabled] = false
 
 The Quantifier short-circuits before any reservation query when this is `false`, so there's no runtime cost and no table growth.
 
-### (Optional) Opt out of rules-based Order Routing
+### Opt out of rules-based Order Routing
 
 Spree 5.5 introduces [Order Routing](../core-concepts/shipments.md#order-routing) — a configurable, per-channel pipeline that decides which stock locations fulfill an order. Every store and every channel ships with three default rules (Preferred Location → Minimize Splits → Default Location) that produce sensible behavior out of the box, with no migration work required.
 
@@ -154,7 +219,9 @@ The Legacy strategy delegates to `Spree::Stock::Coordinator`, which is the exact
 
 > **WARNING:** `Spree::OrderRouting::Strategy::Legacy` and `Spree::Stock::Coordinator` are slated for removal in Spree 6.0. Use this only as a temporary escape hatch while you evaluate the new Rules strategy. New 5.5+ installations should stay on the default Rules strategy.
 
-## Behavior changes worth knowing
+## Behavior changes to review
+
+These don't require any rake task — but storefronts, integrations, and merchant-facing dashboards may need code changes to handle them correctly.
 
 ### Cart changes during checkout can now fail with insufficient stock
 
@@ -207,4 +274,4 @@ The default routing strategy (`Spree::OrderRouting::Strategy::Rules`) packs the
 
 For most stores this is invisible: when one location can fulfill the entire cart, that location now wins consistently (instead of depending on database iteration order). When the cart needs to split across locations, the same multi-location split happens — just with the location order driven by rules.
 
-If you rely on the legacy "every location packed in iteration order, no rule consulted" behavior, see [Opt out of rules-based Order Routing](#optional-opt-out-of-rules-based-order-routing) above.
+If you rely on the legacy "every location packed in iteration order, no rule consulted" behavior, see [Opt out of rules-based Order Routing](#opt-out-of-rules-based-order-routing) above.

package/package.json

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