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
Add ability to run local storefront copy with monorepo SDKs
Damian Legawieccee71bd1d5e2
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.mdindex 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```bashpnpm 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 serverpnpm exec spree migratepnpm exec spree generate model Brand name:stringpnpm 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 testsThe 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.jsonindex 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.shindex 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" ]; thenprintf '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.shnew file mode 100755index 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