@pradip1995/create-storefront-app 0.2.3 → 0.3.1

package/templates/docker/storefront/.dockerignore

@@ -0,0 +1,9 @@
+node_modules
+.generated-app
+.next
+.git
+.env
+.env.*
+npm-debug.log*
+Dockerfile
+.dockerignore

package/templates/docker/storefront/Dockerfile

@@ -0,0 +1,53 @@
+# syntax=docker/dockerfile:1
+
+# Use slim (glibc) — Alpine musl sharp corrupts AVIF product images.
+FROM node:24-slim AS builder
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libvips42 \
+    libheif1 \
+  && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY package.json .npmrc ./
+RUN npm install --prefer-offline --no-audit --legacy-peer-deps \
+  && npm rebuild sharp
+
+COPY pages.config.json storefront.config.json theme-overrides.css ./
+COPY public ./public/
+
+RUN npm run storefront:build
+
+WORKDIR /app/.generated-app
+
+RUN npm install --prefer-offline --no-audit --legacy-peer-deps \
+  && npm rebuild sharp
+
+RUN --mount=type=secret,id=frontend_defaults \
+    --mount=type=secret,id=app_env \
+    sh -c 'cat /run/secrets/frontend_defaults /run/secrets/app_env > .env.production' \
+    && npm run build \
+    && npm prune --omit=dev
+
+FROM node:24-slim AS runner
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libvips42 \
+    libheif1 \
+  && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV PORT=8000
+
+COPY --from=builder /app/.generated-app/package.json ./package.json
+COPY --from=builder /app/.generated-app/.next ./.next
+COPY --from=builder /app/.generated-app/public ./public
+COPY --from=builder /app/.generated-app/next.config.js ./next.config.js
+COPY --from=builder /app/.generated-app/node_modules ./node_modules
+
+EXPOSE 8000
+
+CMD ["npm", "run", "start"]

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

@@ -0,0 +1,27 @@
+# Docker dev
+
+## Full stack in Docker
+
+```bash
+make up
+make migrate
+make seed
+make admin-create
+```
+
+## Infra only + local Node
+
+```bash
+make up-infra
+npm run dev:backend      # terminal 1
+npm run dev:storefront   # terminal 2
+```
+
+## After seed
+
+`make seed` runs Medusa seed unchanged, then `scripts/sync-publishable-key.mjs` reads the token from Postgres and updates:
+
+- `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

@@ -0,0 +1,55 @@
+---
+description: Monorepo layout — backend + storefront dev workflow
+alwaysApply: true
+---
+
+# Project layout
+
+```
+<project>/
+  backend/      Medusa v2 API + Admin
+  storefront/   Segment-based Next.js (config client)
+```
+
+## Dev (local Node)
+
+```bash
+npm run dev:backend      # terminal 1
+npm run dev:storefront   # terminal 2
+```
+
+## Dev (Docker)
+
+```bash
+make up              # full stack in containers
+make up-infra        # postgres + redis + mailpit only, then npm run dev:* locally
+make migrate && make seed && make admin-create
+```
+
+See `Makefile` and command `docker-dev`.
+
+## First-time backend
+
+1. Set `DATABASE_URL` in `backend/.env`
+2. `npm run dev: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)
+
+## Build
+
+```bash
+npm run build:backend
+npm run build:storefront
+```
+
+## Where to edit
+
+| 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) |
+| Storefront sections | `storefront/pages.config.json` |
+| Brand colors | `storefront/theme-overrides.css` |
+
+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/commands/change-theme-colors.md

@@ -21,7 +21,7 @@
 
 ## Hero & section content
 
-Configure in **Medusa Admin** dynamic-config (`homepage-config`), not in this repo. Schema: `dynamic-config.generated.json`.
+Configure in **Medusa Admin** dynamic-config (`homepage-config`). Schema: `backend/config/homepage-config.json`.
 
 ## Switch full theme preset (advanced)
 

package/templates/shared/.cursor/commands/fix-segment-issue.md

@@ -40,8 +40,8 @@ Symptoms: hero is plain text, nav not transparent, sections unstyled.
 ## 5. Empty segment but API works
 
 - Segment may need workflow data (e.g. new-arrivals needs products with tags)
-- Check Medusa dynamic-config for that section's fields
-- Compare with working `dynamic-config.defaults.json` in project root
+- Check Medusa Admin dynamic-config for that section's fields
+- Confirm `NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY` is set and backend `/store/dynamic-config` returns data
 
 ## 6. Package version mismatch
 

package/templates/shared/.cursor/commands/rebuild-storefront.md

@@ -16,4 +16,4 @@ npm run start
 
 **Do not** edit files inside `.generated-app/` — they are overwritten every build.
 
-Verify build output includes your segments and `dynamic-config: wrote dynamic-config.generated.json`.
+Verify build output lists your segments. Homepage content is loaded from Medusa Admin via `/store/dynamic-config`, not generated in the storefront build.

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/customize-theme.mdc

@@ -54,4 +54,4 @@ NEXT_PUBLIC_HOME_PAGE_DESCRIPTION=Subtext
 
 ## Medusa admin content
 
-Hero banners, promo text, testimonials, features → Medusa **dynamic-config** (`homepage-config`). Import `dynamic-config.generated.json` into your backend plugin.
+Hero banners, promo text, testimonials, features → Medusa **dynamic-config** (`homepage-config`). Edit schema in `backend/config/homepage-config.json`; storefront loads values from `GET /store/dynamic-config`.

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

@@ -5,7 +5,7 @@ alwaysApply: true
 
 # Storefront architecture
 
-This project is a **config client**, not a hand-written Next.js app.
+This folder (`storefront/`) is a **config client**, not a hand-written Next.js app. The Medusa backend lives in `../backend/`.
 
 ## You edit (client root)
 
@@ -23,7 +23,8 @@ This project is a **config client**, not a hand-written Next.js app.
 | Path | Purpose |
 |------|---------|
 | `.generated-app/` | Full Next.js app from `storefront-build` |
-| `dynamic-config.generated.json` | Medusa admin schema export |
+
+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`.
 
 After any change to config, deps, or `theme-overrides.css`:
 

package/templates/shared/.cursor/skills/fix-segment-issues/SKILL.md

@@ -48,7 +48,7 @@ Symptom: hero shows raw text, nav not styled, shop-by-category flat.
 
 - Products needed for carousels (catalog + region)
 - Dynamic-config in Medusa for hero/testimonials
-- Compare with `dynamic-config.defaults.json` in project root
+- Confirm backend is running and `/store/dynamic-config` returns expected JSON
 
 ### 6. Version drift
 

package/templates/shared/README.md

@@ -0,0 +1,100 @@
+# {{PROJECT_NAME}}
+
+Full-stack Medusa shop: **backend** (Medusa v2) + **storefront** (segment-based Next.js).
+
+Run **with Docker**, **Docker infra + local Node**, or **fully local** (PostgreSQL + Redis on host).
+
+## Prerequisites
+
+- **Node.js 20+**
+- **npm 9+**
+- **Docker Desktop** (optional — for `make up` / `make up-infra`)
+- **PostgreSQL + Redis** on host when running fully local without Docker infra
+
+All `@pradip1995/*` packages and Medusa plugins resolve from the **public npm registry** — no monorepo or private registry required.
+
+## Option A — Full stack in Docker
+
+```bash
+make env-init    # docker/.env from example (already created on scaffold)
+make up          # build + start postgres, redis, mailpit, backend, storefront
+make migrate     # DB migrations (fresh DB may need two runs)
+make seed        # region, publishable key, sample product
+make admin-create
+```
+
+| Service    | URL |
+|------------|-----|
+| Storefront | {{BASE_URL}}/{{DEFAULT_REGION}} |
+| Admin      | {{BACKEND_URL}}/app |
+| API        | {{BACKEND_URL}} |
+| Mailpit    | http://localhost:8025 |
+
+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`).
+
+## Option B — Docker infra + local Node dev
+
+```bash
+make up-infra              # postgres, redis, mailpit only
+npm run dev:backend        # terminal 1 — uses backend/.env DATABASE_URL
+npm run seed               # from project root, or cd backend && npm run seed
+npm run dev:storefront     # terminal 2
+```
+
+`backend/.env` `DATABASE_URL` matches Docker postgres credentials from scaffold.
+
+For OTP/email in local backend with infra Docker, set `SMTP_HOST=localhost` and `SMTP_PORT=1025` (Mailpit exposes SMTP when using `docker-compose.infra.yml`).
+
+## Option C — Fully local (no Docker)
+
+```bash
+cd backend && npm install
+# Edit .env — PostgreSQL + Redis on localhost
+npm run dev
+npm run seed
+
+cd ../storefront && npm install
+# Edit .env.local — publishable key from Admin
+npm run dev
+```
+
+## Daily dev (local Node)
+
+```bash
+npm run dev:backend      # terminal 1
+npm run dev:storefront   # terminal 2
+```
+
+## Build production
+
+```bash
+npm run build:backend
+npm run build:storefront
+# or
+make build
+```
+
+## Docker commands
+
+```bash
+make help          # all targets
+make up-infra      # postgres + redis + mailpit
+make up-backend    # infra + backend container
+make logs          # tail logs
+make db-shell      # psql
+make clean         # remove containers + volumes
+```
+
+## Customize
+
+| Goal | Where |
+|------|--------|
+| 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`) |
+| Docker secrets | `docker/.env` |
+
+Cursor guides: `.cursor/` in each folder.

package/templates/shared/root-gitignore

@@ -0,0 +1,6 @@
+node_modules
+.DS_Store
+*.log
+.env
+.env.local
+docker/.env

package/templates/shared/storefront-only-README.md

@@ -0,0 +1,25 @@
+# {{PROJECT_NAME}}
+
+Segment-based Medusa storefront (config client).
+
+## Setup
+
+```bash
+npm install
+# Edit .env.local — Medusa URL + publishable key
+npm run dev
+```
+
+Storefront: {{BASE_URL}}/{{DEFAULT_REGION}}
+
+## Customize
+
+| Goal | File |
+|------|------|
+| Home sections | `pages.config.json` |
+| Colors / fonts | `theme-overrides.css` |
+| Brand assets | `public/` |
+
+After config changes: `npm run storefront:build && npm run dev`
+
+Cursor guides: `.cursor/`