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.

Run the storefront in a worktree (#14495)

Damian Legawiec610fcac7bc89
diff --git a/.gitignore b/.gitignore
index 73bec41e8c..885d65f263 100644
--- a/.gitignore
+++ b/.gitignore
@@ -55,6 +55,9 @@ brakeman-*.*
*/app/assets/builds
.claude/worktrees
server/
+# 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_modules
package-lock.json
packages/*/package-lock.json
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.localhost
pnpm wt:seller # seller panel → https://sellers.feature-x.spree.localhost
+pnpm wt:storefront # Next.js storefront → https://store.feature-x.spree.localhost
pnpm wt:e2e [spec...] # Playwright on this worktree's own port block
pnpm wt:template # rebuild the template DB after schema-changing pulls
wt 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.json
index 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.sh
new file mode 100755
index 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.sh
index 676dd90466..08b30dc03a 100755
--- a/scripts/worktree/lib.sh
+++ b/scripts/worktree/lib.sh
@@ -7,6 +7,10 @@
set -euo pipefail
TEMPLATE_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_po
rails_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)" >&2
diff --git a/scripts/worktree/setup.sh b/scripts/worktree/setup.sh
index 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 --silent
mkdir -p packages/dashboard-starter
printf '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