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.

Register the dashboard in the project's Render Blueprint

Damian Legawiecc71039b59892
diff --git a/docs/developer/dashboard/deployment.mdx b/docs/developer/dashboard/deployment.mdx
new file mode 100644
index 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_` variable
diff --git a/docs/docs.json b/docs/docs.json
index 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.ts
index 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: AddDashboardOption
writeDashboardEnv(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.ts
index 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')
+ })
+ })
})