@pradip1995/create-storefront-app 0.2.3 → 0.3.0

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,32 @@
+# 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
+
+Copy publishable API key into:
+
+- `storefront/.env.local` (local dev)
+- `docker/frontend.build.defaults` + rebuild storefront image (Docker)
+
+```bash
+make build-storefront
+make up-storefront
+```
+
+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. Copy publishable key → `storefront/.env.local`
+
+## 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/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-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.) is **not** generated here — it comes from Medusa `GET /store/dynamic-config`. Schema lives in `../backend/config/homepage-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`, update `docker/frontend.build.defaults` and `storefront/.env.local` with the publishable key, then `make build-storefront` if using Docker for the storefront.
+
+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` |
+| 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/`