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
Register the dashboard in the project's Render Blueprint
Damian Legawiecc71039b59892
diff --git a/docs/developer/dashboard/deployment.mdx b/docs/developer/dashboard/deployment.mdxnew file mode 100644index 0000000000..c872686f45--- /dev/null+++ b/docs/developer/dashboard/deployment.mdx@@ -0,0 +1,65 @@+---+title: Deploying the dashboard+sidebarTitle: Deployment+description: Ship the React Dashboard to production — a static build served from a CDN or reverse proxy, with the API's CORS and cookie settings to match.+---++The dashboard deploys as **static files**. `pnpm build` produces `dist/` — HTML, JS, CSS — and any static host can serve it; there is no Node server in production. The API URL is baked in at build time:++```bash+cd apps/dashboard+VITE_SPREE_API_URL=https://api.mystore.com pnpm build+```++<Warning>+`VITE_`-prefixed values are compiled into the client bundle — never put credentials in them. The dashboard authenticates admins interactively (JWT in memory + an httpOnly refresh cookie); no API keys are involved.+</Warning>++## Pick a topology++**Cross-origin (dashboard and API on different domains)** — the default for static hosts (Render, Cloudflare Pages, Netlify, S3+CloudFront). Three requirements:++1. **HTTPS on both sides.** The refresh cookie is issued with `SameSite=None; Secure` in production, and browsers drop `Secure` cookies over HTTP. There is no insecure-production mode.+2. **Allowed Origins.** Add the dashboard's URL (e.g. `https://dashboard.mystore.com`) to **Settings → Allowed Origins** in the Spree admin — the API rejects cross-origin requests until then.+3. **SPA fallback.** Every path must rewrite to `index.html` so the router owns the URL (`/* → /index.html` on your host).++**Same-origin (one domain, reverse proxy)** — serve `dist/` and proxy `/api/*` and `/rails/*` to the Rails server from the same origin, mirroring what the Vite dev proxy does. No CORS entries, `SameSite=Lax` cookies, one certificate — the simpler security posture if you already run nginx/Caddy or an ingress.++## Render++If your project deploys to Render via the Blueprint that `create-spree-app` places at the project root, `spree add dashboard` registers the dashboard automatically — it appends a static-site service to `render.yaml`:++```yaml+- type: web+ name: spree-dashboard+ runtime: static+ rootDir: apps/dashboard+ buildCommand: corepack enable pnpm && pnpm install && pnpm build+ staticPublishPath: dist+ routes:+ - type: rewrite+ source: /*+ destination: /index.html+ envVars:+ - key: VITE_SPREE_API_URL+ sync: false+```++Static sites on Render are CDN-served with the SPA rewrite built in, so only the two cross-origin steps remain manual:++1. **Set `VITE_SPREE_API_URL`** when Render prompts for it (that's what `sync: false` does) — the backend's public URL, e.g. `https://spree-abc123.onrender.com` or your custom API domain.+2. **Add the dashboard's Render URL to Allowed Origins** in the Spree admin after the first deploy.++Redeploys rebuild automatically on push, and each Render environment (staging, production) builds its own bundle with its own API URL.++## Any other static host++The same three ingredients, by hand: build with `VITE_SPREE_API_URL` set, upload `dist/`, configure the `/* → /index.html` rewrite (`_redirects` on Netlify, `vercel.json` rewrites on Vercel, `try_files $uri /index.html;` on nginx). Then add the origin to Allowed Origins.++## Checklist++- [ ] `VITE_SPREE_API_URL` points at the production API (baked at build time — one build per environment)+- [ ] HTTPS on the dashboard *and* the API+- [ ] Dashboard origin added to **Settings → Allowed Origins**+- [ ] All paths rewrite to `index.html`+- [ ] No secrets in any `VITE_` variablediff --git a/docs/docs.json b/docs/docs.jsonindex 5967e27891..a849cc0dc6 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -432,6 +432,12 @@"developer/dashboard/plugins/distributing"]},+ {+ "group": "Deployment",+ "pages": [+ "developer/dashboard/deployment"+ ]+ },{"group": "Slots Catalog","pages": [diff --git a/packages/cli/src/commands/add.ts b/packages/cli/src/commands/add.tsindex 73f9d4d45a..c65a90563b 100644--- a/packages/cli/src/commands/add.ts+++ b/packages/cli/src/commands/add.ts@@ -67,6 +67,7 @@ export async function addDashboard(ctx: ProjectContext, opts: AddDashboardOption}// Recovery: directory present but env missing (interrupted earlier run).writeDashboardEnv(envPath, ctx.port)+ ensureRenderBlueprintService(ctx.projectDir, detectPackageManager(ctx.projectDir, dashboardDir))p.log.info(`Wrote missing ${pc.bold('apps/dashboard/.env.local')}. Nothing else to do.`)return}@@ -85,8 +86,16 @@ export async function addDashboard(ctx: ProjectContext, opts: AddDashboardOptionwriteDashboardEnv(envPath, ctx.port)+ const pm = detectPackageManager(ctx.projectDir, dashboardDir)+ if (ensureRenderBlueprintService(ctx.projectDir, pm) === 'added') {+ p.log.info(+ `Added a static-site service to ${pc.bold('render.yaml')}. At deploy, set ` ++ `${pc.cyan('VITE_SPREE_API_URL')} to the backend's public URL and add the ` ++ `dashboard's URL to Allowed Origins in the Spree admin.`,+ )+ }+if (opts.install) {- const pm = detectPackageManager(ctx.projectDir, dashboardDir)s.start(`Installing dependencies with ${pm}...`)try {await execa(pm, ['install'], { cwd: dashboardDir })@@ -137,6 +146,67 @@ function resolveBundledTemplate(): string {process.exit(1)}+/**+ * Register the dashboard as a static-site service in the project's Render+ * Blueprint, when one exists (create-spree-app relocates spree-starter's+ * render.yaml to the project root). Static sites on Render are CDN-served+ * with SPA rewrites, which is exactly the dashboard's production shape:+ * `vite build` → `dist/`, no Node server. Two things stay manual by design:+ * `VITE_SPREE_API_URL` (`sync: false` makes Render prompt — the backend's+ * public URL isn't knowable here) and the Allowed Origins entry on the+ * Spree side (the API rejects cross-origin calls until the merchant adds+ * the dashboard's URL).+ *+ * Idempotent: an existing `spree-dashboard` service is left untouched.+ */+export function ensureRenderBlueprintService(+ projectDir: string,+ pm: string,+): 'added' | 'present' | 'no-blueprint' {+ const renderYamlPath = path.join(projectDir, 'render.yaml')+ if (!fs.existsSync(renderYamlPath)) return 'no-blueprint'++ const content = fs.readFileSync(renderYamlPath, 'utf-8')+ if (content.includes('name: spree-dashboard')) return 'present'++ const buildCommand =+ pm === 'pnpm'+ ? 'corepack enable pnpm && pnpm install && pnpm build'+ : pm === 'yarn'+ ? 'yarn install && yarn build'+ : 'npm install && npm run build'++ const service = `+ # React Dashboard (Developer Preview) — a static site built from+ # apps/dashboard. After the first deploy:+ # 1. Set VITE_SPREE_API_URL to the backend's public URL (Render prompts).+ # 2. Add the dashboard's URL to Allowed Origins in the Spree admin so the+ # API accepts its cross-origin requests and auth cookies.+ - type: web+ name: spree-dashboard+ runtime: static+ rootDir: apps/dashboard+ buildCommand: ${buildCommand}+ staticPublishPath: dist+ routes:+ - type: rewrite+ source: /*+ destination: /index.html+ envVars:+ - key: VITE_SPREE_API_URL+ sync: false+`++ // Keep the service inside the `services:` array: insert before the+ // top-level `databases:` key when present, else append.+ const databasesMatch = /^databases:/m.exec(content)+ const next = databasesMatch+ ? `${content.slice(0, databasesMatch.index)}${service}\n${content.slice(databasesMatch.index)}`+ : `${content.trimEnd()}\n${service}`+ fs.writeFileSync(renderYamlPath, next)+ return 'added'+}+/*** The bundled template ships its `.gitignore` as `gitignore.template`* (npm never packs `.gitignore` files) — restore the real name on scaffold.diff --git a/packages/cli/tests/add-dashboard.test.ts b/packages/cli/tests/add-dashboard.test.tsindex 64e968fd77..d7263d427d 100644--- a/packages/cli/tests/add-dashboard.test.ts+++ b/packages/cli/tests/add-dashboard.test.ts@@ -2,7 +2,7 @@ import fs from 'node:fs'import os from 'node:os'import path from 'node:path'import { afterEach, beforeEach, describe, expect, it } from 'vitest'-import { addDashboard } from '../src/commands/add.js'+import { addDashboard, ensureRenderBlueprintService } from '../src/commands/add.js'import type { ProjectContext } from '../src/types.js'/**@@ -75,4 +75,63 @@ describe('addDashboard', () => {await addDashboard(ctx(), { template: templateDir, install: false })expect(fs.readFileSync(envPath, 'utf-8')).toContain('http://localhost:3999')})++ describe('Render Blueprint registration', () => {+ const BLUEPRINT = `services:+ - type: web+ name: spree+ runtime: ruby+ rootDir: backend++ - type: redis+ name: spree-redis++databases:+ - name: spree-db+`++ it('adds a static-site service inside the services array', async () => {+ fs.writeFileSync(path.join(projectDir, 'render.yaml'), BLUEPRINT)++ await addDashboard(ctx(), { template: templateDir, install: false })++ const content = fs.readFileSync(path.join(projectDir, 'render.yaml'), 'utf-8')+ expect(content).toContain('name: spree-dashboard')+ expect(content).toContain('runtime: static')+ expect(content).toContain('rootDir: apps/dashboard')+ expect(content).toContain('staticPublishPath: dist')+ expect(content).toContain('destination: /index.html')+ expect(content).toContain('sync: false')+ // Stays inside the services array — before the top-level databases key.+ expect(content.indexOf('spree-dashboard')).toBeLessThan(content.indexOf('databases:'))+ })++ it('is idempotent and picks the build command from the project lockfile', async () => {+ fs.writeFileSync(path.join(projectDir, 'render.yaml'), BLUEPRINT)+ fs.writeFileSync(path.join(projectDir, 'package-lock.json'), '{}')++ expect(ensureRenderBlueprintService(projectDir, 'npm')).toBe('added')+ const once = fs.readFileSync(path.join(projectDir, 'render.yaml'), 'utf-8')+ expect(once).toContain('buildCommand: npm install && npm run build')++ expect(ensureRenderBlueprintService(projectDir, 'npm')).toBe('present')+ expect(fs.readFileSync(path.join(projectDir, 'render.yaml'), 'utf-8')).toBe(once)+ })++ it('does nothing when the project has no Blueprint', async () => {+ expect(ensureRenderBlueprintService(projectDir, 'pnpm')).toBe('no-blueprint')+ expect(fs.existsSync(path.join(projectDir, 'render.yaml'))).toBe(false)+ })++ it('appends at the end when there is no databases key', () => {+ fs.writeFileSync(+ path.join(projectDir, 'render.yaml'),+ 'services:\n - type: web\n name: spree\n',+ )+ expect(ensureRenderBlueprintService(projectDir, 'pnpm')).toBe('added')+ const content = fs.readFileSync(path.join(projectDir, 'render.yaml'), 'utf-8')+ expect(content).toContain('name: spree-dashboard')+ expect(content).toContain('corepack enable pnpm && pnpm install && pnpm build')+ })+ })})