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.

Add ability to run local storefront copy with monorepo SDKs

Damian Legawieccee71bd1d5e2
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 4af670842b..838ff1211d 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -24,6 +24,7 @@ Please read our [Code of Conduct](../CODE_OF_CONDUCT.md) before contributing.
- [Common commands](#common-commands)
- [Package-specific commands](#package-specific-commands)
- [Working on the React dashboard](#working-on-the-react-dashboard)
+ - [Working on the storefront](#working-on-the-storefront)
- [Dashboard E2E tests](#dashboard-e2e-tests)
- [Type generation](#type-generation)
- [Releasing packages](#releasing-packages)
@@ -77,8 +78,11 @@ When it's done, the backend is up at [http://localhost:3000](http://localhost:30
```bash
pnpm dashboard:dev # admin dashboard → http://localhost:5173 (proxies /api to :3000)
pnpm seller:dev # seller panel → http://localhost:5174
+pnpm storefront:dev # Next.js storefront → http://localhost:3001
```
+`pnpm storefront:dev` clones the [Next.js storefront](https://github.com/spree/storefront) into `storefront/` on first run and wires it to this checkout — see [Working on the storefront](#working-on-the-storefront).
+
The setup command finishes by printing a **one-time setup link** (`http://localhost:5173/setup?token=…`) — with `pnpm dashboard:dev` running, open it to create the first admin account. If you lose the link, print it again with:
```bash
@@ -117,7 +121,7 @@ cd server
pnpm exec spree migrate
pnpm exec spree generate model Brand name:string
pnpm exec spree upgrade --plan
-``
+```
See the [`@spree/cli` README](../packages/cli/README.md) for the full command surface.
@@ -130,7 +134,6 @@ Which command after which change:
| Gem dependencies (gemspec / Gemfile / lock drift after `git pull`) | Nothing — the next `pnpm server:dev` boot self-heals via `bundle check | | bundle install` (or `cd server && pnpm exec spree bundle install` while the stack runs) |
| Compose files / `server/.env` | `pnpm server:dev` (force-recreates the containers) |
| `server/Dockerfile` / `.ruby-version` / starter update that breaks the image build ("lockfile can't be updated because frozen") | `pnpm server:build`, then `pnpm server:dev` — the build script handles the edge-rewritten `Gemfile.lock` automatically |
-| Meilisearch image bump ("database version … is incompatible") | Remove the `server_meilisearch_data` volume, boot, then reindex (`pnpm exec spree rake spree:search:reindex`) — the index is derived data |
| Broken beyond repair | `pnpm server:setup` (full reset — wipes the database and volumes) |
Re-run `pnpm server:setup` **only** to fully reset — it starts with the same teardown as `pnpm server:teardown` (`docker compose down -v` + `rm -rf ./server`), wiping all DB data.
@@ -322,6 +325,27 @@ Don't use `VITE_SPREE_API_URL` in dev — it switches the SDK to absolute cross-
See `packages/dashboard/README.md` for the full architecture (auth, permissions, extension points, the three-package split between `dashboard`, `dashboard-core`, and `dashboard-ui`).
+### Working on the storefront
+
+The [Next.js storefront](https://github.com/spree/storefront) is a separate repository. `pnpm storefront:dev` clones it into `storefront/` (gitignored) on first run, on its **`6-0-dev`** branch — `main` targets the released Store API and won't work against this monorepo's backend. Unlike `server/`, the clone keeps its `.git`: commit and push storefront changes from inside `storefront/`.
+
+```bash
+# Terminal 1: backend
+pnpm server:dev
+
+# Terminal 2: storefront
+pnpm storefront:dev # http://localhost:3001
+```
+
+Load sample data first (`pnpm server:load_sample_data`) so the storefront has products to show.
+
+Every boot regenerates `storefront/.env.local` with the backend URL and the seeded publishable key (anything you add below the marker line is preserved), rebuilds `@spree/sdk` from this checkout's `packages/sdk`, and installs it into the storefront. Two consequences:
+
+- The SDK is **copied**, not linked — after changing SDK code (or regenerating its types from serializers), re-run `pnpm storefront:dev` to pick the changes up.
+- The install rewrites `storefront/pnpm-lock.yaml` to point at the local SDK. Restore it before committing inside the clone: `git -C storefront checkout pnpm-lock.yaml`.
+
+`pnpm server:teardown` leaves `storefront/` alone — it only removes the backend.
+
### Dashboard E2E tests
The React dashboard ships an end-to-end suite running on [Playwright](https://playwright.dev/) against a real Rails backend — no mocks. The spec files exercise the full UI: login, staff invitation, invitee signup. CI runs the same suite via the `dashboard-e2e` job in `.github/workflows/packages.yml`.
diff --git a/package.json b/package.json
index 82d98b6680..c966bb7276 100644
--- a/package.json
+++ b/package.json
@@ -26,6 +26,7 @@
"server:load_sample_data": "cd server && spree task load_sample_data",
"dashboard:dev": "turbo build --filter='@spree/dashboard-starter^...' && pnpm --dir packages/dashboard-starter dev --port 5173 --strictPort",
"seller:dev": "turbo build --filter='@spree/seller-dashboard-starter^...' && pnpm --dir packages/seller-dashboard-starter dev --port 5174 --strictPort",
+ "storefront:dev": "bash scripts/storefront-dev.sh",
"wt:setup": "scripts/worktree/setup.sh",
"wt:template": "scripts/worktree/make-template.sh",
"wt:dev": "scripts/worktree/dev.sh",
diff --git a/scripts/server-setup.sh b/scripts/server-setup.sh
index 4e699d991b..07c582fe2d 100755
--- a/scripts/server-setup.sh
+++ b/scripts/server-setup.sh
@@ -85,9 +85,10 @@ step "Fetching the one-time first-run setup link"
SETUP_URL="$(SPREE_PATH="$ROOT" docker compose -f "$DEV_COMPOSE" -f "$EDGE_OVERLAY" exec -T web bin/rails spree:setup:token 2>/dev/null | tr -d '\r' | grep -oE 'https?://[^[:space:]]+' | tail -1 || true)"
printf '\nBackend ready: http://localhost:3000\n\n'
-printf 'The React dashboard and seller panel run as their own dev servers:\n'
+printf 'The React dashboard, seller panel and storefront run as their own dev servers:\n'
printf ' pnpm dashboard:dev # admin dashboard → http://localhost:5173\n'
-printf ' pnpm seller:dev # seller panel → http://localhost:5174\n\n'
+printf ' pnpm seller:dev # seller panel → http://localhost:5174\n'
+printf ' pnpm storefront:dev # storefront → http://localhost:3001\n\n'
if [ -n "$SETUP_URL" ]; then
printf 'Then create the first admin account (one-time link, needs dashboard:dev running):\n %s\n\n' "$SETUP_URL"
printf 'Print it again later with:\n SPREE_PATH="$PWD" docker compose -f %s -f %s exec web bin/rails spree:setup:token\n\n' "$DEV_COMPOSE" "$EDGE_OVERLAY"
diff --git a/scripts/storefront-dev.sh b/scripts/storefront-dev.sh
new file mode 100755
index 0000000000..60e217408f
--- /dev/null
+++ b/scripts/storefront-dev.sh
@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# storefront-dev.sh — run the Next.js storefront against the Docker backend
+# (`pnpm server:setup` / `pnpm server:dev`). The Docker twin of the worktree
+# flow's `pnpm wt:storefront`.
+#
+# The storefront is a separate repo (spree/storefront, branch 6-0-dev) cloned
+# into storefront/ on first run. Unlike server/, the clone keeps its .git —
+# commit and push storefront work from inside it. It is deliberately not a
+# member of this pnpm workspace (one lockfile cannot serve Next and the
+# dashboard's Vite tree at once); it points @spree/sdk at packages/sdk through
+# its own .pnpmfile.cjs whenever SPREE_SDK_PATH is set.
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+
+DEV_COMPOSE="server/docker-compose.dev.yml"
+EDGE_OVERLAY="scripts/docker-compose.edge.yml"
+STOREFRONT_REPO="https://github.com/spree/storefront.git"
+STOREFRONT_BRANCH="6-0-dev"
+STOREFRONT_PORT="${STOREFRONT_PORT:-3001}"
+API_URL="http://localhost:3000"
+
+step() { printf '\n→ %s\n' "$1"; }
+
+# The publishable key lives in the backend's database, so the stack must be up.
+if [ ! -f "$DEV_COMPOSE" ] || [ -z "$(SPREE_PATH="$ROOT" docker compose -f "$DEV_COMPOSE" -f "$EDGE_OVERLAY" ps -q web 2>/dev/null)" ]; then
+ echo "The backend is not running — pnpm server:setup (once), then pnpm server:dev." >&2
+ exit 1
+fi
+
+if [ ! -d storefront ]; then
+ step "Cloning spree/storefront (branch $STOREFRONT_BRANCH) into storefront/"
+ git clone --branch "$STOREFRONT_BRANCH" "$STOREFRONT_REPO" storefront
+fi
+
+# A clone on the storefront's default branch targets the released Store API —
+# the opposite of what this monorepo backend serves.
+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
+
+step "Reading the seeded publishable API keys from the backend"
+# Rewritten on every boot, not just at provisioning: the key changes whenever
+# the database is reseeded, and a stale key reads as a broken storefront
+# rather than a stale config.
+KEYS="$(SPREE_PATH="$ROOT" docker compose -f "$DEV_COMPOSE" -f "$EDGE_OVERLAY" exec -T web bin/rails runner - <<'RUBY' | tr -d '\r'
+rows = ActiveRecord::Base.connection.select_rows(<<~SQL)
+ SELECT COALESCE(c.code, 'default'), 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 (k.channel_id IS NULL OR c.code = 'wholesale')
+ ORDER BY k.id
+SQL
+rows.each { |channel, token| puts "#{channel}=#{token}" }
+RUBY
+)"
+key="$(printf '%s\n' "$KEYS" | sed -n 's/^default=//p' | head -1)"
+wholesale_key="$(printf '%s\n' "$KEYS" | sed -n 's/^wholesale=//p' | head -1)"
+
+if [ -z "$key" ]; then
+ echo " ! No publishable API key in the database — the storefront will not authenticate." >&2
+ echo " Seed the database (pnpm server:seed), then re-run." >&2
+fi
+
+step "Writing storefront/.env.local"
+env_file="storefront/.env.local"
+marker="# --- your own settings below; everything above is regenerated on boot ---"
+
+# 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.
+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' "$API_URL"
+ printf 'SPREE_PUBLISHABLE_KEY=%s\n' "$key"
+ printf 'NEXT_PUBLIC_SITE_URL=http://localhost:%s\n' "$STOREFRONT_PORT"
+ # 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.
+ if [ -n "$custom" ]; then printf '%s\n' "$custom"; fi
+} > "$env_file.tmp"
+mv "$env_file.tmp" "$env_file"
+
+# Absolute: pnpm resolves the redirected dependency relative to the importer,
+# and the same path lands in the storefront's lockfile.
+SPREE_SDK_PATH="$ROOT/packages/sdk"
+export SPREE_SDK_PATH
+
+step "Building @spree/sdk"
+pnpm turbo build --filter='@spree/sdk'
+
+# --no-frozen-lockfile: the pnpmfile redirects @spree/sdk at this checkout, so
+# the lockfile necessarily differs from the committed one. Restore it before
+# committing inside the clone: git -C storefront checkout pnpm-lock.yaml
+step "Installing storefront dependencies (SDK copied from this checkout)"
+(cd storefront && pnpm install --silent --no-frozen-lockfile)
+
+step "Starting the storefront"
+echo "▸ http://localhost:$STOREFRONT_PORT (API → $API_URL)"
+echo " SDK changes: rerun this script to rebuild and copy them in."
+echo " storefront/pnpm-lock.yaml now points at this checkout's SDK — don't commit it."
+cd storefront
+exec pnpm next dev -p "$STOREFRONT_PORT" --turbopack