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.

21.5 KB
Raw Blame

Spree CLI configurator: declarative store configuration

Status: Design finalized — nothing built; open questions settled 2026-09-14 Target: Spree 6.0 Depends on: 5.5-admin-api-cli.md (credential resolution, Admin SDK transport), 6.0-admin-api.md (conventions, natural-key filters), 6.0-store-context-and-first-run-setup.md (what bootstrap owns), 5.6-admin-spa-csv-import.md (natural-key upsert precedent) Author: Damian Legawiec ([email protected]) Last updated: 2026-09-14 Tracking: Linear V-3633 · GitHub spree/spree#14641

Summary

Add a command group to @spree/cli that treats a YAML file as the desired configuration of a store and reconciles a live instance against it through the Admin API: diff shows what would change, deploy applies it, introspect writes the live configuration back out as YAML. Records are matched on natural keys (slug, code, SKU, name), never on prefixed IDs, so the same file provisions a fresh local project, a staging environment and a hosted production store. Today the only way to shape an environment is Ruby: db:seed, spree:load_sample_data, and sixty lines of Ruby embedded as strings in the dashboard's Playwright global setup. A declarative file is reviewable in a pull request, runs from CI against any instance, and needs no Ruby on the caller's machine, which matters because the default install is an API-only Docker app and headless teams often never open the Rails side. Every project scaffolded by create-spree-app ships a spree.config.yml describing the store, its default channel and its default market, and spree init deploys it during setup. The dashboard e2e suite is the first consumer, so the tool is exercised on every CI run before a single spec starts.

Key Decisions (do not deviate without discussion)

  • Built on the Admin API, run from the CLI, never in-process Ruby. An in-process rake spree:config:apply would be faster and could call workflows directly, but it only works where you can run Rails, cannot target a hosted instance, and would not exercise the API. The whole point is a file that works from outside the app. The existing spree api transport (credential layers, @spree/admin-sdk, retries, idempotency keys, X-Spree-Store-Id) is reused unchanged.
  • YAML is the canonical format; JSON is accepted for free. YAML carries comments and block text and diffs cleanly, which a hand-edited, reviewed file needs. YAML is a superset of JSON, so a generated file may be JSON with no second code path. The CLI already depends on the yaml package. No spree.config.ts with a defineConfig() helper: that reintroduces configuration as code that needs a runtime, which is what this removes. Teams that want loops generate YAML and commit the output.
  • A published JSON Schema makes the file self-describing. Every section is validated with Zod before any network call, and the same schemas emit a JSON Schema shipped with the CLI. introspect writes a # yaml-language-server: $schema= header so editors autocomplete and flag mistakes inline.
  • Records match on natural keys, never prefixed IDs. IDs differ per environment; a slug or code does not. References between records (a product's category, a delivery method's zone) are written as the target's natural key and resolved by the CLI. The key table below is part of the contract; a resource without a stable, unique, human-readable key cannot be managed until it gets one.
  • Bootstrap stays in Ruby seeds; the configurator starts after it. The store row, the immutable admin role, the first admin user and the first API key have no API by design (6.0-store-context-and-first-run-setup.md), and a Rails app must seed without Node. Spree::Seeds::All does not shrink. The configurator assumes a bootstrapped store and a secret key with write scopes, which spree init and the e2e global setup already provide.
  • Reconciliation is client-side in the first release. For each section the CLI lists live records filtered on the natural key, then creates, updates or skips. This needs no new endpoints beyond gaps the key audit finds (a missing Ransack allowlist entry, a missing key attribute). Server-side bulk upserts by natural key are a later optimisation for hot sections, added to the API only once the client-side path shows where they pay off. prices/bulk_upsert and stock_levels/bulk_upsert are used where they already exist.
  • Transaction data is out of scope permanently. Orders, payments, fulfillments, returns, seller payouts and transfers are history, not configuration. They stay in Ruby sample data and in the e2e Ruby bootstrap. Customers are the one exception (see Design Details): they are reference data for promotions and groups, the CSV import already upserts them on email, and the e2e suite needs one.
  • The engine is a library first and a command second, and it lives in @spree/cli (decided 2026-09-14). The reconciliation code sits under packages/cli/src/config/ and is exported as @spree/cli/config; the commands in packages/cli/src/commands/config.ts are a thin layer over it. The dashboard e2e global setup imports the library rather than shelling out to spree, so the suite does not depend on a built CLI binary. A separate @spree/configurator package was rejected for now as one more package to version and release for a single consumer; putting it in @spree/admin-sdk was rejected because the SDK stays a thin client and must not pull yaml and zod into every consumer's bundle. Accepted trade-off: the dashboard e2e suite gains a workspace dependency on @spree/cli. If a third consumer appears, split the engine out then.
  • Deletes are opt-in per section (decided 2026-09-14). deploy only creates and updates; live records missing from the file are deleted only in sections named in --prune <sections>, and --fail-on-delete refuses any plan containing a delete. Full sync with a guard flag, as Saleor does, was rejected because a file that declares only delivery zones would then wipe every other section unless the operator remembered the flag. Accepted trade-off: a stale record can linger in staging unnoticed; diff reports live records absent from the file as "not managed" so they are visible.
  • The first release covers configuration, catalog and customers (decided 2026-09-14). Products with variants, prices and stock, and customers, are in scope from the start, because the dashboard e2e bootstrap needs them and dogfooding without them is theatre. Configuration-only was rejected as leaving most of the Ruby bootstrap in place. Accepted trade-off: products are the largest section and most of the implementation effort.
  • Every new project ships with a config file, and project setup deploys it (decided 2026-09-14). create-spree-app writes spree.config.yml at the project root with the store, its default channel and its default market filled in from the answers given at scaffold time, plus commented skeletons of the other sections. spree init runs spree config deploy against it right after seeding, non-interactively, so a fresh project's shape is in a file from day one and the same file is what CI later deploys to staging. Deploy needs write scopes, and the project's auto-minted key is read_all by design (5.5-admin-api-cli.md), so spree init mints a short-lived secret key with the scopes the file needs, deploys, and revokes it. Accepted trade-off: project setup now has an HTTP step against the freshly booted container and fails loudly if the API is not up, where before it only ran rake tasks.
  • The command noun is config (decided 2026-09-14). spree config validate | diff | deploy | introspect, beside spree api and spree auth. Top-level verbs were rejected because spree deploy next to spree dev, spree build and spree init reads as deploying the application; spree store was rejected because it names one section of the file.

Design Details

Command surface

spree config diff       --config store.yml                      # dry run, exit 0 when nothing would change
spree config deploy     --config store.yml                      # diff, confirm, apply; non-TTY skips the prompt
spree config deploy     --config store.yml --prune products,categories   # allow deletes in these sections
spree config deploy     --config store.yml --fail-on-delete     # CI guard: refuse if the plan contains any delete
spree config introspect --out store.yml --include channels,delivery       # live instance to YAML
spree config validate   --config store.yml                      # schema check only, no network

Credentials resolve exactly as for spree api (flags, then env, then project auto-mint, then profiles). A deploy needs write scopes for every section present in the file; the plan step checks the key's scopes first and names the missing ones with the spree api-key create --scopes ... remediation, before touching anything.

File format

# yaml-language-server: $schema=https://spreecommerce.org/schemas/config/6.0.json
version: 1

store:
  name: Acme Wholesale
  default_currency: USD
  supported_currencies: [USD, EUR]

channels:
  - code: retail
    name: Retail
  - code: wholesale
    name: Wholesale
    customer_groups: [wholesale]

customer_groups:
  - name: Wholesale

tax_categories:
  - name: Default
    default: true
  - name: Non-taxable

delivery_zones:
  - name: Europe
    countries: [DE, FR, NL, PL]

delivery_methods:
  - name: Standard EU
    delivery_zone: Europe
    calculator:
      type: flat_rate
      preferences: { amount: 9.90, currency: EUR }

product_types:
  - name: Apparel
    option_types: [size, color]

option_types:
  - name: size
    label: Size
    values: [S, M, L, XL]
  - name: color
    label: Color
    values: [Red, Blue, Black]

categories:
  - permalink: clothing
    name: Clothing
    children:
      - permalink: clothing/t-shirts
        name: T-Shirts

products:
  - slug: classic-tee
    name: Classic Tee
    product_type: Apparel
    categories: [clothing/t-shirts]
    channels: [retail, wholesale]
    status: active
    variants:
      - sku: TEE-S-RED
        options: { size: S, color: Red }
        prices: { USD: 29.99, EUR: 27.90 }
        stock: { Warehouse: 100 }

Only sections present in the file are reconciled. A file with just delivery_zones and delivery_methods touches nothing else. Inside a present section, records absent from the file are left alone unless that section is listed in --prune.

Natural keys

Section Key Notes
store singleton update only; the row is bootstrap
channels code unique per store today
markets name unique per store today; a code column would be better and is part of the audit
customer_groups name unique per store (soft-delete aware)
tax_categories, tax_rates name
delivery_zones, delivery_profiles, delivery_methods name
payment_methods name credentials are never written from the file; see Secrets below
stock_locations name
product_types name unique per store, case-insensitive
option_types name values keyed on name within the type
categories permalink full path, so nesting is implied
collections permalink
products slug same key the CSV import uses
variants sku nested under the product; same key the CSV import uses
prices (sku, currency) via prices/bulk_upsert
stock_levels (sku, stock location) via stock_levels/bulk_upsert
price_lists name rows keyed on sku
custom_field_definitions (resource_type, namespace, key)
roles name the immutable admin role is skipped
customers email same key the CSV import uses
allowed_origins origin
webhook_endpoints url
api_keys name create only; the token is printed once and never written back
integrations type one per store per type by validation
commission_rates code
seller_requirements type (or name for multi types)
return_reasons, claim_reasons, refund_reasons, order_cancellation_reasons name
sellers slug

Where a key is not yet unique in the database, the audit adds the index and validation as part of this plan rather than letting the configurator pick the first match. Every key column must also be on the model's Ransack allowlist, since the client-side plan step filters on it.

Reconciliation

  1. Load and validate. Parse YAML, validate against the section schemas, resolve every reference to a key that exists either in the file or on the live instance. A dangling reference fails here, with the YAML path, before any write.
  2. Plan. For each present section, in dependency order, list live records filtered on the natural key and classify every file entry as create, update or unchanged. Update compares only the attributes the file sets. Live records not in the file become deletes only when the section is in --prune.
  3. Show the diff. Grouped by section, one line per record, attribute-level detail for updates. Machine-readable with --format json so CI can post it.
  4. Confirm and apply. Interactive TTY asks once; non-TTY proceeds unless --fail-on-delete trips. Writes go through the Admin SDK with idempotency keys, sequentially across sections and in small parallel batches within a section. A 422 is reported against the YAML path of the offending entry with the API's own messages, and the run continues with the remaining entries so one bad row does not hide the rest.
  5. Report. Counts per section and per outcome; non-zero exit if anything failed.

Amended 2026-11-02 (6.0-6.1-custom-fields-roadmap.md): custom field definitions come before every section whose records carry custom-field values (products, customers, sellers), so the order below moves them ahead of products. A definition's field_type and resource_type are fixed once created. resource_type is part of the natural key, so an entry whose resource_type differs from a live definition's is a different definition: it plans as a create, and the live one is deleted only under --prune, like any other unmatched record. A field_type that differs on a matched entry is reported as an error in the plan step, never sent as an update. 6.1 adds storefront_writable and validations to the section schema; against an older instance, an entry that sets either is reported as an error in the plan step and never sent, because the Admin API drops attributes it does not know without an error.

Section order follows the reference graph: store, channels, customer groups, tax, delivery zones and profiles, delivery methods, payment methods, stock locations, option types, product types, categories, collections, custom field definitions, products (with variants, prices, stock), price lists, roles, customers, origins, webhooks, integrations, marketplace sections, api keys. Prune runs in reverse order.

Introspect

Reads every list endpoint of the requested sections, strips IDs, timestamps and computed fields, writes references as natural keys, and emits the file with the $schema header. Secrets never come back: payment method credentials, integration credentials and API key tokens are written as # managed outside this file. --include limits sections; the default is everything but products, since a large catalog belongs in the CSV import and export pipeline, not a hand-edited file.

Secrets

The file is meant to be committed. Provider credentials (payment gateway keys, integration tokens) are set by the file only through ${ENV_VAR} placeholders, which the CLI substitutes at deploy time and introspect never emits. A literal value in a credential attribute is rejected by validation.

Schemas

Section schemas are hand-written Zod in the engine package. They reuse the Admin SDK's generated attribute types where a section mirrors an API resource, and describe the file shape (nested variants, references by key, the ${ENV} placeholder) where it does not. zod-to-json-schema emits the published JSON Schema at build time. @spree/admin-sdk has no Zod today and gains none from this plan.

Dashboard e2e as the first consumer

packages/dashboard/e2e/global-setup.ts keeps two Ruby statements: Spree::Seeds::All.call and the admin user. Everything else in BOOTSTRAP_RUBY moves to packages/dashboard/e2e/fixtures/*.yml, applied through the library entry against the test server once it is up, with prune on. Products, the second channel, categories, the promo customer and group, stock locations and levels, and the supplier all fit the sections above. The ledger seller's payouts and transfers are transaction data and stay Ruby, in a much smaller block. Spec-level helpers that already seed through the Admin API (seedCatalogPickerProducts) are unchanged. The gain is twofold: the fixtures become readable, and every CI run exercises the Admin API write paths before the suite starts.

The seller panel has no e2e suite yet; when it gets one it starts from a YAML fixture, not another Ruby block. Core seeds, the worktree template and spree:load_sample_data do not change in this plan.

The project config file

create-spree-app writes spree.config.yml next to docker-compose.yml:

# yaml-language-server: $schema=https://spreecommerce.org/schemas/config/6.0.json
version: 1

store:
  name: My Store            # from the scaffold prompt
  default_currency: USD
  default_locale: en
  default_country: US

channels:
  - code: online
    name: Online Store

markets:
  - name: United States
    countries: [US]
    currency: USD
    default: true

# delivery_zones:
#   - name: Domestic
#     countries: [US]
# delivery_methods:
#   - name: Standard
#     delivery_zone: Domestic
#     calculator: { type: flat_rate, preferences: { amount: 5.00, currency: USD } }

spree init runs, in order: db:seed, spree:cli:ensure_api_key, then spree config deploy --config spree.config.yml with a secret key minted for that run and revoked afterwards. spree config deploy with no --config defaults to spree.config.yml in the project directory, so day-to-day use is spree config diff and spree config deploy with nothing else. The store section updates the seeded store rather than creating one; channels and markets are additive, so the wholesale channel that seeds create is left alone. The file is committed with the project, and the CLI quickstart teaches deploying it to a remote instance with a profile.

Recipes

spree config recipe <name> (a starter file for a wholesale store, a marketplace, an EU multi-currency setup) is a follow-up once the format has settled. The first release ships an examples/ directory in the CLI package and the e2e fixtures as living examples.

Documentation

A new docs/developer/cli/configurator.mdx covers the file format, the commands, the natural-key table, secrets, and CI usage, linked from the CLI quickstart and the Admin API page. The JSON Schema is published with the docs.

Migration Path

  1. Natural key audit. For every section in the table: confirm the key is unique per store at the database level, on the Ransack allowlist, and writable through the Admin API. Fix the gaps in spree/core and spree/api first, as their own small pull requests.
  2. Engine and schemas. Section schemas, reference resolution, plan and apply, diff rendering. Unit tests with MSW against recorded Admin API shapes, plus one integration run against the API dummy app the way packages/sdk/tests/integration does.
  3. Commands. validate, diff, deploy, introspect in @spree/cli, sharing credential resolution with spree api.
  4. Dashboard e2e. Move the bootstrap fixtures to YAML; the suite must stay green shard by shard.
  5. Project scaffold. create-spree-app writes spree.config.yml from its prompts; spree init deploys it with a per-run secret key. spree config deploy defaults to that file inside a project.
  6. Docs and schema publication.
  7. Later, outside this plan: server-side bulk upserts by natural key for products and categories, recipe, an MCP wrapper once spree mcp exists.

Constraints on Current Work

  • A new admin-manageable resource must have a stable, unique, human-readable key (code, slug or name, unique per store, enforced by an index) and that key must be on its Ransack allowlist. Without it the resource cannot be declared in a config file.
  • New dashboard e2e fixtures go into the YAML fixtures once step 4 lands; until then, keep additions to BOOTSTRAP_RUBY to what has no Admin API, so they move cleanly.
  • Do not add a Ruby-side YAML loader to core or the CLI's rake tasks; the configurator's contract is the Admin API.
  • Credential attributes on payment methods and integrations must never be readable back through the Admin API in plain text; introspect relies on that.

Open Questions

None deferred. The four design questions (deletion policy, first-release scope, package placement, command noun) were settled on 2026-09-14 and are recorded under Key Decisions. The natural-key audit in Migration Path step 1 may surface resources whose key needs a schema change; those get decided in the audit pull requests, not here.

References

  • Saleor Configurator: https://saleor.io/blog/configurator and https://github.com/saleor/configurator
  • docs/plans/5.5-admin-api-cli.md, docs/plans/6.0-admin-api.md, docs/plans/6.0-store-context-and-first-run-setup.md, docs/plans/5.6-admin-spa-csv-import.md
  • packages/cli/src/commands/api.ts, packages/cli/src/config.ts
  • packages/dashboard/e2e/global-setup.ts
  • spree/core/app/services/spree/seeds/all.rb, spree/core/app/services/spree/sample_data/loader.rb