@pradip1995/create-storefront-app 0.3.0 → 0.4.0

package/bin/create-storefront-app.js

@@ -195,7 +195,7 @@ function scaffoldProject(args) {
         "storefront:build": "npm run storefront:build --prefix storefront",
         "dev:backend": "npm run dev --prefix backend",
         "build:backend": "npm run build --prefix backend",
-        seed: "npm run seed --prefix backend",
+        seed: "npm run seed --prefix backend && node scripts/sync-publishable-key.mjs --from-db",
       },
     }
     writeJson(join(projectRoot, "package.json"), rootPkg)
@@ -208,6 +208,12 @@ function scaffoldProject(args) {
     scaffoldStorefront(join(projectRoot, "storefront"), args)
     scaffoldBackend(join(projectRoot, "backend"), args)
     scaffoldDocker(projectRoot, args)
+
+    mkdirSync(join(projectRoot, "scripts"), { recursive: true })
+    cpSync(
+      join(PKG_ROOT, "templates/root/scripts/sync-publishable-key.mjs"),
+      join(projectRoot, "scripts/sync-publishable-key.mjs")
+    )
   } else {
     scaffoldStorefront(projectRoot, args, { flat: true })
     writeFileSync(

package/lib/scaffold-backend.js

@@ -1,16 +1,13 @@
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs"
 import { join, dirname } from "path"
 import { fileURLToPath } from "url"
-import { buildBackendPackageJson, VERSIONS } from "./build-backend-package.js"
+import { buildBackendDependencies, VERSIONS } from "./build-backend-package.js"
 import { buildDockerTemplateVars } from "./docker-template-vars.js"
-import { createRequire } from "module"
-
-const require = createRequire(import.meta.url)
-const { buildHomepageConfigDefaults } = require("./build-homepage-defaults.cjs")
+import { FRAMEWORK_COMPILER_VERSION } from "./versions.js"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const PKG_ROOT = join(__dirname, "..")
-const BACKEND_TEMPLATE = join(PKG_ROOT, "templates", "backend")
+const BACKEND_CURSOR = join(PKG_ROOT, "templates", "backend", ".cursor")
 
 const REGION_CURRENCY = {
   in: { currency: "inr", name: "India" },
@@ -32,6 +29,16 @@ function regionMeta(defaultRegion) {
   )
 }
 
+function buildPluginsConfig(preset) {
+  const { medusa, plugins } = buildBackendDependencies(preset)
+  return { medusa, plugins }
+}
+
+function writeJson(path, data) {
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`)
+}
+
+/** Scaffold config-only backend/ — Medusa source is generated by backend-build. */
 export function scaffoldBackend(backendRoot, args) {
   const { preset, name, backendUrl, baseUrl, defaultRegion } = args
   const meta = regionMeta(defaultRegion)
@@ -51,56 +58,66 @@ export function scaffoldBackend(backendRoot, args) {
 
   mkdirSync(backendRoot, { recursive: true })
 
-  const medusaConfigSrc =
-    preset === "minimal"
-      ? join(BACKEND_TEMPLATE, "medusa-config.minimal.ts")
-      : join(BACKEND_TEMPLATE, "medusa-config.full.ts")
-  writeFileSync(join(backendRoot, "medusa-config.ts"), readFileSync(medusaConfigSrc, "utf8"))
-
-  cpSync(join(BACKEND_TEMPLATE, "tsconfig.json"), join(backendRoot, "tsconfig.json"))
-  cpSync(join(BACKEND_TEMPLATE, "gitignore"), join(backendRoot, ".gitignore"))
-  cpSync(join(PKG_ROOT, "templates/shared/npmrc"), join(backendRoot, ".npmrc"))
-  cpSync(join(BACKEND_TEMPLATE, "config"), join(backendRoot, "config"), { recursive: true })
-  cpSync(join(BACKEND_TEMPLATE, "src"), join(backendRoot, "src"), { recursive: true })
-  cpSync(join(BACKEND_TEMPLATE, "scripts"), join(backendRoot, "scripts"), { recursive: true })
-
-  const homepageSchema = JSON.parse(
-    readFileSync(join(backendRoot, "config/homepage-config.json"), "utf8")
-  )
-  writeFileSync(
-    join(backendRoot, "config/homepage-config.defaults.json"),
-    `${JSON.stringify(buildHomepageConfigDefaults(homepageSchema), null, 2)}\n`
-  )
+  writeJson(join(backendRoot, "backend.config.json"), {
+    preset,
+    projectName: name,
+    defaultRegion,
+  })
+
+  writeJson(join(backendRoot, "plugins.config.json"), buildPluginsConfig(preset))
 
   writeFileSync(
-    join(backendRoot, "config", "medusa-plugin-versions.json"),
-    JSON.stringify(VERSIONS, null, 2) + "\n"
+    join(backendRoot, ".gitignore"),
+    readFileSync(join(PKG_ROOT, "templates/backend/gitignore"), "utf8")
   )
-
-  const seedContent = applyTemplate(
-    readFileSync(join(BACKEND_TEMPLATE, "src/scripts/seed.ts"), "utf8"),
-    templateVars
+  writeFileSync(
+    join(backendRoot, ".npmrc"),
+    readFileSync(join(PKG_ROOT, "templates/shared/npmrc"), "utf8")
   )
-  mkdirSync(join(backendRoot, "src/scripts"), { recursive: true })
-  writeFileSync(join(backendRoot, "src/scripts/seed.ts"), seedContent)
 
+  const envTemplate = join(PKG_ROOT, "templates/backend/env.template")
   writeFileSync(
     join(backendRoot, ".env.template"),
-    applyTemplate(readFileSync(join(BACKEND_TEMPLATE, "env.template"), "utf8"), templateVars)
+    applyTemplate(readFileSync(envTemplate, "utf8"), templateVars)
   )
   writeFileSync(
     join(backendRoot, ".env"),
-    applyTemplate(readFileSync(join(BACKEND_TEMPLATE, "env.template"), "utf8"), templateVars)
+    applyTemplate(readFileSync(envTemplate, "utf8"), templateVars)
   )
-
   writeFileSync(
-    join(backendRoot, "package.json"),
-    JSON.stringify(buildBackendPackageJson(preset, name), null, 2) + "\n"
+    join(backendRoot, ".env.example"),
+    applyTemplate(readFileSync(envTemplate, "utf8"), {
+      ...templateVars,
+      DATABASE_URL: "postgres://user:pass@localhost:5432/medusa",
+    })
   )
 
-  const backendCursor = join(BACKEND_TEMPLATE, ".cursor")
-  if (existsSync(backendCursor)) {
-    cpSync(backendCursor, join(backendRoot, ".cursor"), { recursive: true })
+  const backendReadme = join(PKG_ROOT, "templates/backend/README.md")
+  if (existsSync(backendReadme)) {
+    writeFileSync(join(backendRoot, "README.md"), readFileSync(backendReadme, "utf8"))
+  }
+
+  writeJson(join(backendRoot, "package.json"), {
+    name: `${name}-backend`,
+    private: true,
+    scripts: {
+      "backend:build": "backend-build",
+      dev: "npm run backend:build && cd .generated-backend && npm install && npm run dev",
+      build:
+        "npm run backend:build && cd .generated-backend && npm install && npm run build",
+      start:
+        "npm run backend:build && cd .generated-backend && npm install && npm run start",
+      seed: "npm run backend:build && cd .generated-backend && npm install && npm run seed",
+      "dynamic-config:defaults":
+        "npm run backend:build && cd .generated-backend && npm run dynamic-config:defaults",
+    },
+    dependencies: {
+      "@pradip1995/framework-compiler": FRAMEWORK_COMPILER_VERSION,
+    },
+  })
+
+  if (existsSync(BACKEND_CURSOR)) {
+    cpSync(BACKEND_CURSOR, join(backendRoot, ".cursor"), { recursive: true })
   }
 
   return backendRoot

package/lib/versions.js

@@ -1,7 +1,7 @@
 /** Published package semver ranges — bump when releasing framework/components. */
 export const COMMERCE_CORE_VERSION = "^4.0.2"
 export const FRAMEWORK_VERSION = "^0.2.1"
-export const FRAMEWORK_COMPILER_VERSION = "^0.2.4"
+export const FRAMEWORK_COMPILER_VERSION = "^0.3.0"
 export const COMPONENTS_VERSION = ">=0.2.0 <0.4.0"
 
 export const FRAMEWORK_PACKAGES = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pradip1995/create-storefront-app",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Scaffold a segment-based Medusa storefront using @pradip1995/framework packages",
   "license": "MIT",
   "type": "module",

package/templates/backend/.cursor/commands/seed-backend.md

@@ -1,16 +1,21 @@
 # Seed Medusa backend
 
-From project root:
+From project root (recommended — also syncs publishable key to storefront):
+
+```bash
+npm run seed
+```
+
+Backend only:
 
 ```bash
 cd backend
 npm run seed
+node ../scripts/sync-publishable-key.mjs --from-db
 ```
 
 Requires PostgreSQL running and `DATABASE_URL` set in `backend/.env`.
 
-After seed:
+## After seed
 
-1. Start backend: `npm run dev`
-2. Copy publishable API key from Admin into `storefront/.env.local`
-3. Start storefront: `cd ../storefront && npm run dev`
+`scripts/sync-publishable-key.mjs` reads the publishable key from Postgres and updates `storefront/.env.local`. Then start storefront: `npm run dev:storefront`.

package/templates/backend/.cursor/rules/medusa-backend.mdc

@@ -1,55 +1,49 @@
 ---
-description: Medusa backend — config, plugins, env, seed
+description: Medusa backend — config-only client, generated on dev/build
 globs: backend/**/*
 alwaysApply: false
 ---
 
-# Medusa backend
+# Medusa backend (config client)
 
-## Key files
+Generated Medusa source lives in `.generated-backend/` (gitignored). Same pattern as `storefront/.generated-app/`.
+
+## Committed source
 
 | File | Purpose |
 |------|---------|
-| `medusa-config.ts` | Plugins + modules wiring |
-| `config/medusa-plugin-versions.json` | npm version map for all plugins |
-| `config/homepage-config.json` | Dynamic-config schema (sync with storefront build) |
+| `plugins.config.json` | Medusa core + plugin npm versions; optional `enabled` array |
+| `backend.config.json` | Preset (`full`/`minimal`), default region |
 | `.env` | Database, CORS, secrets, integrations |
-| `src/scripts/seed.ts` | Region, sales channel, publishable API key, sample product |
 
 ## Commands
 
 ```bash
 cd backend
-npm run dev      # medusa develop
-npm run build    # medusa build
-npm run seed     # medusa exec ./src/scripts/seed.ts
+npm run dev              # backend-build → medusa develop
+npm run build            # backend-build → medusa build
+npm run seed             # seed region, API key, sample product
+npm run backend:build    # regenerate .generated-backend/ only
 ```
 
+**Do not edit** `.generated-backend/` — overwritten every build.
+
 ## Docker
 
-From project root: `make up-infra` then local `npm run dev`, or `make up` for full containerized stack. See `Makefile`.
+From project root: `make up-infra` then local `npm run dev:backend`, or `make up` for full stack. See `Makefile`.
 
 ## After seed
 
-1. Open Medusa Admin → Settings → Publishable API Keys
-2. Copy token into `storefront/.env.local` as `NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY`
+From project root, `npm run seed` or `make seed` syncs the publishable key into `storefront/.env.local` (via `scripts/sync-publishable-key.mjs`).
 
-## Plugin versions
+## Plugins
 
-Edit `config/medusa-plugin-versions.json`, then update `package.json` dependencies to match and run `npm install`.
+Edit `plugins.config.json` — add/remove plugin keys or change versions, then run `npm run dev` or `backend:build`.
 
-## CORS
-
-`STORE_CORS` and `AUTH_CORS` must include the storefront URL (`STOREFRONT_URL`).
+`medusa-config.ts` is generated from the enabled plugin list.
 
 ## Dynamic config
 
-Homepage fields in Admin come from `config/homepage-config.json` (registered in `medusa-config.ts`).
-
-After editing the schema, run:
-
-```bash
-npm run dynamic-config:defaults
-```
+Homepage admin fields sync from `storefront/pages.config.json` on `storefront:build` into `.generated-backend/config/homepage-config.json`.
 
-The storefront reads **runtime values** from `GET /store/dynamic-config` — it does not generate or import schema files.
+Restart backend after schema changes. Storefront reads runtime values from `GET /store/dynamic-config`.

package/templates/backend/README.md

@@ -0,0 +1,26 @@
+# Backend (config-only)
+
+Medusa source is **generated** into `.generated-backend/` — same pattern as `storefront/.generated-app/`.
+
+## Committed source
+
+| File | Edit when |
+|------|-----------|
+| `plugins.config.json` | Add/remove plugins or change npm versions |
+| `backend.config.json` | Change preset (`full`/`minimal`) or default region |
+| `.env` | Database URL, secrets, optional integrations |
+
+## Commands
+
+```bash
+npm run dev          # backend-build → medusa develop
+npm run build        # backend-build → medusa build
+npm run seed         # seed demo data
+npm run backend:build   # regenerate .generated-backend/ only
+```
+
+**Do not edit** `.generated-backend/` — changes are overwritten on the next build.
+
+## Homepage admin schema
+
+Synced from storefront segments — see `storefront/pages.config.json` and run `npm run storefront:build` in the storefront folder.

package/templates/backend/config/README.md

@@ -1,21 +1,29 @@
-# Dynamic config (backend)
+# Backend config (committed)
+
+This folder is **config-only**. Medusa source is generated into `.generated-backend/` on `npm run dev` or `npm run build` — do not commit that folder.
+
+## Source files
 
 | File | Purpose |
 |------|---------|
-| `homepage-config.json` | **Schema** — field definitions for Medusa Admin (`medusa-plugin-dynamic-config`) |
-| `homepage-config.defaults.json` | **Default values** extracted from schema `defaultValue` fields (reference + bootstrap) |
+| `plugins.config.json` | Medusa core + plugin npm versions; optional `enabled` array to override preset |
+| `backend.config.json` | Preset (`full` \| `minimal`), default region, project name |
+| `.env` / `.env.template` | Secrets and service URLs (DATABASE_URL, CORS, optional integrations) |
+
+## Generated (gitignored)
+
+Running `npm run backend:build` (or `dev` / `build`) writes:
 
-## Workflow
+- `.generated-backend/medusa-config.ts` — assembled from `plugins.config.json`
+- `.generated-backend/package.json` — Medusa dependencies
+- `.generated-backend/src/`, `scripts/`, `config/`
 
-1. Edit `homepage-config.json` when adding/removing admin fields.
-2. Run `npm run dynamic-config:defaults` to refresh default values.
-3. Restart backend — schema is loaded from `medusa-config.ts`.
-4. Set live content in **Medusa Admin** (Dynamic Config).
+## Dynamic homepage schema
 
-The **storefront does not copy this schema**. It reads runtime values from:
+Homepage admin fields are **not** edited here manually. They sync from the storefront:
 
-```
-GET /store/dynamic-config
-```
+1. Edit `storefront/pages.config.json` (segments/workflows).
+2. Run `npm run storefront:build` in `storefront/` — writes filtered schema to `backend/.generated-backend/config/homepage-config.json`.
+3. Run `npm run backend:build` or `dev:backend` — preserves synced schema when regenerating.
 
-Configure values in Admin after `npm run seed`.
+Restart the backend after schema changes.

package/templates/backend/gitignore

@@ -1,4 +1,5 @@
 node_modules
+.generated-backend
 .medusa
 .cache
 static

package/templates/backend/src/scripts/seed.ts

@@ -206,7 +206,5 @@ export default async function seedStore({ container }: ExecArgs) {
   logger.info("=== Seed complete ===")
   logger.info(`Region: ${SEED_REGION_NAME} (${SEED_COUNTRIES.join(", ")})`)
   logger.info(`Publishable API key id: ${publishableKey.id}`)
-  logger.info("Copy the publishable key token from Medusa Admin → Settings → Publishable API Keys")
-  logger.info("into storefront/.env.local as NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY")
   logger.info(`Sample product: ${products[0]?.handle}`)
 }

package/templates/docker/Makefile

@@ -72,8 +72,10 @@ health: ## Check backend and storefront HTTP health
 admin-create: ## Create admin user (ADMIN_EMAIL / ADMIN_PASSWORD)
 	$(COMPOSE) exec backend npx medusa user -e $(ADMIN_EMAIL) -p '$(ADMIN_PASSWORD)'
 
-seed: ## Run Medusa seed script (regions, publishable key, sample product)
+seed: ## Run Medusa seed, then sync publishable key to storefront env
 	$(COMPOSE) exec backend npx medusa exec ./src/scripts/seed.ts
+	@token=$$($(COMPOSE) exec -T postgres psql -U {{POSTGRES_USER}} -d {{POSTGRES_DB}} -tAc "SELECT token FROM api_key WHERE type = 'publishable' AND deleted_at IS NULL AND revoked_at IS NULL ORDER BY created_at DESC LIMIT 1" | tr -d '[:space:]'); \
+	node scripts/sync-publishable-key.mjs "$$token"
 
 db-shell: ## Open psql in postgres container
 	$(COMPOSE) exec postgres psql -U {{POSTGRES_USER}} -d {{POSTGRES_DB}}

package/templates/docker/backend/Dockerfile

@@ -2,10 +2,14 @@ FROM node:24-alpine AS builder
 
 WORKDIR /app
 
-COPY package.json package-lock.json* ./
+COPY package.json .npmrc plugins.config.json backend.config.json ./
 RUN npm install --prefer-offline --no-audit --legacy-peer-deps
 
-COPY . .
+RUN npm run backend:build
+
+WORKDIR /app/.generated-backend
+
+RUN npm install --prefer-offline --no-audit --legacy-peer-deps
 RUN npm run build
 
 RUN if [ -d templates ]; then cp -r templates .medusa/server/; fi
@@ -16,11 +20,12 @@ WORKDIR /app
 
 ENV NODE_ENV=production
 
-COPY --from=builder /app/.medusa/server ./
-COPY --from=builder /app/medusa-config.ts ./medusa-config.ts
-COPY --from=builder /app/config ./config
-COPY --from=builder /app/package.json ./package.json
-COPY --from=builder /app/package-lock.json* ./
+COPY --from=builder /app/.generated-backend/.medusa/server ./
+COPY --from=builder /app/.generated-backend/medusa-config.ts ./medusa-config.ts
+COPY --from=builder /app/.generated-backend/config ./config
+COPY --from=builder /app/.generated-backend/src ./src
+COPY --from=builder /app/.generated-backend/package.json ./package.json
+COPY --from=builder /app/.generated-backend/package-lock.json* ./
 
 RUN npm install --omit=dev --prefer-offline --no-audit --legacy-peer-deps \
   && npm install --save-prod ts-node typescript --prefer-offline --no-audit --legacy-peer-deps

package/templates/root/.cursor/commands/docker-dev.md

@@ -19,14 +19,9 @@ npm run dev:storefront   # terminal 2
 
 ## After seed
 
-Copy publishable API key into:
+`make seed` runs Medusa seed unchanged, then `scripts/sync-publishable-key.mjs` reads the token from Postgres and updates:
 
-- `storefront/.env.local` (local dev)
-- `docker/frontend.build.defaults` + rebuild storefront image (Docker)
-
-```bash
-make build-storefront
-make up-storefront
-```
+- `storefront/.env.local`
+- `docker/.env` and `docker/frontend.build.defaults` (when using Docker)
 
 Mailpit: http://localhost:8025

package/templates/root/.cursor/rules/monorepo-layout.mdc

@@ -7,15 +7,17 @@ alwaysApply: true
 
 ```
 <project>/
-  backend/      Medusa v2 API + Admin
-  storefront/   Segment-based Next.js (config client)
+  backend/      Config-only Medusa client → .generated-backend/
+  storefront/   Config-only Next.js client → .generated-app/
 ```
 
+Both folders are **config clients**. Generated code is gitignored.
+
 ## Dev (local Node)
 
 ```bash
-npm run dev:backend      # terminal 1
-npm run dev:storefront   # terminal 2
+npm run dev:backend      # terminal 1 — backend-build + medusa develop
+npm run dev:storefront   # terminal 2 — storefront-build + next dev
 ```
 
 ## Dev (Docker)
@@ -31,9 +33,9 @@ See `Makefile` and command `docker-dev`.
 ## First-time backend
 
 1. Set `DATABASE_URL` in `backend/.env`
-2. `npm run dev:backend` (migrations)
+2. `npm run dev:backend` (generates backend + migrations)
 3. `npm run seed` (region, API key, sample product)
-4. Copy publishable key → `storefront/.env.local`
+4. Run `npm run seed` from project root (syncs publishable key to `storefront/.env.local` via Postgres)
 
 ## Build
 
@@ -42,14 +44,16 @@ npm run build:backend
 npm run build:storefront
 ```
 
-## Where to edit
+## Where to edit (committed source only)
 
 | Goal | Path |
 |------|------|
-| Medusa plugins / modules | `backend/medusa-config.ts` |
-| Plugin npm versions | `backend/config/medusa-plugin-versions.json` |
-| Homepage admin fields | `backend/config/homepage-config.json` (+ `npm run dynamic-config:defaults` in backend) |
+| Medusa plugins + versions | `backend/plugins.config.json` |
+| Backend preset / region | `backend/backend.config.json` |
+| Homepage admin fields | driven by `storefront/pages.config.json` → synced on `storefront:build` |
 | Storefront sections | `storefront/pages.config.json` |
 | Brand colors | `storefront/theme-overrides.css` |
 
+**Never edit** `backend/.generated-backend/` or `storefront/.generated-app/` — regenerated every dev/build.
+
 Cursor guides live in `backend/.cursor/` and `storefront/.cursor/`.

package/templates/root/scripts/sync-publishable-key.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * Sync NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY into storefront/.env.local and docker env files.
+ * Does not modify Medusa backend — reads the token from Postgres after seed.
+ *
+ * Usage:
+ *   node scripts/sync-publishable-key.mjs --from-db
+ *   node scripts/sync-publishable-key.mjs pk_abc123...
+ *   echo pk_abc... | node scripts/sync-publishable-key.mjs --stdin
+ */
+import { execSync } from "child_process"
+import { existsSync, readFileSync, writeFileSync } from "fs"
+import { dirname, join } from "path"
+import { fileURLToPath } from "url"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const projectRoot = join(__dirname, "..")
+const ENV_KEY = "NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY"
+
+const SQL = `SELECT token FROM api_key WHERE type = 'publishable' AND deleted_at IS NULL AND revoked_at IS NULL ORDER BY created_at DESC LIMIT 1`
+
+function upsertEnvLine(content, key, value) {
+  const line = `${key}=${value}`
+  const regex = new RegExp(`^${key}=.*$`, "m")
+  if (regex.test(content)) return content.replace(regex, line)
+  return `${content.replace(/\n?$/, "")}\n${line}\n`
+}
+
+function updateEnvFile(filePath, token) {
+  if (!existsSync(filePath)) return false
+  writeFileSync(filePath, upsertEnvLine(readFileSync(filePath, "utf8"), ENV_KEY, token))
+  return true
+}
+
+function parseEnvFile(path) {
+  if (!existsSync(path)) return {}
+  const vars = {}
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    const m = line.match(/^([A-Z0-9_]+)=(.*)$/)
+    if (m) vars[m[1]] = m[2]
+  }
+  return vars
+}
+
+function readDatabaseUrl() {
+  const backendEnv = join(projectRoot, "backend", ".env")
+  const vars = parseEnvFile(backendEnv)
+  return vars.DATABASE_URL || process.env.DATABASE_URL || null
+}
+
+function queryTokenViaPsql(databaseUrl) {
+  const out = execSync(`psql "${databaseUrl}" -tAc "${SQL}"`, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+  return out.trim()
+}
+
+function isValidToken(token) {
+  return typeof token === "string" && token.startsWith("pk_") && !token.includes("...")
+}
+
+function resolveToken() {
+  const args = process.argv.slice(2)
+
+  if (args.includes("--stdin")) {
+    const fromStdin = readFileSync(0, "utf8").trim()
+    if (isValidToken(fromStdin)) return fromStdin
+  }
+
+  const positional = args.filter((a) => !a.startsWith("--"))
+  if (positional[0] && isValidToken(positional[0])) return positional[0]
+
+  if (args.includes("--from-db") || args.length === 0) {
+    const databaseUrl = readDatabaseUrl()
+    if (!databaseUrl) {
+      throw new Error("DATABASE_URL not found in backend/.env")
+    }
+    const token = queryTokenViaPsql(databaseUrl)
+    if (isValidToken(token)) return token
+    throw new Error("No publishable API key in database — run seed first")
+  }
+
+  throw new Error("Pass pk_ token, --stdin, or --from-db")
+}
+
+try {
+  const token = resolveToken()
+  const targets = [
+    join(projectRoot, "storefront", ".env.local"),
+    join(projectRoot, "docker", ".env"),
+    join(projectRoot, "docker", "frontend.build.defaults"),
+  ]
+  const updated = targets.filter((p) => updateEnvFile(p, token))
+
+  if (updated.length === 0) {
+    console.error("sync-publishable-key: no env files updated (storefront/.env.local missing?)")
+    process.exit(1)
+  }
+
+  console.log("sync-publishable-key: set NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY in:")
+  for (const p of updated) {
+    console.log(`  ${p.replace(`${projectRoot}/`, "")}`)
+  }
+} catch (error) {
+  console.error(`sync-publishable-key: ${error.message}`)
+  process.exit(1)
+}

package/templates/shared/.cursor/rules/customize-sections.mdc

@@ -20,7 +20,13 @@ Each entry in `segments` renders top-to-bottom:
 ]
 ```
 
-**Reorder** — change array order, then `npm run storefront:build`.
+**Reorder / add / remove sections** — edit `pages.config.json`, then:
+
+```bash
+npm run storefront:build
+```
+
+This regenerates the Next.js app **and** syncs `backend/config/homepage-config.json` (Admin fields for your active segments). Restart the backend after schema changes.
 
 **Remove** — delete the line and remove the package from `package.json` if unused elsewhere.
 

package/templates/shared/.cursor/rules/storefront-architecture.mdc

@@ -24,7 +24,7 @@ This folder (`storefront/`) is a **config client**, not a hand-written Next.js a
 |------|---------|
 | `.generated-app/` | Full Next.js app from `storefront-build` |
 
-Homepage content (hero, promo, logo, etc.) is **not** generated here — it comes from Medusa `GET /store/dynamic-config`. Schema lives in `../backend/config/homepage-config.json`.
+Homepage content (hero, promo, logo, etc.) comes from Medusa `GET /store/dynamic-config`. The **schema** in `../backend/.generated-backend/config/homepage-config.json` is updated automatically when you run `npm run storefront:build` after changing `pages.config.json`.
 
 After any change to config, deps, or `theme-overrides.css`:
 

package/templates/shared/README.md

@@ -30,7 +30,7 @@ make admin-create
 | API        | {{BACKEND_URL}} |
 | Mailpit    | http://localhost:8025 |
 
-After `make seed`, update `docker/frontend.build.defaults` and `storefront/.env.local` with the publishable key, then `make build-storefront` if using Docker for the storefront.
+After `make seed` or `npm run seed`, the publishable key is read from Postgres and written to `storefront/.env.local` and `docker/` env files (no backend code changes).
 
 Default admin: `make admin-create` (see `Makefile` for `ADMIN_EMAIL` / `ADMIN_PASSWORD`).
 
@@ -93,8 +93,9 @@ make clean         # remove containers + volumes
 |------|--------|
 | Home sections | `storefront/pages.config.json` |
 | Colors / fonts | `storefront/theme-overrides.css` |
-| Medusa plugins | `backend/medusa-config.ts` + `backend/config/medusa-plugin-versions.json` |
-| Homepage admin fields | `backend/config/homepage-config.json` |
+| Medusa plugins | `backend/plugins.config.json` |
+| Plugin preset / region | `backend/backend.config.json` |
+| Homepage admin fields | auto-synced to `backend/.generated-backend/config/` on `storefront:build` |
 | Docker secrets | `docker/.env` |
 
 Cursor guides: `.cursor/` in each folder.

package/templates/shared/root-gitignore

@@ -4,3 +4,5 @@ node_modules
 .env
 .env.local
 docker/.env
+backend/.generated-backend
+storefront/.generated-app