@pradip1995/create-storefront-app 0.2.2 → 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

@@ -0,0 +1,28 @@
+# Change theme, colors & fonts
+
+## Quick brand (no CSS)
+
+1. Edit `.env.local`:
+   - `NEXT_PUBLIC_SHOP_NAME`
+   - `NEXT_PUBLIC_HOME_PAGE_TITLE`
+   - `NEXT_PUBLIC_HOME_PAGE_DESCRIPTION`
+2. Add `public/logo.png` for nav/footer logo.
+3. `npm run storefront:build && npm run dev`
+
+## Colors & fonts (CSS variables)
+
+1. Open or create **`theme-overrides.css`** in the project root.
+2. Override `:root` variables (see `.cursor/rules/customize-theme.mdc`):
+   - Brand: `--color-brand-accent`, `--color-brand-accent-hover`, `--color-brand-pink`
+   - Text: `--color-text-heading`, `--color-text-body`, `--color-text-muted`
+   - Surfaces: `--color-page-bg`, `--color-footer-bg`, `--color-surface-muted`
+   - Fonts: `--font-sans`, `--font-heading`, `--font-display`
+3. Rebuild: `npm run storefront:build && npm run dev`
+
+## Hero & section content
+
+Configure in **Medusa Admin** dynamic-config (`homepage-config`). Schema: `backend/config/homepage-config.json`.
+
+## Switch full theme preset (advanced)
+
+Default build uses `impulse.css`. Switching to `valero.css` alone breaks hero/nav styling unless you fork `@pradip1995/segment-tokens`. Prefer `theme-overrides.css` for rebrand.

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

@@ -0,0 +1,56 @@
+# Fix segment / UI issues
+
+Work through this checklist before changing segment source code.
+
+## 1. Rebuild
+
+```bash
+npm run storefront:build
+npm run dev
+```
+
+Never debug stale `.generated-app/` from an old build.
+
+## 2. Medusa connection
+
+In `.env.local`:
+
+- `NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY` must be a real `pk_...` key (not placeholder)
+- `MEDUSA_BACKEND_URL` / `NEXT_PUBLIC_MEDUSA_BACKEND_URL` reachable
+- `NEXT_PUBLIC_DEFAULT_REGION` matches a region in Medusa (e.g. `in`)
+
+Symptoms of bad key: empty categories, "No new arrivals", generic "Store" fallback text, API 400 in terminal.
+
+## 3. Missing CSS / broken hero layout
+
+Symptoms: hero is plain text, nav not transparent, sections unstyled.
+
+- Confirm `.generated-app/app/layout.tsx` imports `themes/impulse.css`
+- Add/fix `theme-overrides.css` only for colors — not layout
+- Align package versions: `@pradip1995/framework-compiler@^0.2.2`, `@pradip1995/segment-tokens@^0.2.1`
+
+## 4. Missing images (404)
+
+| Path | Fix |
+|------|-----|
+| `/theme-defaults/valero/logo.svg` | Add under `public/theme-defaults/valero/` |
+| Hero images | Set in Medusa dynamic-config or env fallbacks |
+| Product images | Medusa catalog / CDN allowlist in backend |
+
+## 5. Empty segment but API works
+
+- Segment may need workflow data (e.g. new-arrivals needs products with tags)
+- 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
+
+```bash
+npm ls @pradip1995/framework-compiler @pradip1995/segment-tokens
+```
+
+Bump to latest patch, reinstall, rebuild.
+
+## 7. Still broken
+
+Inspect browser Network tab for 404/400. Check terminal Medusa SDK logs. Open issue on the specific `@pradip1995/segment-*` or `workflow-*` package — do not fork segment code into this client repo.

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

@@ -0,0 +1,19 @@
+# Rebuild storefront
+
+Run after any change to `pages.config.json`, `package.json`, `.env.local`, or `theme-overrides.css`.
+
+```bash
+npm run storefront:build
+npm run dev
+```
+
+Or production:
+
+```bash
+npm run build
+npm run start
+```
+
+**Do not** edit files inside `.generated-app/` — they are overwritten every build.
+
+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/commands/update-home-sections.md

@@ -0,0 +1,50 @@
+# Update home sections
+
+## Reorder or remove
+
+Edit `pages.config.json` → route `/` → `segments` array.
+
+```json
+"segments": [
+  "@pradip1995/segment-hero",
+  "@pradip1995/segment-new-arrivals",
+  "@pradip1995/segment-features"
+]
+```
+
+Remove unused packages from `package.json`, then:
+
+```bash
+npm install
+npm run storefront:build
+npm run dev
+```
+
+## Add a segment
+
+1. Pick package from `@pradip1995/segment-*` (npm).
+2. Add to `package.json` dependencies.
+3. Append to home `segments` in `pages.config.json`.
+4. `npm install && npm run storefront:build && npm run dev`
+
+## Available home segments (full preset)
+
+- `segment-hero` — banner
+- `segment-shop-by-category` — category grid
+- `segment-new-arrivals` — product carousel
+- `segment-promotional-banners` — promo tiles
+- `segment-collections-showcase` — collection tabs
+- `segment-why-choose-us` — feature icons
+- `segment-bestsellers-carousel` — bestsellers
+- `segment-reviews-marquee` — testimonials
+- `segment-features` — trust strip
+
+## Metadata
+
+Set page title/description on the home route:
+
+```json
+"metadata": { "title": "Home", "description": "Welcome" }
+```
+
+Rebuild to apply in `.generated-app`.

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

@@ -0,0 +1,49 @@
+---
+description: Add, remove, or reorder homepage and page segments
+globs: pages.config.json,package.json
+alwaysApply: false
+---
+
+# Customize sections
+
+Sections are **npm segment packages** wired in `pages.config.json`.
+
+## Home page (`route: "/"`)
+
+Each entry in `segments` renders top-to-bottom:
+
+```json
+"segments": [
+  "@pradip1995/segment-hero",
+  "@pradip1995/segment-shop-by-category",
+  "@pradip1995/segment-new-arrivals"
+]
+```
+
+**Reorder** — change array order, then `npm run storefront:build`.
+
+**Remove** — delete the line and remove the package from `package.json` if unused elsewhere.
+
+**Add** — see command `add-home-segment` or skill `update-storefront-sections`.
+
+## Other routes
+
+| Route | Typical segments |
+|-------|------------------|
+| `/store` | mobile-filters, refinement-list, product-grid |
+| `/products/[handle]` | product-gallery, product-info, product-actions, related-products |
+| `/cart` | cart-item, cart-summary |
+| `/checkout` | checkout-form, checkout-summary |
+
+## After changing segments
+
+1. Add dep to `package.json`: `"@pradip1995/segment-foo": "^0.2.2"`
+2. Run `npm install`
+3. Update `pages.config.json`
+4. Run `npm run storefront:build`
+
+Build log lists segment count — verify your new segment appears.
+
+## Segment data
+
+Each segment receives props from its route **workflow** (e.g. `workflow-home` loads hero, categories, products). If a segment renders empty, the workflow may not supply its data key — check Medusa backend + publishable key first.

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

@@ -0,0 +1,57 @@
+---
+description: Change storefront colors, fonts, and theme CSS
+globs: theme-overrides.css,public/**/*
+alwaysApply: false
+---
+
+# Customize theme, colors & fonts
+
+## Default stylesheet
+
+Build imports `@pradip1995/segment-tokens/themes/impulse.css` (full segment UI: hero, nav, footer, carousels).
+
+Alternate token presets (advanced — requires forking compiler import or publishing custom tokens):
+
+- `themes/impulse.css` — burgundy/cream, Playfair + Montserrat (default)
+- `themes/valero.css` — blue monochrome; **missing** many component class rules — not recommended alone
+
+## Brand colors & fonts (recommended)
+
+Edit **`theme-overrides.css`** in the project root. Rebuild after changes.
+
+```css
+:root {
+  --color-brand-accent: #5a2a43;
+  --color-brand-accent-hover: #723a56;
+  --color-brand-pink: #c68a8a;
+  --color-page-bg: #ffffff;
+  --color-footer-bg: #1a1a1a;
+  --color-text-heading: #1a1a1a;
+  --color-text-body: #4d4d4d;
+  --font-sans: "Montserrat", sans-serif;
+  --font-heading: "Playfair Display", serif;
+  --font-display: "Playfair Display", serif;
+}
+```
+
+Common variables: `--color-brand-*`, `--color-text-*`, `--color-surface-*`, `--color-promo-*`, `--font-sans`, `--font-heading`, `--header-height`, `--container-max`.
+
+## Logo & hero images
+
+| Asset | Location |
+|-------|----------|
+| Logo | `public/logo.png` or Medusa dynamic-config logo field |
+| Hero fallback | `public/theme-defaults/valero/hero-desktop.svg` (override same path) |
+| Favicon | `public/favicon.ico` |
+
+Env copy for hero when Medusa config is empty:
+
+```bash
+NEXT_PUBLIC_SHOP_NAME=My Shop
+NEXT_PUBLIC_HOME_PAGE_TITLE=Headline
+NEXT_PUBLIC_HOME_PAGE_DESCRIPTION=Subtext
+```
+
+## Medusa admin content
+
+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

@@ -0,0 +1,41 @@
+---
+description: Config-only Medusa storefront — structure, build flow, what not to edit
+alwaysApply: true
+---
+
+# Storefront architecture
+
+This folder (`storefront/`) is a **config client**, not a hand-written Next.js app. The Medusa backend lives in `../backend/`.
+
+## You edit (client root)
+
+| File | Purpose |
+|------|---------|
+| `pages.config.json` | Routes, workflows, layouts, home/product segments |
+| `storefront.config.json` | Region, loader |
+| `package.json` | npm deps on `@pradip1995/*` segments/workflows |
+| `.env.local` | Medusa URL, publishable key, shop name, hero copy |
+| `public/` | Logo, favicon, brand static files |
+| `theme-overrides.css` | Brand colors & fonts (CSS variables) |
+
+## Generated (do not hand-edit)
+
+| Path | Purpose |
+|------|---------|
+| `.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`.
+
+After any change to config, deps, or `theme-overrides.css`:
+
+```bash
+npm run storefront:build
+npm run dev
+```
+
+## Rules
+
+- Never commit secrets from `.env.local`
+- Never edit `.generated-app/` — changes are overwritten on rebuild
+- Segment logic lives in npm packages; fix bugs there + publish, not copy-paste into this repo
+- URL pattern: `http://localhost:8000/<NEXT_PUBLIC_DEFAULT_REGION>/...`

package/templates/shared/.cursor/skills/customize-storefront-theme/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: customize-storefront-theme
+description: Change storefront colors, fonts, logo, and hero branding in a config-only @pradip1995 create-storefront-app project. Use when the user asks to rebrand, change theme, update colors, fonts, logo, or hero styling.
+---
+
+# Customize storefront theme
+
+## When to use
+
+User wants to change look-and-feel of a scaffolded storefront (not the medusa-storefront-kit theme package).
+
+## Workflow
+
+1. Read `.cursor/rules/customize-theme.mdc` and `theme-overrides.css` if present.
+2. **Content/branding text** → `.env.local`:
+   - `NEXT_PUBLIC_SHOP_NAME`
+   - `NEXT_PUBLIC_HOME_PAGE_TITLE`
+   - `NEXT_PUBLIC_HOME_PAGE_DESCRIPTION`
+3. **Logo** → `public/logo.png` or Medusa dynamic-config logo.
+4. **Colors & fonts** → edit `theme-overrides.css` at project root:
+
+```css
+:root {
+  --color-brand-accent: #YOUR_BRAND;
+  --color-brand-accent-hover: #YOUR_BRAND_DARK;
+  --color-text-heading: #1a1a1a;
+  --font-sans: "Your Font", sans-serif;
+  --font-heading: "Your Display Font", serif;
+}
+```
+
+5. Always run after CSS/env changes:
+
+```bash
+npm run storefront:build
+npm run dev
+```
+
+## Do not
+
+- Edit `.generated-app/` directly
+- Switch to `valero.css` alone (breaks hero/nav component CSS)
+- Put secrets in committed files
+
+## Medusa content
+
+Hero images and promo copy often come from Medusa **dynamic-config** (`homepage-config`), not from this repo. Point user to Medusa Admin if content is wrong but styling is fine.

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

@@ -0,0 +1,68 @@
+---
+name: fix-segment-issues
+description: Diagnose and fix broken storefront segments, missing CSS, empty sections, 404 assets, or Medusa API errors in a create-storefront-app project. Use when hero looks wrong, sections unstyled, or data not loading.
+---
+
+# Fix segment issues
+
+## When to use
+
+User reports: broken hero, no CSS, empty sections, 404 images, or storefront not matching demo-store.
+
+## Diagnosis order
+
+### 1. Stale build
+
+```bash
+npm run storefront:build
+npm run dev
+```
+
+### 2. API key / backend
+
+Check `.env.local`:
+
+- `NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY` is valid `pk_...`
+- Backend URL correct and running
+- `NEXT_PUBLIC_DEFAULT_REGION` exists in Medusa
+
+Terminal symptom: repeated `Received response with status 400`.
+
+### 3. Missing CSS
+
+Check `.generated-app/app/layout.tsx` imports:
+
+```tsx
+import "@pradip1995/segment-tokens/themes/impulse.css"
+```
+
+If it imports only `theme.css` without full impulse rules, upgrade `@pradip1995/framework-compiler` to `^0.2.2` and rebuild.
+
+Symptom: hero shows raw text, nav not styled, shop-by-category flat.
+
+### 4. Missing static assets
+
+404 on `/theme-defaults/valero/*.svg` → add files under `public/theme-defaults/valero/` or upgrade `@pradip1995/segment-assets@^0.2.1`.
+
+### 5. Empty segment with working API
+
+- Products needed for carousels (catalog + region)
+- Dynamic-config in Medusa for hero/testimonials
+- Confirm backend is running and `/store/dynamic-config` returns expected JSON
+
+### 6. Version drift
+
+Align framework + components patch versions, reinstall, rebuild:
+
+```bash
+npm install @pradip1995/framework-compiler@^0.2.2 @pradip1995/segment-tokens@^0.2.1
+npm run storefront:build
+```
+
+## Fix in packages, not client
+
+Logic bugs in `@pradip1995/segment-*` or `workflow-*` → fix upstream repo, publish npm, bump dep here.
+
+## Reference
+
+See `.cursor/commands/fix-segment-issue.md` for full checklist.

package/templates/shared/.cursor/skills/update-storefront-sections/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: update-storefront-sections
+description: Add, remove, or reorder homepage and page segments in pages.config.json for a config-only Medusa storefront. Use when changing home sections, adding segments, or updating page composition.
+---
+
+# Update storefront sections
+
+## When to use
+
+User wants to change which blocks appear on home, store, PDP, cart, etc.
+
+## Workflow
+
+1. Read `pages.config.json` for the target route.
+2. Home sections = `segments` array on `"route": "/"`.
+3. To **reorder** — rearrange array entries.
+4. To **remove** — delete entry; remove unused dep from `package.json`.
+5. To **add**:
+   - Add `"@pradip1995/segment-<name>": "^0.2.2"` to `package.json`
+   - Append package name to route's `segments`
+   - `npm install`
+6. Rebuild:
+
+```bash
+npm run storefront:build
+npm run dev
+```
+
+## Common home segments
+
+| Package | Purpose |
+|---------|---------|
+| segment-hero | Main banner |
+| segment-shop-by-category | Category cards |
+| segment-new-arrivals | New products carousel |
+| segment-promotional-banners | Promo tiles |
+| segment-collections-showcase | Collection slider |
+| segment-why-choose-us | USP icons |
+| segment-bestsellers-carousel | Bestsellers |
+| segment-reviews-marquee | Testimonials |
+| segment-features | Trust strip |
+
+## Verify
+
+- Build log shows expected segment count
+- Dev server home page renders new block
+- If empty data, check workflow + Medusa (not just config)
+
+## Do not
+
+- Copy segment source into this repo
+- Edit `.generated-app/app/**/page.tsx` manually