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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Run the storefront in a worktree (#14495)
Damian Legawiec610fcac7bc89
diff --git a/.gitignore b/.gitignoreindex 73bec41e8c..885d65f263 100644--- a/.gitignore+++ b/.gitignore@@ -55,6 +55,9 @@ brakeman-*.**/app/assets/builds.claude/worktreesserver/+# Per-worktree clone of spree/storefront (branch 6-0-dev), provisioned by+# scripts/worktree/setup.sh. Keeps its own .git — commit and push from inside it.+storefront/**/node_modulespackage-lock.jsonpackages/*/package-lock.jsondiff --git a/CLAUDE.md b/CLAUDE.mdindex ad276664a9..1b7621803d 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -105,6 +105,7 @@ Shipped plans:| `packages/cli` | `@spree/cli` — Docker-based project management CLI || `packages/create-spree-app` | `create-spree-app` — project scaffolding || `server/` | Rails app cloned from `spree/spree-starter` (.gitignored, provisioned per worktree by `scripts/worktree/setup.sh`) |+| `storefront/` | Next.js storefront cloned from `spree/storefront` branch `6-0-dev` (.gitignored, provisioned per worktree; keeps its `.git` — commit and push from inside it) |## Development Server (worktrees)@@ -115,13 +116,20 @@ wt switch -c feature-x # create worktree + provisioned environment (~20 s)pnpm wt:dev # Rails → https://feature-x.spree.localhost (/up, /api/v3, /jobs; jobs run inside Puma via Solid Queue)pnpm wt:dashboard # admin UI → https://admin.feature-x.spree.localhostpnpm wt:seller # seller panel → https://sellers.feature-x.spree.localhost+pnpm wt:storefront # Next.js storefront → https://store.feature-x.spree.localhostpnpm wt:e2e [spec...] # Playwright on this worktree's own port blockpnpm wt:template # rebuild the template DB after schema-changing pullswt merge main # ship + clean up (worktree, branch and databases all removed)wt remove # abandon instead of shipping```-Admin login: `[email protected]` / `spree123`. Both dev scripts run in the foreground and stream logs; `server/log/development.log` has the Rails log if the server runs detached. Start servers only in worktrees you're actively looking at — rspec/vitest/tsc need no servers.+Admin login: `[email protected]` / `spree123`. The dev scripts run in the foreground and stream logs; `server/log/development.log` has the Rails log if the server runs detached. Start servers only in worktrees you're actively looking at — rspec/vitest/tsc need no servers.++**Storefront (`pnpm wt:storefront`).** The Next.js storefront is a separate repo (`spree/storefront`) cloned per worktree into a gitignored `storefront/`, on its **`6-0-dev`** branch — `main` stays on the released Store API for people forking or deploying it. Unlike `server/`, the clone keeps its `.git`: commit and push storefront work from inside it, and push before `wt remove`, which deletes the clone with the worktree.++It is deliberately **not** a member of this pnpm workspace — one lockfile and one set of global overrides cannot serve both Next 16 and the dashboard's Vite tree. It instead points `@spree/sdk` at this worktree's `packages/sdk` through its own `.pnpmfile.cjs`, which rewrites the dependency only when `SPREE_SDK_PATH` is set (the JavaScript twin of `SPREE_PATH`), so a standalone clone still installs the published SDK. The rewrite uses `file:` and not `link:`, because the storefront pins module resolution to its own directory (`turbopack.root`, `output: "standalone"`) and lists the SDK in `transpilePackages` — a symlink pointing outside the project fails to resolve, and every `@spree/sdk` import breaks. Two consequences: the storefront's `pnpm-lock.yaml` will show a local path — never commit it — and because the SDK is **copied**, picking up a change to it means rebuilding and reinstalling, which is exactly what re-running `pnpm wt:storefront` does.++`storefront/.env.local` is regenerated on every boot with this worktree's API URL and the seeded publishable keys (read straight from Postgres — publishable tokens are plaintext), so a reseeded database can't leave a stale key behind. Anything you add below the marker line is preserved.One-time machine setup: Homebrew `postgresql@18` running on :5432 (with a `postgres` superuser role), `mailpit` (`brew services start mailpit` — one instance serves every worktree), Ruby per `server/.ruby-version` (mise or rbenv), Node ≥ 24 with `npm i -g portless` (start the proxy once with `portless proxy start`, accepting sudo for :443), worktrunk, then `pnpm wt:template`.@@ -134,6 +142,7 @@ One-time machine setup: Homebrew `postgresql@18` running on :5432 (with a `postg| Rails console / database | `cd server && bin/rails console`; the DB is `spree_dev_<branch>` on `localhost:5432` || E2E prerequisites | Once per worktree: `cd spree/api && bundle install && bundle exec rake test_app` (then `pnpm wt:e2e`) || Read an email the app sent | Mailpit catches everything: <http://localhost:8025>. `brew install mailpit && brew services start mailpit` if it is not running — without it the starter falls back to a delivery method that does not exist and every send raises |+| Store API serializers or SDK code, and the storefront is running | Re-run `pnpm wt:storefront` — it rebuilds the SDK and copies it in. Run the [type generation pipeline](#type-generation-pipeline) first if you changed serializers || Meilisearch search provider | Optional: `brew install meilisearch`, run it, set `MEILISEARCH_URL` in `server/.env`, `bin/rails spree:search:reindex` || Hosted dashboard at `/dashboard` (single-node test) | `pnpm server:dashboard` to build `packages/dashboard-starter/dist`, set `SPREE_DASHBOARD_DIST_PATH=<monorepo>/packages/dashboard-starter/dist` in `server/.env` || Hosted seller panel at `/sellers` (single-node test) | `pnpm server:seller` to build `packages/seller-dashboard-starter/dist`, set `SPREE_SELLER_PANEL_DIST_PATH=<monorepo>/packages/seller-dashboard-starter/dist` in `server/.env` |diff --git a/package.json b/package.jsonindex 030ff8d42e..726708e68e 100644--- a/package.json+++ b/package.json@@ -28,6 +28,7 @@"wt:dev": "scripts/worktree/dev.sh","wt:dashboard": "scripts/worktree/dev-dashboard.sh","wt:seller": "scripts/worktree/dev-seller.sh",+ "wt:storefront": "scripts/worktree/dev-storefront.sh","wt:e2e": "scripts/worktree/e2e.sh","changeset": "changeset","version:preview": "changeset version --ignore @spree/sdk"diff --git a/scripts/worktree/dev-storefront.sh b/scripts/worktree/dev-storefront.shnew file mode 100755index 0000000000..c3c84f3971--- /dev/null+++ b/scripts/worktree/dev-storefront.sh@@ -0,0 +1,65 @@+#!/usr/bin/env bash+# Start this worktree's Next.js storefront behind portless, against this+# worktree's Rails and this worktree's @spree/sdk build.+# URL: https://store.<branch>.spree.localhost+#+# The storefront is a separate repo (spree/storefront, branch 6-0-dev) cloned+# into storefront/ by setup.sh. It has its own pnpm project — deliberately not a+# member of this workspace, whose single lockfile and global overrides would+# have to cover Next 16 and the dashboard's Vite tree at once.+set -euo pipefail+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib.sh"+require_portless+cd "$(worktree_root)"++if [ ! -d storefront ]; then+ echo "storefront/ is missing — run pnpm wt:setup to clone it." >&2+ exit 1+fi++# A clone made before 6-0-dev was pushed sits on the storefront's default+# branch, which targets the released Store API — the opposite of what this+# worktree is for. Say so rather than let 6.0 changes look broken.+storefront_head=$(git -C storefront rev-parse --abbrev-ref HEAD)+if [ "$storefront_head" != "$STOREFRONT_BRANCH" ]; then+ echo " ! storefront/ is on '$storefront_head', not '$STOREFRONT_BRANCH' — it targets the released Store API." >&2+ echo " git -C storefront fetch origin && git -C storefront checkout $STOREFRONT_BRANCH" >&2+fi++# Absolute: pnpm resolves link: targets relative to the importer, and the same+# path is written into the storefront's lockfile.+SPREE_SDK_PATH="$(pwd)/packages/sdk"+export SPREE_SDK_PATH++write_storefront_env++echo "▸ Building @spree/sdk"+pnpm turbo build --filter='@spree/sdk'++# --no-frozen-lockfile: the pnpmfile redirects @spree/sdk at this worktree, so+# the lockfile necessarily differs from the committed one.+#+# That diff is left visible on purpose. Hiding it (skip-worktree) makes any pull+# that touches the lockfile fail with a misleading "local changes would be+# overwritten" — a worse trap than the diff. Restore it before committing in the+# clone: git checkout pnpm-lock.yaml+echo "▸ Installing storefront dependencies (SDK copied from this worktree)"+(cd storefront && pnpm install --silent --no-frozen-lockfile)++# The clone lives inside the worktree, so `wt remove` takes it — and any commits+# in it — along with everything else. Cheap to say once per boot.+if [ -n "$(git -C storefront log --branches --not --remotes --oneline 2>/dev/null)" ]; then+ echo " ! storefront/ has commits that are not on its remote — push before wt remove." >&2+fi++# Resolved before the cd below: every name here derives from the current git+# branch, and inside storefront/ that is the storefront's branch, not this+# worktree's — which would put the site on a URL keyed to the wrong worktree.+storefront_host="$(storefront_name)"+banner="▸ $(storefront_url) (API → $(rails_url))"++cd storefront+echo "$banner"+echo " SDK changes: rerun this script to rebuild and copy them in."+echo " storefront/pnpm-lock.yaml now points at this worktree's SDK — don't commit it."+portless "$storefront_host" sh -c 'exec pnpm next dev -p "$PORT" --turbopack'diff --git a/scripts/worktree/lib.sh b/scripts/worktree/lib.shindex 676dd90466..08b30dc03a 100755--- a/scripts/worktree/lib.sh+++ b/scripts/worktree/lib.sh@@ -7,6 +7,10 @@set -euo pipefailTEMPLATE_DB="spree_worktree_template"+# The storefront's 6.0 line. Its main branch stays on the released Store API for+# people forking or deploying it; 6-0-dev tracks the unreleased one we build here.+STOREFRONT_REPO="https://github.com/spree/storefront.git"+STOREFRONT_BRANCH="6-0-dev"# Same defaults as the starter's config/database.yml, so the psql tools and# Rails always agree on which server they are talking to. teardown runs after# the worktree (and its bundled Rails) is gone, so these cannot come from Rails.@@ -72,8 +76,10 @@ url_suffix() { [ "$(portless_port)" = "443" ] && echo "" || echo ":$(portless_porails_name() { echo "$(branch_slug).spree"; }dashboard_name() { echo "admin.$(branch_slug).spree"; }+storefront_name() { echo "store.$(branch_slug).spree"; }rails_url() { echo "https://$(rails_name).localhost$(url_suffix)"; }dashboard_url() { echo "https://$(dashboard_name).localhost$(url_suffix)"; }+storefront_url() { echo "https://$(storefront_name).localhost$(url_suffix)"; }# The marketplace seller panel — a separate app from the operator's dashboard,# so it gets its own host rather than a route inside it.seller_name() { echo "sellers.$(branch_slug).spree"; }@@ -83,6 +89,37 @@ rails_host() { echo "$(rails_name).localhost$(url_suffix)"; }port_free() { ! lsof -iTCP:"$1" -sTCP:LISTEN -n -P >/dev/null 2>&1; }+# Publishable API keys of the default store, read straight from Postgres — the+# token column is plaintext for publishable keys (only secret keys are hashed),+# so the storefront can be wired up without booting Rails.+#+# $1 selects the channel binding: "default" for the unbound key the DTC+# storefront uses, or a channel code for a bound one (the wholesale portal).+# Prints nothing when there is no such key, which callers treat as "skip".+publishable_key() {+ local binding="${1:-default}" filter++ if [ "$binding" = "default" ]; then+ filter="k.channel_id IS NULL"+ else+ filter="c.code = '${binding//\'/\'\'}'"+ fi++ psql "${PG_ARGS[@]}" -d "$(db_name)" -tAc "+ SELECT k.token+ FROM spree_api_keys k+ JOIN spree_stores s ON s.id = k.store_id+ LEFT JOIN spree_channels c ON c.id = k.channel_id+ WHERE k.key_type = 'publishable'+ AND k.revoked_at IS NULL+ AND k.token IS NOT NULL+ AND s.default+ AND $filter+ ORDER BY k.id+ LIMIT 1;+ " 2>/dev/null | tr -d '[:space:]'+}+# Even-numbered base in 20000-29999 (rails = base, vite = base+1), derived from# the branch so repeat runs reuse it. The hash space is smaller than the set of# branch names, so step to the next free pair when another run already holds it.@@ -101,6 +138,52 @@ e2e_base_port() {return 1}+# Write storefront/.env.local from this worktree's Rails URL and seeded keys.+#+# Called on every storefront boot, not just at provisioning: the publishable key+# lives in the worktree's database, so it changes whenever the database is+# reseeded or recreated from a newer template. A stale key authenticates as+# another store — or nothing at all — which reads as a broken storefront rather+# than a stale config, so it is cheaper to rewrite the file than to detect drift.+# Anything a developer adds below the generated block is preserved.+write_storefront_env() {+ local env_file="storefront/.env.local" key wholesale_key+ local marker="# --- your own settings below; everything above is regenerated on boot ---"++ key="$(publishable_key default)"+ if [ -z "$key" ]; then+ echo " ! No publishable API key in $(db_name) — storefront will not authenticate." >&2+ echo " Seed the database (cd server && bin/rails db:seed), then re-run." >&2+ fi+ wholesale_key="$(publishable_key wholesale)"++ # Keep whatever the developer put below the marker (Stripe test keys, GTM, a+ # different wholesale channel). grep -F and awk index() both match literally,+ # so the marker needs no regex escaping.+ local custom=""+ if [ -f "$env_file" ] && grep -qF "$marker" "$env_file"; then+ custom=$(awk -v m="$marker" 'found { print } index($0, m) { found = 1 }' "$env_file")+ fi++ {+ printf 'SPREE_API_URL=%s\n' "$(rails_url)"+ printf 'SPREE_PUBLISHABLE_KEY=%s\n' "$key"+ printf 'NEXT_PUBLIC_SITE_URL=%s\n' "$(storefront_url)"+ # The wholesale channel only exists in seeded databases; without the code the+ # storefront runs DTC-only and its /wholesale routes 404 by design.+ if [ -n "$wholesale_key" ]; then+ printf 'SPREE_WHOLESALE_CHANNEL=wholesale\n'+ printf 'SPREE_WHOLESALE_PUBLISHABLE_KEY=%s\n' "$wholesale_key"+ fi+ printf '\n%s\n' "$marker"+ # printf '%s\n' rather than '%s': $(...) strips trailing newlines, so the+ # last custom line would otherwise lose its own and merge with whatever a+ # later append writes.+ [ -n "$custom" ] && printf '%s\n' "$custom"+ } > "$env_file.tmp"+ mv "$env_file.tmp" "$env_file"+}+require_portless() {command -v portless >/dev/null || {echo "portless not found — install with: npm install -g portless (Node >= 24)" >&2diff --git a/scripts/worktree/setup.sh b/scripts/worktree/setup.shindex 7d6fb1002a..3a5f163ddb 100755--- a/scripts/worktree/setup.sh+++ b/scripts/worktree/setup.sh@@ -9,6 +9,32 @@ WT_BRANCH="${1:-}"source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib.sh"cd "$(worktree_root)"+# Clone the Next.js storefront and point it at this worktree's Rails + seeded+# publishable keys. Unlike server/, the clone keeps its .git: the starter is a+# disposable host app, while the storefront is a repo we actually develop in and+# push from, so each worktree gets its own branch-able checkout.+#+# .env.local is only written when absent, so local edits (Stripe keys, a+# different channel) survive a re-run. It is regenerated by dev-storefront.sh+# on every boot for the values that follow the worktree — the API URL and keys.+setup_storefront() {+ if [ ! -d storefront ]; then+ echo "▸ Cloning storefront into storefront/"+ # Non-fatal: the storefront is optional, and most worktrees never boot it.+ # A failure here (offline, no access) must not abandon a provisioning run+ # that has already created the database and installed gems.+ if ! git clone --quiet --branch "$STOREFRONT_BRANCH" "$STOREFRONT_REPO" storefront; then+ echo " ! Could not clone the storefront — skipping. Re-run this script to retry." >&2+ rm -rf storefront+ return 0+ fi+ fi++ if [ ! -f storefront/.env.local ]; then+ write_storefront_env+ fi+}+echo "▸ Provisioning worktree '$(branch_slug)' (db: $(db_name))"if [ ! -d server ]; then@@ -90,9 +116,12 @@ pnpm install --silentmkdir -p packages/dashboard-starterprintf 'VITE_API_PROXY_TARGET=%s\n' "$(rails_url)" > packages/dashboard-starter/.env.local+setup_storefront+echo "✓ Worktree ready"-echo " rails: $(rails_url) (pnpm wt:dev)"-echo " dashboard: $(dashboard_url) (pnpm wt:dashboard)"-echo " seller: $(seller_url) (pnpm wt:seller)"-echo " mail: $(mailpit_url)"+echo " rails: $(rails_url) (pnpm wt:dev)"+echo " dashboard: $(dashboard_url) (pnpm wt:dashboard)"+echo " seller: $(seller_url) (pnpm wt:seller)"+echo " storefront: $(storefront_url) (pnpm wt:storefront)"+echo " mail: $(mailpit_url)"warn_unless_mailpit