@forgecart/cli 2.202610280742.0 → 2.202610280926.0

package/templates/storefront-blank/README.md

@@ -0,0 +1,86 @@
+# Blank storefront
+
+A [Next.js](https://nextjs.org) (App Router) storefront for a ForgeCart
+channel with no example storefront on it: no header, no example pages, no cart
+and no checkout — one home page carrying the store's name, on everything
+ForgeCart needs for tracking and SEO, styled with the daisyUI design system.
+
+This directory is the scaffold `forgecart init --example blank` copies into
+your project. Nothing here is compiled by the ForgeCart monorepo; it ships
+as-is in the published `@forgecart/cli` package. It is the daisyUI storefront
+(`templates/storefront`) minus its example pages and components, every other
+file kept exactly as that storefront ships it — so `forgecart refresh` keeps
+the platform files current, and a storefront built from here grows on the same
+foundations as the example one.
+
+To migrate a storefront built before the locale and SEO layer, follow [`SEO-MIGRATION.md`](SEO-MIGRATION.md).
+
+## Configuration
+
+The storefront reads four environment variables (server-side only):
+
+| Variable                  | Purpose                                                        |
+| ------------------------- | -------------------------------------------------------------- |
+| `FORGECART_CHANNEL_TOKEN` | Identifies the channel; sent as the `forgecart-token` header.  |
+| `FORGECART_SHOP_API_URL`  | Base URL of the channel's shop GraphQL API (`.../shop-api`).   |
+| `FORGECART_ADMIN_SECRET`  | Channel admin secret for server-side admin operations.         |
+| `FORGECART_ADMIN_API_URL` | URL of the channel's admin GraphQL API (`.../admin-api`).      |
+
+`forgecart init` writes all four to `.env` — the only env file this project
+ever has, and git-ignored. None of the values ever reaches the browser: every
+module that constructs an SDK client starts with `import 'server-only'`, so a
+client component importing one is a **build error**.
+
+## What ships
+
+The platform plumbing, and the one page on it:
+
+| Path                                     | What it is                                                                  |
+| ---------------------------------------- | --------------------------------------------------------------------------- |
+| `src/app/layout.tsx`                     | the shell: `<html lang>`, the locale contract, the metadata floor           |
+| `src/app/page.tsx`                       | `/` — the store's name as its one heading, indexable                        |
+| `src/app/pages/[slug]/`                  | the merchant's ACF pages, served at the route the shop API mints            |
+| `src/app/sitemap.ts`, `src/app/robots.ts` | the XML sitemap and `robots.txt`                                           |
+| `src/seo/static-routes.ts`               | the route table: every non-entity route this storefront serves — `/`        |
+| `src/seo/redirects.ts`                   | rename redirects                                                            |
+| `src/components/ForgeTracker.tsx`        | page views and identity, relayed through `/__fc/track` and `/__fc/identify` |
+| `src/components/ForgeErrorBeacon.tsx`    | browser errors, posted to `/__forge_beacon`                                 |
+| `src/components/ForgecartDesigner.tsx`   | the visual editor's runtime                                                 |
+| `src/app/ping/route.ts`                  | the liveness route the platform probes                                      |
+| `src/middleware.ts`, `src/lib/locale/`   | the locale grammar: one URL prefix per offered language                     |
+| `src/lib/`                               | the SDK clients, SEO, sessions, experiments and the account rules           |
+| `src/server/`                            | the embedded NestJS backend behind `sdk.backend` — no method yet            |
+
+## The backend gate (`sdk.backend`)
+
+The storefront embeds a real NestJS backend under `src/server/` — booted as
+an application context (no HTTP server; Next.js owns HTTP) in
+`instrumentation.ts`. A service method decorated with `@BackendMethod()` and
+declared in `src/server/backend-api.ts` becomes callable from any client
+component through the typed proxy in `src/lib/backend-client.ts`. A blank
+storefront declares none: add the first one by registering its module in
+`src/server/app.module.ts`, decorating the method and declaring it in
+`backend-api.ts` — boot fails loudly if the decorator scan and the declaration
+drift.
+
+## Design system
+
+Styling is Tailwind v4 + daisyUI 5, using **semantic** classes only
+(`bg-base-100`, `btn-primary`, …). The single source of brand truth is the
+`@plugin "daisyui/theme"` block in [`src/app/globals.css`](src/app/globals.css).
+
+## Adding a page
+
+Create `src/app/<route>/page.tsx`, give it `routeMetadata(...)` from
+`src/lib/seo/metadata.ts`, and add its row to `STATIC_ROUTES` in
+`src/seo/static-routes.ts` — `{ path: '/<route>', indexable: true }`, or
+`indexable: false` for a page that must stay out of search. Link it with
+`LocaleLink` so every link stays in its own language.
+
+## Development
+
+```bash
+npm install
+npm run dev     # Turbopack dev server (what workspace pods run)
+npm run build   # production build (what deploys run; see Procfile)
+```