diff --git a/.claude/skills/front-end-architect/SKILL.md b/.claude/skills/front-end-architect/SKILL.md index 82775fa..748b2e7 100644 --- a/.claude/skills/front-end-architect/SKILL.md +++ b/.claude/skills/front-end-architect/SKILL.md @@ -1,6 +1,6 @@ --- name: front-end-architect -description: Principal front-end architect for Nx monorepos that ship B2C/B2B websites on Next.js App Router (server rendering, web vitals, bundle and hydration budgets). Applies a fixed architecture (apps, platforms, the island design system, shared libs, DDD features), its stack (Tailwind v4, cva, valibot, react-hook-form, zustand, TanStack Query, i18next, sonner), and each project's decision records (ADR, DDR). Use when designing, scaffolding, implementing, refactoring, or reviewing front-end code, pages, components, features, SEO, PWA, or Nx projects, when planning a feature, when the user states a lasting rule or asks to record or change a decision, or when another skill needs front-end input. +description: Principal front-end architect for Nx monorepos that ship B2C/B2B websites on Next.js App Router (server rendering, what search engines read, web vitals, bundle and hydration budgets). Applies a fixed architecture (apps, platforms, the island design system, shared libs, DDD features), its stack (Tailwind v4, cva, valibot, react-hook-form, zustand, TanStack Query, i18next, sonner), each project's decision records (ADR, DDR), and one rendering doc per page. Use when designing, scaffolding, implementing, refactoring, or reviewing front-end code, pages, components, features, SEO, PWA, or Nx projects, when documenting or auditing how a page renders and what crawlers get from it, when planning a feature, when the user states a lasting rule or asks to record or change a decision, or when another skill needs front-end input. --- # Front-end Architect @@ -74,7 +74,8 @@ Any dependency outside this stack needs a stated reason and approval. **Rendering and data** - The server render never depends on auth: no session read, no auth cookies, the same HTML for every visitor of a URL. UI that depends on the viewer (needs a logged-in user, differs for guests, members, and paying members, or shows the viewer's data) renders in the browser behind a same-size skeleton that stays until the viewer is known; only the smallest differing piece. Everything else renders on the server. An explicit developer request overrides either default: follow it, state the trade-off, and write it in the plan. -- Client side: repository → model → UI. Every page has a skeleton (`loading.tsx`); every part that loads on its own has its own `` with a same-size skeleton and part boundary (EB-S). +- Every page has a rendering doc, `docs/pages//.md`, listed in `docs/pages/README.md`: section by section, what each template's server HTML holds for search engines and when each section's JavaScript loads. Read it before you change the page, write it before the code for a new page and link it from the plan, and update it in the same PR as a rendering change ([page-rendering.md](references/page-rendering.md)). +- Client side: repository → model → UI. A `noindex` or blocked page has a skeleton (`loading.tsx`). An indexable page has none, and no `` around `children` above it, so its content is in place in the first flush, and a link to it is the platform's `NavLink`, which shows a pending hint; an entity page (product, category, brand, seller, article, store branch, campaign) also answers a missing entity with a real 404 and a replaced one with a 308 ([b2c-b2b.md](references/b2c-b2b.md#rendering)). Every part that loads on its own has its own `` with a same-size skeleton and part boundary (EB-S). - Server side: repository → cache → server components. Pages, `generateMetadata`, and server components read only through caches. Client components get server data as props, or through React Query hydration when it must stay live. - Metadata: fixed values use the `metadata` export, and `generateMetadata` only values that depend on the request or on data (params, locale, a cache read); the same for `viewport` and `generateViewport`. Every app's `next.config.ts` sets `htmlLimitedBots: /.*/`, so metadata is always in ``, never streamed into ``. - Every root layout's viewport is `width: 'device-width', initialScale: 1, maximumScale: 1`, so iOS doesn't zoom in on a focused input. @@ -84,10 +85,10 @@ Any dependency outside this stack needs a stated reason and approval. - Env (`packages/libs/env`): only the app's `env/` files read `process.env`, through `createClientEnv` (public) and `createServerEnv` (server). Other projects use their own `getEnv`, filled by the app's bootstrap; libs get settings through `configure`. Never hard-code an env value (a service or CDN address, key, third-party ID, or flag) as a literal, a fallback (`?? 'http://localhost:3000'`), or a schema default: it comes from the serving app's `.env`, and only apps have `.env` files. Values equal in every environment go in `constants/`. - HTTP (`packages/libs/http`): one root `http` configured in bootstrap, one `http.extend(...)` per feature, and no `fetch` elsewhere. Cookie auth: on a 401 one refresh runs for the whole app, waiting requests replay once, a failed refresh logs out; the server never refreshes or sends auth cookies. Only idempotent requests retry, with backoff. Every request is abortable; aborts are silent. Uploads report progress. Every failure is an `HttpError` (`{ code, message, status, fieldErrors, hint, requestId, retryAfter }`) that the error handler lib shows and reports. -- `cookie`: browser only, small values the server needs (locale, theme), never tokens (auth cookies are HttpOnly and server-owned). Server code uses `next/headers`. `storage` (local storage): client-only, non-critical data under the app's prefix and persisted stores, never tokens or personal data. Neither is read during render, at module top level, or in repositories. +- `cookie`: browser only, small values the server needs (such as the theme), never tokens (auth cookies are HttpOnly and server-owned), and never the locale or currency of an indexable page, which its URL decides. Server code uses `next/headers`. `storage` (local storage): client-only, non-critical data under the app's prefix and persisted stores, never tokens or personal data. Neither is read during render, at module top level, or in repositories. - Service worker (`packages/libs/pwa`): one worker per app at `/sw.js`, written by `writeServiceWorker`, registered from the `AppShell` when the app's env turns it on. It stores only `/_next/static/` JS and CSS, `/fonts/` woff2 files, and `/icons/symbol-defs.svg`. Content-hashed JS and CSS (`chunks/`, `css/`, `immutable/`) are cache first, keyed by origin and path without the query string, with no network request on a hit; the rest is stale-while-revalidate by exact URL. Everything else reaches the network untouched; storing another kind needs a recorded decision. `/sw.js` is never renamed or removed; the env flag off unregisters the worker for every visitor. - PWA: each app is installable from its manifest (`configs/pwa.ts`), with a splash screen on Android (from the manifest) and on iOS (a startup image per device size). -- Structured data (`packages/libs/json-ld`, server only): every indexable page renders one schema.org graph with island's `JsonLd` in its page entry, from its first-paint data: the business (`OnlineStore`) and website on the home page from `configs/seo.ts`, other page types from a builder in the platform's `app/json-ld/`. It says only what the page shows, the same for every visitor: no member or personal price, no rating on the business. `noindex`, not-found, no-access, and error states render none. +- Structured data (`packages/libs/json-ld`, server only): every indexable page renders one schema.org graph with island's `JsonLd` in its page entry, in the first flush, from its first-paint data: the business (`OnlineStore`) and website on the home page from `configs/seo.ts`, other page types from a builder in the platform's `app/json-ld/`. It says only what the page shows, the same for every visitor: no member or personal price, no rating on the business. `noindex`, not-found, no-access, and error states render none. **Design system (island)** @@ -110,17 +111,17 @@ Any dependency outside this stack needs a stated reason and approval. ## 4. Workflow -For any design or implementation task, write a short plan in the PR description: affected projects and paths; each new component's path, level, and reason; data types; each route's streamed, deferred, and auth-dependent parts; each rendering override the developer asked for; each new non-obvious pattern. +For any design or implementation task, write a short plan in the PR description: affected projects and paths; each new component's path, level, and reason; data types; a link to the rendering doc of each new or changed page, and the first-load JS and HTML size of key routes; each rendering override the developer asked for; each new non-obvious pattern. 1. **Clarify the job:** who uses it, how often, and what they finish with it. State assumptions. -2. **Read** the playbook sections the task touches, and ui-rules.md for UI work (section 5). +2. **Read** the playbook sections the task touches, ui-rules.md for UI work, and the rendering doc of each page the task changes (section 5). 3. **Map the data:** entities, repository types, caches and how each client part gets server data, page and part models, actions and events, query keys, and the query-cache update after each mutation. -4. **Place the code:** list the Nx projects and folders that change; reuse before creating. Give each component its level and owner. For each part, decide whether it depends on the viewer, where it renders, and when its code loads. Add a pattern only for a signal you can name. Refactor code that resists the change first, in its own commit. +4. **Place the code:** list the Nx projects and folders that change; reuse before creating. Give each component its level and owner. For each section of a page, decide what search engines need from it, whether it depends on the viewer, where it renders, and when its code loads, and write it as a row of the page's rendering doc. Add a pattern only for a signal you can name. Refactor code that resists the change first, in its own commit. 5. **Design every state first:** loading, empty (no data, no results, not found, no access), error, in progress, then populated. 6. **Build in layer order** with island components: setup (Nx projects, tags, subpath exports, env variables), foundation (entities, repositories with mappers and query keys, caches, island variants), then each user story (actions, models, templates and organisms, route entry). Fix a bug in the layer that owns it, not in the UI. 7. **Wire feedback:** a toast for every completed action; field errors, a form alert, and an error toast with hint or reference ID and retry for a failed action; a boundary or empty state for a failed read; progress for long operations. 8. **Check performance:** bundle, hydration, web vitals, re-renders, flicker. -9. **Verify and deliver:** `nx affected -t ` for lint, type-check, and tests (target names: `nx show project `). Tick the Definition of Done, and note trade-offs: each new non-obvious pattern with its signal and the simpler option rejected, and smells left as debt. +9. **Verify and deliver:** `nx affected -t ` for lint, type-check, and tests (target names: `nx show project `). Check the crawler view of each changed page against a production build ([page-rendering.md](references/page-rendering.md#checking-the-crawler-view)). Tick the Definition of Done, and note trade-offs: each new non-obvious pattern with its signal and the simpler option rejected, and smells left as debt. ## 5. What to read @@ -134,6 +135,8 @@ For any design or implementation task, write a short plan in the PR description: | Adds a page, part, query, action, or form, or catches or shows an error | [error-handling.md](references/error-handling.md); [error-handling-code.md](references/error-handling-code.md) only to build or change a boundary, `ErrorFallback`, `readOnServer`, or the query client's error settings | | Adds a page | [page-example.md](references/page-example.md) | | Adds or moves a part of a page, or changes where it renders or when its code loads | [rendering-patterns.md](references/rendering-patterns.md#choosing-where-a-part-loads), then the sections its steps name | +| Adds a page, or changes a page's sections, where one renders, when its code loads, or what crawlers get; or documents or audits how a page renders | The page's rendering doc in `docs/pages/` first. Then [page-rendering.md](references/page-rendering.md), the sections its intro names for the task, and the page type's section of [page-type-maps.md](references/page-type-maps.md) | +| Shows the current time or the time left, such as a countdown or an open-now badge | [rendering-patterns.md](references/rendering-patterns.md#time-dependent-ui) | | Adds a pattern or shared abstraction (factory, `Record` map, state machine, adapter, context, generic hook) | [design-patterns.md](references/design-patterns.md) | | Refactors or reviews code | [refactoring.md](references/refactoring.md): for a review, [Smells that are intended here](references/refactoring.md#smells-that-are-intended-here), [Front-end smells](references/refactoring.md#front-end-smells), and [Review comments](references/refactoring.md#review-comments), plus the catalog row of each smell you name; for a refactor, [When and how](references/refactoring.md#when-and-how) and the technique you use. Also [Not used here](references/design-patterns.md#not-used-here) | | Builds or changes a lib, or needs lib behavior not described above | [lib-http.md](references/lib-http.md), [lib-error-handler.md](references/lib-error-handler.md), [lib-env.md](references/lib-env.md), [lib-cookie.md](references/lib-cookie.md), [lib-local-storage.md](references/lib-local-storage.md), [lib-pwa.md](references/lib-pwa.md), or [lib-json-ld.md](references/lib-json-ld.md) | diff --git a/.claude/skills/front-end-architect/references/b2c-b2b.md b/.claude/skills/front-end-architect/references/b2c-b2b.md index a1688c1..f02816a 100644 --- a/.claude/skills/front-end-architect/references/b2c-b2b.md +++ b/.claude/skills/front-end-architect/references/b2c-b2b.md @@ -18,8 +18,11 @@ These are defaults; tighten them per product in the plan. | TTFB, p75 | ≤ 0.8 s | | First-load JS per route, gzipped, framework included | ≤ 200 KB | | Route-specific client JS, gzipped | ≤ 100 KB | +| HTML per template, uncompressed, headers included, on the route's largest page | ≤ 1 MB | -Record the first-load JS of key routes from `next build` in the plan. Any increase on a key route needs a stated reason in the PR. +Googlebot reads only the first 2 MB of a page's uncompressed HTML, headers included, and drops the rest. The inline RSC payload repeats most of the page, and streamed parts come last, so they are the first content cut. Cap the items per listing page to stay within the HTML target. + +`next build` stopped printing first-load JS in Next.js 16. Measure it and the HTML size as [page-rendering.md](page-rendering.md#checking-the-crawler-view) shows, and record both for key routes in the plan. Any increase on a key route needs a stated reason in the PR. ## No server cache @@ -38,7 +41,7 @@ The Next.js server renders a fresh page for every request and keeps nothing betw }, ``` -- Every request pays for a full render, so keep it cheap: stream slow parts, fetch in parallel, and when a back-end call is slow, fix or cache it in the back end, never in Next.js. +- Every request pays for a full render, so keep it cheap: stream slow secondary parts, fetch in parallel, and when a back-end call is slow, fix or cache it in the back end, never in Next.js. ## Rendering @@ -46,10 +49,18 @@ The Next.js server renders a fresh page for every request and keeps nothing betw - The server render never depends on auth: every visitor of a URL gets the same server HTML. A page or part whose UI depends on the viewer (it needs a logged-in user, differs for guests, members, and paying members, or shows the viewer's own data) renders completely in the browser behind a same-size skeleton. What is the same for every visitor renders on the server. An explicit request from the developer overrides either default ([rendering-patterns.md](rendering-patterns.md#auth-dependent-ui)). - Templates stay Server Components. Interactive parts are small client components, each driven by its part model (`use---part.ts`). Don't turn a whole template into a client component to use a page model when only part of it is interactive. - Keep props passed to client components small and serializable; they are serialized into the page's RSC payload. -- Pages are thin entrypoints. The page resolves the device on the server and renders the mobile or the desktop template. Only that view's client code ships, the markup matches on hydration, and nothing shifts. Never choose between layouts with viewport checks in components. -- Stream: add `loading.tsx` per route group and `` with same-size skeletons around slow parts, each inside its own `PartBoundary`. One slow or failing backend call must never block the whole page. Record each route's streamed and auth-dependent parts in the plan. +- Pages are thin entrypoints. The page resolves the device on the server and renders the mobile or the desktop template, so the markup matches on hydration and nothing shifts. Never choose between layouts with viewport checks in components. +- Choose the template by device class only: `userAgent().device.type === 'mobile'` gets the mobile template, and everything else, tablets included, gets the desktop one. Never branch on `isBot`: content that differs for crawlers is cloaking. Where the repo has a unit test runner, a unit test pins Googlebot Smartphone to the mobile template, because Google indexes that template ([page-example.md](page-example.md)); otherwise propose one, which needs approval ([refactoring.md](refactoring.md#when-and-how)). +- Both templates' client components ship in the route's first-load JavaScript to every device, because the bundler builds a route's chunks from its imports, not from what one request renders. A heavy client component that only one template renders loads through `next/dynamic` in a small client component, so only the device that renders it downloads it. +- The reverse proxy or the CDN adds `Vary: User-Agent` to every HTML response, because one URL serves two templates, and Google's dynamic serving relies on the header. Next.js 16.4 overwrites a `Vary` set in `next.config.ts` or `proxy.ts` on page responses, so the app can't add it. +- Stream: every slow part with secondary content gets `` with a same-size skeleton, inside its own `PartBoundary`, so one slow or failing back-end call never blocks the whole page. Primary content never streams: a slow read it needs is fixed in the back end ([ui-rules.md](ui-rules.md#crawlers)). +- Indexable pages have nothing above them that streams: no `loading.tsx`, and no `` around `children` in a layout or in a component that a layout renders around them, such as the `AppShell` or a provider. React writes a boundary that is complete by the first flush in place only while the HTML of the shell, of the boundaries already in place, and its own stays within 12,800 bytes (its `progressiveChunkSize`, which Next.js doesn't change), or when its own HTML is 500 bytes or less. Above that, it writes the fallback in place and the content after the footer, in a hidden `
`, whatever the page awaits. A `loading.tsx` above an indexable page would therefore move its H1, content, and JSON-LD after the footer. +- Entity pages (product, category, brand, seller, article, store branch, campaign) are indexable pages whose URL names one record. With nothing above them that streams, their `generateMetadata` answers a missing entity with a real 404, and a replaced one with a 308, before the first byte ([error-handling.md](error-handling.md#b2cb2b-server)). +- Only `noindex` and blocked pages (search, compare, cart, checkout, account, login) have a `loading.tsx`, so a click shows their skeleton at once. A `loading.tsx` wraps every page below its folder, so put it beside its page, or in a route group that holds only such pages, such as `(account)` or `(auth)`. A link to an indexable page is the platform's `NavLink`, which shows a pending hint instead (Hydration and navigation). +- First flush: on an indexable page, the first byte waits for every read outside a ``, and, with `htmlLimitedBots`, for `generateMetadata`. So the page entry, and every Server Component outside a ``, await only the First flush reads, the reads the page's primary content needs; `generateMetadata` reads the same caches when it needs data, so they share one request. Any other read there holds the status line and the first byte: a secondary section with a read of its own streams in a part inside ``. - Server code reads data through the features' caches, so `generateMetadata`, the page, and every server component share one request per distinct call (see Data flow). -- Every indexable page renders its JSON-LD in the page entry, outside every ``, from the data its first paint already awaits, so structured data is in the initial HTML and costs no extra request ([lib-json-ld.md](lib-json-ld.md#rendering)). +- Every indexable page renders its JSON-LD in the page entry, before the template, from the data its first paint already awaits. So structured data is in the first flush and costs no extra request ([lib-json-ld.md](lib-json-ld.md#rendering)). +- Each page's rendering doc records its sections, where each one renders, and when its code loads ([page-rendering.md](page-rendering.md)). ## Server and client entries @@ -66,7 +77,7 @@ The Next.js server renders a fresh page for every request and keeps nothing betw A request becomes a page in this order. The server steps run per request, keep nothing afterwards, and never depend on who the viewer is. 1. Every root layout imports `bootstrap.server.ts` first. -2. The page resolves the device, awaits only what the first paint needs through caches or a server page loader, and renders the mobile or the desktop template. +2. The page resolves the device, awaits only the First flush reads (Rendering) through caches or a server page loader, and renders the mobile or the desktop template. 3. Server components that need more data read it through caches. A slow part is an async server component inside `` with a same-size skeleton, so the page streams around it. An auth-dependent part renders only its skeleton on the server. 4. Client components get server data as props or through query hydration (below). In the browser their models take over: queries through repositories, mutations through actions, and auth-dependent parts render their variant once the auth store knows the viewer. After a mutation that changes server-rendered content, `router.refresh()` renders the page again. @@ -82,7 +93,7 @@ A request becomes a page in this order. The server steps run per request, keep n - Props, for data the client part only shows or starts from: pass the `*Payload`, small and serializable. To stream it, pass the un-awaited promise and read it with `use()` inside ``. - Query hydration, for data the client part keeps live (refetches, pagination, filters, or mutations that update it): prefetch into a `QueryClient` from `getQueryClient()` in `configs/react-query.ts`, with the cache as the `queryFn`, and render the part inside ``. The part's model queries the same key and starts with the data. - - An awaited prefetch puts the data in the HTML. Wrap the server component in `` so the await streams. + - An awaited prefetch puts the data in the HTML. For a secondary part, wrap the server component in `` so the await streams. A primary section awaits its prefetch outside every ``, from a read the page entry also awaits, so the cache sends one request (Rendering). - An un-awaited prefetch doesn't block the part: the pending query is dehydrated and streams in, and the model reads it with `useSuspenseQuery`. Page or filter changes then go through `startTransition`, so the part keeps its content instead of falling back to the skeleton. - A server prefetch calls the cache, never the repository, so a server component that awaits the same data in the same request shares the request. @@ -95,7 +106,7 @@ A request becomes a page in this order. The server steps run per request, keep n The model, the boundaries, and their code are in [error-handling.md](error-handling.md). What is special here: -- Server reads classify on the server, because a Server Component error reaches the browser with only its digest. Pages and server parts read through `readOnServer`: the page calls `notFound()` for 404 and 410, renders the `no-access` empty state for 403 with `robots: { index: false }`; a part renders its empty state for 404 and 403. Everything else is rethrown to a boundary. +- Server reads classify on the server, because a Server Component error reaches the browser with only its digest. Pages and server parts read through `readOnServer`. `generateMetadata` and the page call `notFound()` for 404 and 410, which an indexable page answers with a real 404 ([error-handling.md](error-handling.md#b2cb2b-server)). The page renders the `no-access` empty state for 403, with `robots: { index: false }`. A part renders its empty state for 404 and 403. Everything else is rethrown to a boundary. - Boundaries: `app/global-error.tsx` is EB-W; every route group has `error.tsx` (page EB-S) and, when it calls `notFound()`, `not-found.tsx`; each part has a `PartBoundary` built with `catchError`, which lets `notFound()` and `redirect()` through. Error pages render `noindex`. - A part that must show an empty state awaits its read on the server; an un-awaited prefetch fits only reads that can't answer 404 or 403. - `instrumentation.ts` configures the error handler for the server and reports what no server code caught; `bootstrap.client.ts` configures it for the browser. @@ -104,10 +115,10 @@ The model, the boundaries, and their code are in [error-handling.md](error-handl - `configs/react-query.ts`: `getQueryClient()` returns a new `QueryClient` on every server call and one shared instance in the browser. `staleTime` is above zero (60 s) so hydrated data isn't refetched on mount, queries don't retry (the HTTP lib does), a failed first load throws to its boundary while a failed refetch keeps the data, and pending queries are dehydrated so they can stream. - zustand stores hold client state only. Never write to a store during server render: on the server a module-level store is shared by every request, so one user's data would leak to another. Pass server data through props or the query cache. If a store must start from server data, create it per request with `createStore` inside a provider. -- Server-side requests forward only the incoming request's cookies that the render needs, such as locale and theme, and never the auth cookies. Configure the HTTP lib once in `bootstrap.server.ts` with `configureServerHttp`: the server `baseUrl` from the app's server env, and a cookie provider that calls `cookies()` from `next/headers` on each request and keeps only the app's forwarded cookie names ([lib-http.md](lib-http.md#server-side)). That configures the root client, so every feature client forwards the same cookies. Never keep a user's cookies in module state. +- Server-side requests forward only the incoming request's cookies that the render needs, such as the theme, and never the auth cookies. Configure the HTTP lib once in `bootstrap.server.ts` with `configureServerHttp`: the server `baseUrl` from the app's server env, and a cookie provider that calls `cookies()` from `next/headers` on each request and keeps only the app's forwarded cookie names ([lib-http.md](lib-http.md#server-side)). That configures the root client, so every feature client forwards the same cookies. Never keep a user's cookies in module state. - On the server, the HTTP lib never refreshes, never calls `abortAll`, and retries at most once with a shorter timeout, so a slow back end doesn't hold up rendering (see [lib-http.md](lib-http.md#server-side)). - The server never reads or refreshes the session. The browser learns who the viewer is once per load through the auth store's `status`, and the browser's HTTP lib refreshes an expired session on a 401 ([rendering-patterns.md](rendering-patterns.md#auth-dependent-ui)). -- The `cookie` and `storage` libs are browser-only. Never read them during render: client components also render on the server, and the value would differ between server and browser. A value the page needs while rendering (theme, locale) is read on the server with `cookies()` and passed down as a prop. +- The `cookie` and `storage` libs are browser-only. Never read them during render: client components also render on the server, and the value would differ between server and browser. A value the page needs while rendering, such as the theme, is read on the server with `cookies()` and passed down as a prop. On an indexable page, the URL decides the locale and the currency, never a cookie ([ui-rules.md](ui-rules.md#crawlers)). - Persisted zustand stores set `skipHydration: true` and rehydrate in an effect of the platform's `AppShell`, so the first browser render matches the server's (code in code-patterns.md, Persisted store). ## Bundle and code splitting @@ -121,9 +132,9 @@ The model, the boundaries, and their code are in [error-handling.md](error-handl ## Hydration and navigation -- Render output must be identical on server and client: no `Date.now()`, `Math.random()`, `typeof window` branches, or locale and time-zone differences in render. Format dates and numbers with the locale and time zone the server chose. +- Render output must be identical on server and client: no `Date.now()`, `new Date()`, `Math.random()`, `typeof window` branches, or locale and time-zone differences in render. Format numbers with the locale the server chose. Format absolute dates on the server for everything the server renders, with every option pinned, and pass the text down; a browser-only part formats its own with `formatDateTime`. UI that shows the current time reads the shared clock ([rendering-patterns.md](rendering-patterns.md#time-dependent-ui)). - Fewer and smaller client boundaries hydrate faster. -- Navigate with `next/link` so routes prefetch. Keep the header and footer in layouts, so navigation re-renders only the page segment. +- Navigate with `next/link` so routes prefetch. Keep the header and footer in layouts, so navigation re-renders only the page segment. Indexable pages have no `loading.tsx`, so a link to one prefetches nothing, and the current page stays until the new one arrives: every link to an indexable page is the platform's `NavLink`, which shows a pending hint inside the clicked link ([rendering-patterns.md](rendering-patterns.md#loading-patterns)). - Protect INP: keep event handlers light, wrap non-urgent updates in `startTransition`, debounce search input by 250–400 ms, and for long interactive lists try `content-visibility` first; a virtualization library needs approval ([rendering-patterns.md](rendering-patterns.md)). ## Deploys and version skew diff --git a/.claude/skills/front-end-architect/references/definition-of-done.md b/.claude/skills/front-end-architect/references/definition-of-done.md index c6529b1..ba0812f 100644 --- a/.claude/skills/front-end-architect/references/definition-of-done.md +++ b/.claude/skills/front-end-architect/references/definition-of-done.md @@ -21,17 +21,18 @@ Structure [ ] Every action emits its event when it succeeds, unless called with { emit: false } [ ] No tokens or personal data in cookies or local storage; neither is read during render [ ] Every new pattern answers a named signal and sits where design-patterns.md puts it; none is on its "Not used here" list -[ ] Each new or moved part went through rendering-patterns.md's "Choosing where a part loads"; every deferred part and its trigger is written in the PR +[ ] Each new or moved section went through rendering-patterns.md's "Choosing where a part loads"; its row in the page's rendering doc names its HTML, JS, and Index values +[ ] Every new or changed page has its rendering doc in docs/pages// and its line in docs/pages/README.md, added or updated in this PR as page-rendering.md's "Keeping docs current" says; the doc passes its ready-for-review checks and matches the production HTML of both templates [ ] The server render is the same for every visitor; every auth-dependent page or part renders in the browser behind a same-size skeleton, unless the developer asked otherwise and the PR says so [ ] Fonts and the icon sprite keep fixed names that no step hashes; every sprite change raised ICON_SPRITE_VERSION in the same commit [ ] The service worker stores only /_next/static/ JS and CSS, fonts, and symbol-defs.svg: content-hashed JS and CSS cache first, the rest stale-while-revalidate; /sw.js keeps its name and its no-cache header -[ ] Every indexable page renders one JSON-LD graph through the json-ld lib and island's JsonLd, from its first-paint data; it says only what the page shows, the same for every visitor; noindex pages and error states have none +[ ] Every indexable page renders one JSON-LD graph through the json-ld lib and island's JsonLd, in the first flush, from its first-paint data; it says only what the page shows, the same for every visitor and in both templates; noindex pages and error states have none [ ] Refactors are in their own commits, and the PR states how unchanged behavior was checked; smells noticed but not fixed are listed as debt [ ] Code follows every accepted decision in docs/decisions; lasting decisions made in this work are recorded States and feedback [ ] Loading, empty, error, and in-progress states exist -[ ] Every page has a skeleton; every part that loads on its own has its own Suspense skeleton and part boundary (EB-S); the app has EB-W +[ ] Every noindex or blocked page has a skeleton (loading.tsx), and no indexable page has a loading.tsx above it; every part that loads on its own has its own Suspense skeleton and part boundary (EB-S); the app has EB-W [ ] Every completed action shows a toast, and every failed one the action-error toast with its hint or reference ID; reads never toast [ ] Errors follow error-handling.md: 404 and 403 reads show their empty state, ABORTED and 401 stay silent, retries follow the cause, 5xx and logic errors are reported once [ ] Query cache is updated or invalidated after every mutation; no stale data is visible @@ -54,12 +55,18 @@ Quality [ ] useSuspenseQuery only on queries the server prefetched [ ] global-error.tsx, error.tsx in every route group, and not-found.tsx where notFound() is called; error pages are noindex [ ] Server reads that can answer 404 or 403 go through readOnServer; every streamed part has a PartBoundary -[ ] Each route's streamed parts are decided and written in the plan -[ ] The server render is the same for every visitor: no session reads, no auth cookies forwarded, no variant picked on the server; auth-dependent parts render their skeleton until the browser knows the viewer, unless the developer asked otherwise +[ ] Each template's first flush holds the page's primary content: the H1, the main data, the breadcrumb, the LCP image, the JSON-LD, and the links that are the only path to other pages; the page entry and every Server Component outside a Suspense await only the First flush reads, the reads the primary content needs +[ ] Both templates hold the same H1, primary content, internal links, image URLs and alt texts, title, description, canonical, robots, JSON-LD, and status; collapsed content stays in the DOM +[ ] Links are with real URLs in the server HTML; menus, tabs, drawers, and sliders render the links and panels that search engines need while closed; pagination and indexable filters are links with self-canonical URLs +[ ] Indexable pages have no loading.tsx, and no Suspense around children, above them, and every link to them is the platform's NavLink; entity pages answer a missing entity with a real 404 and a replaced one with a 308 +[ ] robots.ts disallows /search, /compare, and, on listing paths only, sort orders and non-indexable filters; never product pages or their variant URLs, cart, or checkout +[ ] The template is chosen by device class only, never isBot; where the repo has a unit test runner, a unit test pins Googlebot Smartphone to the mobile template; the reverse proxy or CDN adds Vary: User-Agent to HTML responses +[ ] Time-dependent UI reads useClock behind a same-size skeleton; no clock in a client component's render; absolute dates in server-rendered output are formatted on the server; nothing refreshes when a countdown ends +[ ] The server render is the same for every visitor: no session reads, no auth cookies forwarded, no viewer-dependent variant picked on the server; auth-dependent parts render their skeleton until the browser knows the viewer, unless the developer asked otherwise [ ] Page is a thin entrypoint that renders the server-chosen mobile or desktop template [ ] 'use client' only on interactive leaves; no server-only code reachable from client bundles [ ] New server-only code is exported through server.ts and starts with import 'server-only' -[ ] First-load JS within budget; heavy widgets and third-party scripts deferred +[ ] First-load JS and each template's uncompressed HTML within budget, measured as page-rendering.md shows (next build no longer prints first-load JS); heavy widgets and third-party scripts deferred; a heavy client component that one template renders loads through next/dynamic [ ] No hydration warnings; LCP image not lazy; images, fonts, and banners cause no layout shift [ ] No store writes during server render; per-request QueryClient on the server [ ] No cookie or local-storage reads during render; persisted stores rehydrate after mount @@ -79,4 +86,4 @@ Every review comment names the rule, shows the problem, and proposes the fix. Fo Name a code smell and its technique, with the target layer or file, as [refactoring.md](refactoring.md#review-comments) does. A smell is a suggestion; when it also breaks a rule on the list below, lead with that rule, mark it blocking, and name the smell in the body. In a feature PR, raise smells only in the code the PR touches. Flag a pattern from the "Not used here" list in [design-patterns.md](design-patterns.md#not-used-here) with its alternative. Never flag the smells that refactoring.md marks as intended. -Block a merge only for: code that breaks an accepted project decision; a boundary or layer violation; a client-side dependency in a repository; server-only code reachable from a client bundle; tokens or personal data readable by JavaScript (a non-HttpOnly cookie or local storage); stale cache after a mutation; a sprite change without a version bump, a font changed under its old name, or a font or sprite name that a build step hashes; a service worker that stores anything beyond JS, CSS, fonts, and the icon sprite, or a renamed or removed `/sw.js`; structured data that says what the page doesn't show or depends on the viewer, or an `application/ld+json` script written outside island's `JsonLd`; missing error handling; missing loading or empty states; inaccessible contrast; UI that flickers on update; a server-side cache; a server render that depends on auth without the developer's explicit request; a page not rendered per request, or a web-vitals or bundle-budget regression. Everything else is a suggestion with a rationale. +Block a merge only for: code that breaks an accepted project decision; a boundary or layer violation; a client-side dependency in a repository; server-only code reachable from a client bundle; tokens or personal data readable by JavaScript (a non-HttpOnly cookie or local storage); stale cache after a mutation; a sprite change without a version bump, a font changed under its old name, or a font or sprite name that a build step hashes; a service worker that stores anything beyond JS, CSS, fonts, and the icon sprite, or a renamed or removed `/sw.js`; structured data that says what the page doesn't show or depends on the viewer, or an `application/ld+json` script written outside island's `JsonLd`; missing error handling; missing loading or empty states; inaccessible contrast; UI that flickers on update; a server-side cache; a server render that depends on auth without the developer's explicit request; a change to what a page's server HTML holds, or to when its code loads, without the matching rendering doc change; primary content, JSON-LD, or the only link to a page missing from the first flush of either template; an indexable page with a `loading.tsx`, or a `` around `children`, above it; a page not rendered per request, or a web-vitals, bundle-budget, or HTML-size regression. Everything else is a suggestion with a rationale. diff --git a/.claude/skills/front-end-architect/references/design-patterns.md b/.claude/skills/front-end-architect/references/design-patterns.md index 6aac03b..e852845 100644 --- a/.claude/skills/front-end-architect/references/design-patterns.md +++ b/.claude/skills/front-end-architect/references/design-patterns.md @@ -68,7 +68,7 @@ Where a new implementation goes: | Observer listener | An effect of the AppShell | Subscribe once, and return the unsubscribe function as the effect's cleanup | | Factory | Beside what it builds: in the module's main file when the module exists to build that thing (`createHttpClient` in `http.ts`), otherwise its own `create-.ts` in the owning module | `create(options): Thing`, returning an object literal or a closure | | Exhaustive check | `assertNever` in `packages/tools/src/assert-never/` | `assertNever(value: never): never` throws. Call it in the `default` of every `switch` over a union | -| Generic hook with no feature data, such as `useDebouncedValue` | `packages/tools/src/use-debounced-value/use-debounced-value.ts` when more than one project needs it; otherwise beside its only user, such as an organism's `hooks/` | A `use-.ts` hook that takes plain values and imports only React. A hook that reads a store, a query, or a `*Payload` belongs in the owning feature's `models/` or beside its store | +| Generic hook with no feature data, such as `useDebouncedValue` or `useClock` ([rendering-patterns.md](rendering-patterns.md#time-dependent-ui)) | `packages/tools/src/use-debounced-value/use-debounced-value.ts` when more than one project needs it; otherwise beside its only user, such as an organism's `hooks/` | A `use-.ts` hook that takes plain values and imports only React. A hook that reads a store, a query, or a `*Payload` belongs in the owning feature's `models/` or beside its store | The examples use feature paths relative to `platforms//src/`, as code-patterns.md does. diff --git a/.claude/skills/front-end-architect/references/error-handling-code.md b/.claude/skills/front-end-architect/references/error-handling-code.md index de54e64..f87ce03 100644 --- a/.claude/skills/front-end-architect/references/error-handling-code.md +++ b/.claude/skills/front-end-architect/references/error-handling-code.md @@ -269,34 +269,45 @@ export async function readOnServer(read: () => Promise): Promise/src/app/(shop)/seller/[slug]/page.tsx`. A seller page is the same for every visitor, so it reads on the server. A page that depends on the viewer, such as an order page, loads in the browser instead, and its reads reach the fallback as browser errors ([rendering-patterns.md](rendering-patterns.md#auth-dependent-ui)). `getSeller` is a cache, so the metadata and the page share one request, and the cache keeps a failure for the request too. +`apps//src/app/(shop)/seller/[slug]/page.tsx`. A seller page is the same for every visitor, so it reads on the server. A page that depends on the viewer, such as an order page, loads in the browser instead, and its reads reach the fallback as browser errors ([rendering-patterns.md](rendering-patterns.md#auth-dependent-ui)). A seller page is an entity page: no `loading.tsx` sits above it, so when `generateMetadata` calls `readSeller`, the status is decided before the first byte. A missing seller answers 404, and an old slug 308 ([error-handling.md](error-handling.md#b2cb2b-server)). `getSeller` is a cache, so the metadata and the page share one request, and the cache keeps a failure for the request too. `movedTo` stands for the current slug, which the back end sends when the URL used an old one. ```tsx import { StatusEmptyState } from '@project//app/error-boundaries'; +import { paths } from '@project//app/navigation'; import { getDevice, getSeller, readOnServer } from '@project//server'; import type { Metadata } from 'next'; -import { notFound } from 'next/navigation'; +import { notFound, permanentRedirect } from 'next/navigation'; import { SellerDesktop } from './templates/seller-desktop'; import { SellerMobile } from './templates/seller-mobile'; type SellerPageProps = { params: Promise<{ slug: string }> }; +// Throws for a missing or moved seller; returns 'ok' or 'no-access'. +async function readSeller(slug: string) { + const seller = await readOnServer(() => getSeller(slug)); + if (seller.status === 'not-found') notFound(); + if (seller.status === 'ok' && seller.data.movedTo) permanentRedirect(paths.seller(seller.data.movedTo)); + return seller; +} + export async function generateMetadata({ params }: SellerPageProps): Promise { const { slug } = await params; - const seller = await readOnServer(() => getSeller(slug)); + const seller = await readSeller(slug); if (seller.status !== 'ok') return { robots: { index: false } }; return { title: seller.data.name }; } export default async function SellerPage({ params }: SellerPageProps) { const { slug } = await params; - const [device, seller] = await Promise.all([getDevice(), readOnServer(() => getSeller(slug))]); - if (seller.status === 'not-found') notFound(); - if (seller.status === 'no-access') return ; + const [device, seller] = await Promise.all([getDevice(), readSeller(slug)]); + if (seller.status !== 'ok') return ; return device === 'mobile' ? : ; } ``` +- Both functions call `readSeller`. `generateMetadata` runs before the first byte, so its call sets the real status for every request that sends a `User-Agent`. The page's call decides it for a request without one, whose metadata streams, and narrows the type. +- Narrow with `status !== 'ok'` before touching `data`. Two checks such as `=== 'not-found'` and then `=== 'no-access'` never narrow the `{ status: 'not-found' | 'no-access' }` member away, so `seller.data` fails type-check. At run time `variant` is `'no-access'`, because `readSeller` has already thrown for `'not-found'`. + A server part, `.../seller/[slug]/organisms/seller-ratings/SellerRatings.tsx`: ```tsx diff --git a/.claude/skills/front-end-architect/references/error-handling.md b/.claude/skills/front-end-architect/references/error-handling.md index 95a4cea..9cf9df5 100644 --- a/.claude/skills/front-end-architect/references/error-handling.md +++ b/.claude/skills/front-end-architect/references/error-handling.md @@ -22,8 +22,8 @@ Contents: The model · What each failure shows · Boundaries · Reads · Actions ``` - **EB-X** is the nearest boundary around the code that failed: the part's EB-S, else the page's EB-S, else EB-W. -- **EB-W** sits only at the app root, above the shell, and catches only what nothing below it caught. It replaces the whole app, so it is the last resort. -- **EB-S** has two sizes. A page-size EB-S sits inside the shell, so a failed page keeps the header, navigation, and breadcrumbs usable. A part-size EB-S (`PartBoundary`) wraps each part that loads on its own, so one failed part never takes down the page ([SKILL.md](../SKILL.md#3-architecture-rules)). +- **EB-W** sits only at the app root, above the root layout, and catches only what nothing below it caught. It replaces the whole app, so it is the last resort. +- **EB-S** has two sizes. A page-size EB-S sits inside the layouts, so a failed page keeps the header, navigation, and breadcrumbs usable. A part-size EB-S (`PartBoundary`) wraps each part that loads on its own, so one failed part never takes down the page ([SKILL.md](../SKILL.md#3-architecture-rules)). - **Read** means getting information: queries, server component reads, and the data a page loads. **Action** means a write the user started: a mutation or a feature action. - Reads never toast. A failed read shows where its data would be, as an empty state or a fallback. Actions always toast, because the user is waiting for the result and the page they started from is still there. - **Empty state** covers every "nothing to show" case: a successful response with no items, a filter with no matches, a 404 or 410, and a 403. @@ -112,13 +112,35 @@ Rules: Server reads classify on the server, because a Server Component error reaches the browser with only its digest. - The page reads its main data through `readOnServer`, a server-only helper in the platform's `app/error-boundaries/`. It returns `{ status: 'ok', data }`, or `not-found` for 404 and 410 and `no-access` for 403, and rethrows the rest to the page's `error.tsx`. Server reads send no auth cookies, so only pages that are the same for every visitor read on the server; a page that needs a logged-in user loads in the browser ([rendering-patterns.md](rendering-patterns.md#auth-dependent-ui)). -- `not-found` calls `notFound()`, which renders the group's `not-found.tsx`. When the page has already started streaming (it has a `loading.tsx`), the status stays 200 and Next.js adds a `noindex` robots tag, which search engines treat as not found. +- Where `notFound()` runs decides the status: + - An indexable page has nothing above it that streams: no `loading.tsx`, and no `` around `children` in a layout or in a component that a layout renders around them ([b2c-b2b.md](b2c-b2b.md#rendering)). On an entity page (product, category, brand, seller, article, store branch, campaign), `generateMetadata` and the page call one read helper. The helper reads through `readOnServer` and the page's cache, calls `notFound()` for `not-found`, and calls `permanentRedirect()` when the payload names a replacement ([error-handling-code.md](error-handling-code.md#server-reads)). `generateMetadata` runs before the first byte, so crawlers get a real 404 with `noindex` in ``, at no extra read, or a 308 with `Location`. The page's call covers a request without a `User-Agent`, whose metadata streams. + - The server HTML of a real 404 has an empty ``, and the group's `not-found.tsx` renders in the browser. Google needs only the status, and it may not render a non-200 page at all. + - Moves known in advance, such as a renamed category tree, go in `redirects()` in `next.config.ts`, which answers before any render. A redirect thrown while the shell renders, or a failed read that `generateMetadata` rethrows, makes Next.js render again with a fresh cache, so the read runs twice. A back-end outage therefore doubles the reads that `generateMetadata` awaits, as on entity pages. + - A `noindex` or blocked page keeps its `loading.tsx`, so its status is already 200 when `notFound()` runs. Next.js then adds a `noindex` robots tag, in `` when `generateMetadata` throws and at the end of `` when the page throws, and renders the not-found UI only in the browser. A redirect becomes a ``. - `no-access` renders the page-size `StatusEmptyState`, and `generateMetadata` returns `robots: { index: false }` for it. Like `not-found` and every error page, it renders no JSON-LD ([lib-json-ld.md](lib-json-ld.md#rendering)). `forbidden()` and `unauthorized()` are experimental and not used ([rendering-patterns.md](rendering-patterns.md#rendering-patterns)). - A server part reads through `readOnServer` too: it renders the part-size `StatusEmptyState` for `not-found` and `no-access`, and rethrows the rest to its `PartBoundary`. - A part that must show an empty state awaits its read on the server. An un-awaited prefetch streams its error to the browser as a digest, so use it only for reads that can't answer 404 or 403. `shouldRedactErrors: () => false` in the dehydrate options keeps the real error on the server, so Next.js reports it and the browser gets its digest instead of a generic "redacted" error. - `error.tsx` and `global-error.tsx` render ``, so an error page is never indexed. - `instrumentation.ts` configures the error handler for the server and calls `handleError` from `onRequestError` ([lib-error-handler.md](lib-error-handler.md#usage)). +Status per case, measured on Next.js 16.4. No page answers 410: Google treats it like 404, and Next.js has no API for it. + +| Case | Status | The server HTML holds | +|---|---|---| +| Entity missing | 404 | `noindex` in `` and an empty ``; `not-found.tsx` renders in the browser | +| Entity replaced by another | 308 to the replacement | nothing that matters | +| Product out of stock, or discontinued with its content kept | 200, indexable | the page, with its stock text, and its availability in the JSON-LD | +| Listing page past the last; empty, duplicate, or unknown combination of indexable filters | 404 | as for a missing entity | +| Empty listing whose URL includes a filter that `robots.ts` blocks | 200 | the listing, with the `no-results` empty state and Clear filters | +| Category with no products | 200 with `noindex` while the menu links it; 404 once it leaves the menu | the page, with the `no-data` empty state | +| Search with no results | 200; `/search` is blocked in `robots.ts` | the `no-results` empty state; never 5xx for an unknown query | +| A failed read on an indexable page, in `generateMetadata`, the page entry, or another Server Component outside every `` | 500 | `noindex` and an empty ``; `error.tsx` renders in the browser | +| A failed read in a part inside its `` and `PartBoundary` | 200 | the part's skeleton; the `PartBoundary` fallback renders in the browser | +| A failed read in a layout above the page, such as the `(shop)` layout's `getMenu()` | 500, on every page under that layout | `noindex` and an empty `` | +| `notFound()` on a `noindex` or blocked page, under its `loading.tsx` | 200 | the skeleton and `noindex`; the not-found UI renders in the browser | +| A failed read on a `noindex` or blocked page, under its `loading.tsx` | 200 | the skeleton; a `noindex` page keeps the `noindex` of its `metadata` export, and a blocked page has no robots tag; `error.tsx` and its `noindex` render in the browser | +| Overload | 503 with `Retry-After`, from the reverse proxy or the CDN | — | + ## Reporting - `handleError` runs once per error, where it stops: a fallback, `showActionError`, `QueryCache.onError`, or the server's `onRequestError`. Never call it in a repository, an action, or a `catch` that rethrows. @@ -153,4 +175,5 @@ The boundaries, `ErrorFallback`, `readOnServer`, and the query client's error se [ ] Successful empty responses show the no-data or no-results empty state with a next step [ ] handleError runs once per error, where it stops; 5xx and logic errors reach the tracker with requestId or digest [ ] Server reads go through readOnServer; error pages and no-access pages are noindex +[ ] Indexable pages have no loading.tsx, and no Suspense around children, above them; an entity page's generateMetadata answers a missing entity with notFound() (404) and a replaced one with permanentRedirect() (308) before the first byte ``` diff --git a/.claude/skills/front-end-architect/references/lib-cookie.md b/.claude/skills/front-end-architect/references/lib-cookie.md index 73b967c..d1a78aa 100644 --- a/.claude/skills/front-end-architect/references/lib-cookie.md +++ b/.claude/skills/front-end-architect/references/lib-cookie.md @@ -6,7 +6,7 @@ Contents: What cookies are for · Structure · Types · API · Keys · Browser o ## What cookies are for -- Only small values the server must see on the request: `locale`, `theme`, and device preference (so the server renders the right version without a flash), and the consent choice. +- Only small values the server must see on the request: `theme` (so the server renders it without a flash), a `locale` preference, and the consent choice. A locale cookie never decides the locale of an indexable page, which its URL decides ([ui-rules.md](ui-rules.md#crawlers)), and no cookie picks the mobile or desktop template, which comes from the User-Agent's device class only ([b2c-b2b.md](b2c-b2b.md#rendering)). - Every cookie is sent with every request to its domain and path and holds about 4 KB. Anything the server doesn't need goes to local storage ([lib-local-storage.md](lib-local-storage.md)). - Never auth tokens. Auth cookies are `HttpOnly`, set and rotated by the server, and JavaScript can't and mustn't read them (see [lib-http.md](lib-http.md), Refresh token). Never secrets or personal data. diff --git a/.claude/skills/front-end-architect/references/lib-http.md b/.claude/skills/front-end-architect/references/lib-http.md index 438ddcd..3d30e0b 100644 --- a/.claude/skills/front-end-architect/references/lib-http.md +++ b/.claude/skills/front-end-architect/references/lib-http.md @@ -257,7 +257,7 @@ interface DownloadResult { ## Server side - `bootstrap.server.ts` calls `configureServerHttp` once (code below). It sets the root's server `baseUrl` (from the app's server env, for example an internal service address) and the cookie provider on the root, so every feature client forwards the same cookies. A feature with its own `baseUrl` reads it through its project's `getEnv()`, which the server bootstrap fills with the server-side address. -- `getCookieHeader` runs on every server request and forwards only the names in the app's `FORWARDED_COOKIES`, the cookies the server render needs, such as `LOCALE_COOKIE` and `THEME_COOKIE`. It never forwards the auth cookies, so no back-end response on the server depends on who the viewer is ([rendering-patterns.md](rendering-patterns.md#auth-dependent-ui)). Never keep cookies, users, or tokens in module state. +- `getCookieHeader` runs on every server request and forwards only the names in the app's `FORWARDED_COOKIES`, the cookies the server render needs, such as `THEME_COOKIE`. An indexable page's locale comes from its URL, never from a forwarded cookie ([ui-rules.md](ui-rules.md#crawlers)). In an app with more than one locale, the page passes its URL's locale to its cache calls, and the repository sends it as the back-end request's `Accept-Language` header, in that request's `headers` option. The server registers no `Accept-Language` interceptor: an interceptor never sees the URL, and a module-level language would serve every request. It never forwards the auth cookies, so no back-end response on the server depends on who the viewer is ([rendering-patterns.md](rendering-patterns.md#auth-dependent-ui)). Never keep cookies, users, or tokens in module state. - On the server, refresh is off, `abortAll` is unavailable, retry defaults to one attempt with a shorter timeout, `credentials` is ignored, and every request is sent with `cache: 'no-store'`, whatever `init` says. - `init` never carries Next.js caching options (`next: { revalidate, tags }`): the Next.js server keeps no cache between requests (see [b2c-b2b.md](b2c-b2b.md#no-server-cache)). diff --git a/.claude/skills/front-end-architect/references/lib-json-ld.md b/.claude/skills/front-end-architect/references/lib-json-ld.md index 2b79718..82ca6e7 100644 --- a/.claude/skills/front-end-architect/references/lib-json-ld.md +++ b/.claude/skills/front-end-architect/references/lib-json-ld.md @@ -16,7 +16,7 @@ Contents: What each page gets · What the markup may say · Structure · Types | Returns policy | `buildOrganization` with `returnPolicy` | The store's return window and fees on its product results | | Shipping policy | `buildOrganization` with `shipping` | The store's delivery cost and time on its product results | | Store branch | `buildStore` and `buildBreadcrumbList` | The branch's address, opening hours, and phone | -| Search results, cart, checkout, account, compare, and every not-found, no-access, or error state | Nothing | Nothing: these pages are `noindex` | +| Search results, cart, checkout, account, compare, and every not-found, no-access, or error state | Nothing | Nothing: these pages are `noindex`, or blocked in `robots.ts` | - One graph per page: the page passes its nodes to `buildGraph` and renders the result with one ``. - The platform's `app/json-ld/` holds one builder per page type that maps a `*Payload`, such as `buildProductPageJsonLd(product)`. The home and policy pages build theirs from the business facts in the app's `configs/seo.ts` (Usage). @@ -25,7 +25,7 @@ Contents: What each page gets · What the markup may say · Structure · Types Google shows rich results only from markup it trusts, and a manual action for misleading markup makes it ignore the site's markup. So: -- Only what the page shows. The name, price, sale price, availability, rating, review count, reviews, and policies match the server HTML of the same URL. They come from the same `*Payload` in the same request, so they match by construction. Never add a value the page doesn't show; identifiers (`sku`, `gtin`, `mpn`) and the brand may stay invisible. +- Only what the page shows. The name, price, sale price, availability, rating, review count, reviews, and policies match the server HTML of the same URL, in both templates. They come from the same `*Payload` in the same request, so they match by construction. Never add a value the page doesn't show; identifiers (`sku`, `gtin`, `mpn`) and the brand may stay invisible. - The same for every visitor. Build it only from what the server render reads, never from the viewer: no member price, personal price, cart, or recommendation. A page whose price depends on the viewer, such as a B2B price list after login, has no `offer`; its product can still carry its rating. - The page's main thing. A product page marks up its product, never the products in its rails, which have their own pages. - No self-serving ratings. `rating` and `reviews` go on products only, never on the organization or a store: Google ignores what a business shows about itself. @@ -270,7 +270,7 @@ JSON-LD is read by machines in every locale, so its values keep their machine fo ## Rendering -- Where: in the page entry (`page.tsx`), once, before the mobile or desktop template and outside every ``, so it's near the top of the HTML. Google prefers product markup in the initial HTML and reads only the first 2 MB of a page. An element inside `` arrives at the end of the stream, in a hidden `
` that client JavaScript moves into place. Never in a layout, where every page under it would repeat it; in a template, which the page has in two versions; in a streamed part; or in a client component, which can't import the lib. +- Where: in the page entry (`page.tsx`), once, before the mobile or desktop template, in the first flush, so it's near the top of the HTML. Google prefers product markup in the initial HTML and reads only the first 2 MB of a page. What streams arrives at the end of the document, in a hidden `
` that client JavaScript moves into place. An indexable page has nothing above it that streams, no `loading.tsx` included, so its page entry is always in the first flush ([b2c-b2b.md](b2c-b2b.md#rendering)). Never in a layout, where every page under it would repeat it; in a template, which the page has in two versions; in a part inside ``; or in a client component, which can't import the lib. - Inside an element: the root layout renders page content inside an element such as `
`, so no JSON-LD is a direct child of `` or ``. When the root fails to hydrate, React renders the document again in the browser but keeps the scripts that sit directly under `` and ``, and Google then reads two copies. - A native `