@spree/docs 0.1.294 → 0.1.296

package/dist/developer/cli/quickstart.md

@@ -76,14 +76,6 @@ spree restart
 
 Not appropriate for Gemfile changes (use `spree bundle install`, then Ctrl+C and re-run `spree dev`), Dockerfile / `.ruby-version` changes (use `spree build`), or compose file changes (Ctrl+C and re-run `spree dev`).
 
-### `spree update`
-
-Pull the latest Spree Docker image and recreate containers. Migrations run automatically on startup.
-
-```bash
-spree update
-```
-
 ### `spree build`
 
 Rebuild the dev image after Dockerfile or `.ruby-version` changes. Only relevant after `spree eject`.
@@ -100,17 +92,27 @@ spree build --yes            # Skip confirmation prompts (for CI)
 
 ### `spree upgrade`
 
-Walk a Spree version upgrade end-to-end inside the dev stack. Runs `bundle update`, applies pending migrations, then walks the version-specific data backfills from the upgrade manifest.
+Upgrade your project to the latest Spree release in one go. It works for both kinds of project:
+
+1. **Update the server**
+   - On a project that runs the prebuilt image, it pulls the latest Spree image and recreates the containers. Database migrations run as the containers start.
+   - On an [ejected](#spree-eject) project, it updates the Spree gems with `bundle update`, applies pending migrations, and restarts the app so it loads the new gems.
+2. **Run data backfills** — the version-specific steps from the upgrade manifest that convert existing records.
+3. **Update the `@spree/*` packages** — `@spree/cli` in the project root, and the dashboard packages and Admin SDK in `apps/dashboard` and `apps/seller-dashboard`. Each package moves to the newest release its declared range in `package.json` allows, the same way `bundle update` respects your `Gemfile`. To move to a new major version, change the range in `package.json` first.
 
 ```bash
-spree upgrade                  # Detect target, run the full sequence interactively
-spree upgrade --plan           # Print the plan without executing (DRY_RUN=1)
-spree upgrade --to 5.5         # Cap the walk at a specific target version
-spree upgrade --step <id>      # Re-run a single step idempotently (skips bundle + migrate)
-spree upgrade --yes            # Skip the per-step prompts
+spree upgrade                  # Run every step, asking before each one
+spree upgrade --plan           # List the data backfills without running anything
+spree upgrade --to 6.1         # Set the target version for the data backfills
+spree upgrade --step <id>      # Re-run a single data backfill (runs nothing else)
+spree upgrade --yes            # Skip the prompts
 ```
 
-Production upgrades only need the third stage — `bundle install` and `db:migrate` happen in your deploy pipeline. The CLI runs all three for local development. See [Upgrades](../upgrades.md) for the manual production path.
+Your storefront is your own code, so `spree upgrade` does not change it — it tells you which `@spree/sdk` version to move to.
+
+Production upgrades only need the data backfills — installing gems and migrating happen in your deploy pipeline. See [Upgrades](../upgrades.md) for the manual production path.
+
+> **NOTE:** `spree update` is the old name for this command. It still works, prints a deprecation warning, and will be removed in a future release.
 
 ### `spree eject`
 
@@ -204,7 +206,7 @@ spree encryption init            # Add ACTIVE_RECORD_ENCRYPTION_* keys to the pr
 spree encryption init --print    # Print a fresh set without writing anything (e.g. for your hosting provider)
 ```
 
-It never overwrites keys `.env` already sets, and there is no `--force`: changing the keys makes data encrypted with them unreadable. Afterwards, recreate the containers so they load the new `.env` (`spree update`, or `spree dev` for an ejected project — `spree restart` keeps the old environment), and back the keys up in your secret manager.
+It never overwrites keys `.env` already sets, and there is no `--force`: changing the keys makes data encrypted with them unreadable. Afterwards, recreate the containers so they load the new `.env` (`spree dev` — `spree restart` keeps the old environment), and back the keys up in your secret manager.
 
 ### `spree api`
 

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

@@ -111,7 +111,7 @@ The project includes [@spree/cli](../cli/quickstart.md) for managing your Spree
 |---------|-------------|
 | `spree dev` | Run the app in the foreground — streams logs, Ctrl+C stops it. First run completes setup automatically; co-runs the Admin Dashboard dev server when `apps/dashboard` exists |
 | `spree stop` | Stop backend services |
-| `spree update` | Pull latest Spree image and restart (runs migrations automatically) |
+| `spree upgrade` | Upgrade Spree — the server, database and `@spree/*` packages |
 | `spree eject` | Switch from prebuilt image to building from `server/` |
 | `spree add dashboard` | Add the Admin Dashboard to an existing project, to customize it |
 | `spree add seller-dashboard` | Add the marketplace seller panel to an existing project |
@@ -148,10 +148,10 @@ Open [http://localhost:3001](http://localhost:3001) to see your store.
 To update to the latest Spree version:
 
 ```bash
-spree update
+spree upgrade
 ```
 
-This pulls the latest Docker image and recreates the containers. The entrypoint automatically runs database migrations.
+This updates the server (the Docker image, or the Spree gems on an ejected project), runs database migrations and data backfills, and updates the `@spree/*` packages of the project and its dashboard apps. See [`spree upgrade`](../cli/quickstart.md#spree-upgrade) for details.
 
 To pin a specific version, edit `SPREE_VERSION_TAG` in `.env`:
 

package/dist/developer/customization/email-variables.md

@@ -42,7 +42,8 @@ Each object's fields, and the fields of the objects nested in it.
 
 ### `store`
 
-- `store`: `id`, `name`, `address`, `mail_from_address`, `default_currency`, `default_locale`, `url`, `support_email`, `logo_url`, `logo_width`
+- `store`: `id`, `name`, `address`, `mail_from_address`, `default_currency`, `default_locale`, `url`, `support_email`, `logo_url`, `logo_width`, `branding`
+- `store.branding`: `background_color`, `card_color`, `text_color`, `heading_color`, `accent_color` (empty unless the merchant set one), `link_color`, `button_color`, `button_text_color`, `button_border`, `font`, `font_family`, `heading_font_family`, `font_url` (a web font's stylesheet, empty for email-safe fonts)
 
 ### `order`
 

package/dist/developer/customization/emails.md

@@ -8,7 +8,7 @@ Every email Spree sends — order confirmations, shipping notices, password rese
 
 To change an email, you copy its template into your app and edit it. Nothing else changes: Spree still picks the recipient, the language and the sender, and delivers the email through your [SMTP provider](../providers/emails.md).
 
-> **NOTE:** Templates read plain data — the same fields the [Store API](../../api-reference/store-api/introduction.md) returns, plus what only an email needs — never Ruby objects. The same template can later run outside Ruby, and merchants will be able to edit templates safely from the dashboard.
+> **NOTE:** Templates read plain data — the same fields the [Store API](../../api-reference/store-api/introduction.md) returns, plus what only an email needs — never Ruby objects. The same template can run outside Ruby, and merchants can edit customer emails safely from the dashboard.
 
 ## Where templates live
 
@@ -102,6 +102,73 @@ In development and test, a variable that does not exist raises an error instead
 
 To look at every email with real data, open the mailer previews at `/rails/mailers` on your Spree server.
 
+## Templates merchants edit in the dashboard
+
+Merchants can edit the emails their customers receive in **Settings → Emails → Templates**, along with the layout and the shared blocks in `spree/shared`. An edit is saved as a draft and goes live when published; publishing renders it with the store's own data first and refuses a template that does not render. An email built from a record the store does not have yet, such as an order confirmation in a store with no orders, is checked for template syntax only. Staff, store-owner and seller emails are not editable and always render from files.
+
+A store's published template comes first, so the lookup for an editable email is:
+
+1. the store's published template in the email's language
+2. the store's published template for every language
+3. your app's file
+4. Spree's file
+
+Your file stays the default the dashboard starts from and reverts to, so overriding a template in code and letting merchants edit it work together. When a Spree upgrade or a change to your file alters a default a merchant has customized, the dashboard tells them and shows what changed.
+
+The same operations are open to integrations through the [Admin API](../../api-reference/admin-api/introduction.md), with the `email_templates` permission:
+
+**Admin SDK:**
+
+```typescript
+    const preview = await client.emailTemplates.preview('spree.order_mailer.confirm_email', {
+      body: '<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>',
+    })
+
+    await client.emailTemplates.draft.update('spree.order_mailer.confirm_email', {
+      body: '<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>',
+    })
+    await client.emailTemplates.publish('spree.order_mailer.confirm_email')
+    ```
+
+  **cURL:**
+
+```bash
+    curl -X PUT https://your-store.com/api/v3/admin/email_templates/spree.order_mailer.confirm_email/draft \
+      -H "X-Spree-Api-Key: sk_xxx" -H "Content-Type: application/json" \
+      -d '{"body": "<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>"}'
+
+    curl -X POST https://your-store.com/api/v3/admin/email_templates/spree.order_mailer.confirm_email/publication \
+      -H "X-Spree-Api-Key: sk_xxx"
+    ```
+
+
+### Branding
+
+Merchants set the colors and font of their customer emails in **Settings → Emails**, without touching a template. Templates read them from [`store.branding`](email-variables.md#store), and Spree's layout uses them throughout. If you override the layout or a template, read colors and fonts from `store.branding` rather than writing them in, so a store's branding keeps applying.
+
+### Making your own customer email editable
+
+A customer email your app adds can be edited like Spree's own. Register it with a class that builds the data its preview renders with:
+
+```ruby server/config/initializers/spree.rb
+Rails.application.config.after_initialize do
+  Spree.editable_email_templates.register(
+    'spree/review_mailer/request_email', kind: :email, sample: 'ReviewRequestSample'
+  )
+end
+```
+
+```ruby server/app/services/review_request_sample.rb
+# Previews with the store's latest completed order, or the one the merchant picks.
+class ReviewRequestSample < Spree::Emails::Samples::Order
+  def variables
+    { order: super[:order], review_url: placeholder_url('reviews/new') }
+  end
+end
+```
+
+A sample builds from the record the merchant picked, else the store's latest one; a store with none is told there is nothing to preview with yet. Pass placeholder URLs, never real tokens, and register only emails your customers receive.
+
 ## Your own mailers
 
 A mailer that inherits `Spree::BaseMailer` and renders its own ERB views with `mail` keeps working. Spree wraps its HTML in the same layout as every other email, so it carries the store's logo, header and footer. The `spree/shared/mailer_hero` and `spree/shared/mailer_button` partials are still there for those views.

package/dist/developer/upgrades/5.6-to-6.0.md

@@ -226,7 +226,7 @@ bin/rails db:encryption:init    # prints a set; put it in env vars or encrypted
 ```
 
 
-Recreate the containers so they pick up the new `.env` (`spree update`, or `spree dev` for an ejected project — `spree restart` keeps the old environment). Set the keys on your production host **before** deploying, and store them in your secret manager.
+Recreate the containers so they pick up the new `.env` (`spree dev` — `spree restart` keeps the old environment). Set the keys on your production host **before** deploying, and store them in your secret manager.
 
 > **WARNING:** Never change or lose the keys once data is encrypted — the encrypted records become unreadable.
 

package/dist/developer/upgrades/quickstart.md

@@ -9,6 +9,38 @@ The upgrade process is fairly easy and well described. Of course, it all boils d
 
 We strongly advise upgrading Spree incrementally, rather than in one big go.
 
+## How to upgrade
+
+An upgrade updates the server, migrates the database, runs the version's data backfills, and updates the `@spree/*` packages of your dashboard apps. Always read the guide for the version you're moving to first — it lists the behavior changes to review.
+
+**Spree CLI:**
+
+```bash
+    spree upgrade
+    ```
+
+    One command for every project: it pulls the new image, or updates the Spree gems on an [ejected](../cli/quickstart.md#spree-eject) project, then runs migrations, data backfills and the package updates. See [`spree upgrade`](../cli/quickstart.md#spree-upgrade) for its options.
+
+  **Without CLI:**
+
+Run from the project root:
+
+    ```bash
+    cd server
+    bundle update $(bundle list --name-only | grep ^spree)
+    bin/rails spree:install:migrations db:migrate
+    bin/rails spree:upgrade
+    cd ..
+
+    # The project root and each dashboard app have their own package.json
+    pnpm update "@spree/*"
+    (cd apps/dashboard && pnpm update "@spree/*")
+    (cd apps/seller-dashboard && pnpm update "@spree/*")
+    ```
+
+    On npm or Yarn, run `npm update` or `yarn upgrade` instead, naming each `@spree/*` package from that `package.json` (they do not accept the `"@spree/*"` pattern).
+
+
 ## Support
 
 If you're stuck and would want to get some professional help, you can [contact us directly](https://spreecommerce.org/contact/) and request a quote for our consulting services.

package/package.json

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