@pradip1995/create-storefront-app 0.3.1 → 0.4.0

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.6"
+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.1",
+  "version": "0.4.0",
   "description": "Scaffold a segment-based Medusa storefront using @pradip1995/framework packages",
   "license": "MIT",
   "type": "module",

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

@@ -1,54 +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 — **synced from storefront build** when sections change |
+| `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
 
-From project root, `npm run seed` or `make seed` syncs the publishable key into `storefront/.env.local` (via `scripts/sync-publishable-key.mjs`, reads from Postgres — no backend code changes).
+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,23 +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** for Medusa Admin — **auto-synced** from storefront build |
-| `homepage-config.defaults.json` | Default values from schema `defaultValue` fields (auto-synced) |
+| `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)
 
-## Workflow
+Running `npm run backend:build` (or `dev` / `build`) writes:
 
-1. Edit **`storefront/pages.config.json`** (add/remove/reorder segments).
-2. Run **`npm run storefront:build`** in `storefront/` (or `npm run dev:storefront`).
-3. `storefront-build` writes filtered schema here based on segments + workflows in use.
-4. Restart Medusa backend so Admin picks up schema changes.
+- `.generated-backend/medusa-config.ts` — assembled from `plugins.config.json`
+- `.generated-backend/package.json` — Medusa dependencies
+- `.generated-backend/src/`, `scripts/`, `config/`
 
-Optional manual refresh of defaults only:
+## Dynamic homepage schema
 
-```bash
-cd backend && npm run dynamic-config:defaults
-```
+Homepage admin fields are **not** edited here manually. They sync from the storefront:
 
-Runtime content is edited in **Medusa Admin** (Dynamic Config). The storefront loads values via `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.
 
-Override entire schema: add `storefront/dynamic-config.schema.json` (see framework docs).
+Restart the backend after schema changes.

package/templates/backend/gitignore

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

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/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,7 +33,7 @@ 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. Run `npm run seed` from project root (syncs publishable key to `storefront/.env.local` via Postgres)
 
@@ -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/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.) comes from Medusa `GET /store/dynamic-config`. The **schema** in `../backend/config/homepage-config.json` is updated automatically when you run `npm run storefront:build` after changing `pages.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

@@ -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` (auto-synced on `storefront:build`) |
+| 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