create-react-starter-kit 1.0.6 → 1.0.7

package/dist/templates/__when_apiLayer_fetch__/src/services/http/client.ts.ejs

@@ -0,0 +1,195 @@
+import { env } from '@/config/env';
+import { ApiError, mapStatusToCode } from './errors';
+
+const REQUEST_ID_HEADER = 'X-Request-Id';
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+<% if (isTypeScript) { -%>
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+export interface RequestOptions extends Omit<RequestInit, 'method' | 'body'> {
+  method?: HttpMethod;
+  body?: unknown;
+  timeoutMs?: number;
+  /** Skip JSON Content-Type / body serialization when sending FormData, etc. */
+  rawBody?: boolean;
+}
+<% } -%>
+
+/**
+ * Swap this for your real auth storage (cookie, memory store, secure storage).
+ */
+function getAccessToken()<% if (isTypeScript) { %>: string | null<% } %> {
+  if (typeof window === 'undefined') return null;
+  return window.localStorage.getItem('access_token');
+}
+
+function createRequestId()<% if (isTypeScript) { %>: string<% } %> {
+  if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+    return crypto.randomUUID();
+  }
+  return `req_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+}
+
+async function parseErrorBody(response<% if (isTypeScript) { %>: Response<% } %>)<% if (isTypeScript) { %>: Promise<unknown><% } %> {
+  const contentType = response.headers.get('content-type') ?? '';
+  if (contentType.includes('application/json')) {
+    try {
+      return await response.json();
+    } catch {
+      return undefined;
+    }
+  }
+  try {
+    return await response.text();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Shared fetch wrapper with auth header, request IDs, timeout, and normalized errors.
+ * Prefer domain helpers in `services/api` over calling this from components.
+ */
+export async function request<% if (isTypeScript) { %><T = unknown><% } %>(
+  path<% if (isTypeScript) { %>: string<% } %>,
+  options<% if (isTypeScript) { %>: RequestOptions = {}<% } else { %> = {}<% } %>,
+)<% if (isTypeScript) { %>: Promise<T><% } %> {
+  const {
+    method = 'GET',
+    body,
+    headers: initHeaders,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    rawBody = false,
+    signal: userSignal,
+    ...rest
+  } = options;
+
+  const requestId = createRequestId();
+  const headers = new Headers(initHeaders);
+  headers.set(REQUEST_ID_HEADER, requestId);
+  headers.set('Accept', 'application/json');
+
+  const token = getAccessToken();
+  if (token) {
+    headers.set('Authorization', `Bearer ${token}`);
+  }
+
+  let payload<% if (isTypeScript) { %>: BodyInit | undefined<% } %>;
+  if (body !== undefined && body !== null) {
+    if (rawBody) {
+      payload = body<% if (isTypeScript) { %> as BodyInit<% } %>;
+    } else {
+      headers.set('Content-Type', 'application/json');
+      payload = JSON.stringify(body);
+    }
+  }
+
+  const controller = new AbortController();
+  const onAbort = () => controller.abort();
+  if (userSignal) {
+    if (userSignal.aborted) controller.abort();
+    else userSignal.addEventListener('abort', onAbort, { once: true });
+  }
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(`${env.apiBaseUrl}${path}`, {
+      ...rest,
+      method,
+      headers,
+      body: payload,
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const details = await parseErrorBody(response);
+      const message =
+        details && typeof details === 'object' && 'message' in details && typeof details.message === 'string'
+          ? details.message
+          : `Request failed with status ${response.status}`;
+
+      const apiError = new ApiError({
+        message,
+        status: response.status,
+        code: mapStatusToCode(response.status),
+        details,
+        requestId,
+      });
+
+      if (apiError.isUnauthorized && typeof window !== 'undefined') {
+        window.dispatchEvent(new CustomEvent('auth:unauthorized', { detail: apiError }));
+      }
+
+      throw apiError;
+    }
+
+    if (response.status === 204) {
+      return undefined<% if (isTypeScript) { %> as T<% } %>;
+    }
+
+    return (await response.json())<% if (isTypeScript) { %> as T<% } %>;
+  } catch (error) {
+    if (error instanceof ApiError) throw error;
+
+    if (error instanceof DOMException && error.name === 'AbortError') {
+      const timedOut = !userSignal?.aborted;
+      throw new ApiError({
+        message: timedOut ? 'Request timed out. Please try again.' : 'Request was cancelled.',
+        code: timedOut ? 'TIMEOUT' : 'NETWORK',
+        requestId,
+        cause: error,
+      });
+    }
+
+    throw new ApiError({
+      message: error instanceof Error ? error.message : 'Network error. Check your connection and try again.',
+      code: 'NETWORK',
+      requestId,
+      cause: error,
+    });
+  } finally {
+    clearTimeout(timeoutId);
+    userSignal?.removeEventListener('abort', onAbort);
+  }
+}
+
+export async function apiGet<% if (isTypeScript) { %><T = unknown><% } %>(
+  path<% if (isTypeScript) { %>: string<% } %>,
+  options<% if (isTypeScript) { %>?: Omit<RequestOptions, 'method' | 'body'><% } %>,
+)<% if (isTypeScript) { %>: Promise<T><% } %> {
+  return request<% if (isTypeScript) { %><T><% } %>(path, { ...options, method: 'GET' });
+}
+
+export async function apiPost<% if (isTypeScript) { %><T = unknown, B = unknown><% } %>(
+  path<% if (isTypeScript) { %>: string<% } %>,
+  body<% if (isTypeScript) { %>?: B<% } %>,
+  options<% if (isTypeScript) { %>?: Omit<RequestOptions, 'method' | 'body'><% } %>,
+)<% if (isTypeScript) { %>: Promise<T><% } %> {
+  return request<% if (isTypeScript) { %><T><% } %>(path, { ...options, method: 'POST', body });
+}
+
+export async function apiPut<% if (isTypeScript) { %><T = unknown, B = unknown><% } %>(
+  path<% if (isTypeScript) { %>: string<% } %>,
+  body<% if (isTypeScript) { %>?: B<% } %>,
+  options<% if (isTypeScript) { %>?: Omit<RequestOptions, 'method' | 'body'><% } %>,
+)<% if (isTypeScript) { %>: Promise<T><% } %> {
+  return request<% if (isTypeScript) { %><T><% } %>(path, { ...options, method: 'PUT', body });
+}
+
+export async function apiPatch<% if (isTypeScript) { %><T = unknown, B = unknown><% } %>(
+  path<% if (isTypeScript) { %>: string<% } %>,
+  body<% if (isTypeScript) { %>?: B<% } %>,
+  options<% if (isTypeScript) { %>?: Omit<RequestOptions, 'method' | 'body'><% } %>,
+)<% if (isTypeScript) { %>: Promise<T><% } %> {
+  return request<% if (isTypeScript) { %><T><% } %>(path, { ...options, method: 'PATCH', body });
+}
+
+export async function apiDelete<% if (isTypeScript) { %><T = unknown><% } %>(
+  path<% if (isTypeScript) { %>: string<% } %>,
+  options<% if (isTypeScript) { %>?: Omit<RequestOptions, 'method' | 'body'><% } %>,
+)<% if (isTypeScript) { %>: Promise<T><% } %> {
+  return request<% if (isTypeScript) { %><T><% } %>(path, { ...options, method: 'DELETE' });
+}
+
+export { ApiError };

package/dist/templates/__when_apiLayer_fetch__/src/services/http/errors.ts.ejs

@@ -0,0 +1,81 @@
+<% if (isTypeScript) { -%>
+export type ApiErrorCode =
+  | 'NETWORK'
+  | 'TIMEOUT'
+  | 'UNAUTHORIZED'
+  | 'FORBIDDEN'
+  | 'NOT_FOUND'
+  | 'VALIDATION'
+  | 'SERVER'
+  | 'UNKNOWN';
+
+export class ApiError extends Error {
+  readonly status?: number;
+  readonly code: ApiErrorCode;
+  readonly details?: unknown;
+  readonly requestId?: string;
+
+  constructor(options: {
+    message: string;
+    status?: number;
+    code?: ApiErrorCode;
+    details?: unknown;
+    requestId?: string;
+    cause?: unknown;
+  }) {
+    super(options.message, options.cause ? { cause: options.cause } : undefined);
+    this.name = 'ApiError';
+    this.status = options.status;
+    this.code = options.code ?? 'UNKNOWN';
+    this.details = options.details;
+    this.requestId = options.requestId;
+  }
+
+  get isUnauthorized() {
+    return this.status === 401 || this.code === 'UNAUTHORIZED';
+  }
+
+  get isRetryable() {
+    return this.code === 'NETWORK' || this.code === 'TIMEOUT' || this.code === 'SERVER';
+  }
+}
+
+export function mapStatusToCode(status?: number): ApiErrorCode {
+  if (!status) return 'NETWORK';
+  if (status === 401) return 'UNAUTHORIZED';
+  if (status === 403) return 'FORBIDDEN';
+  if (status === 404) return 'NOT_FOUND';
+  if (status === 422 || status === 400) return 'VALIDATION';
+  if (status >= 500) return 'SERVER';
+  return 'UNKNOWN';
+}
+<% } else { -%>
+export class ApiError extends Error {
+  constructor(options) {
+    super(options.message, options.cause ? { cause: options.cause } : undefined);
+    this.name = 'ApiError';
+    this.status = options.status;
+    this.code = options.code ?? 'UNKNOWN';
+    this.details = options.details;
+    this.requestId = options.requestId;
+  }
+
+  get isUnauthorized() {
+    return this.status === 401 || this.code === 'UNAUTHORIZED';
+  }
+
+  get isRetryable() {
+    return this.code === 'NETWORK' || this.code === 'TIMEOUT' || this.code === 'SERVER';
+  }
+}
+
+export function mapStatusToCode(status) {
+  if (!status) return 'NETWORK';
+  if (status === 401) return 'UNAUTHORIZED';
+  if (status === 403) return 'FORBIDDEN';
+  if (status === 404) return 'NOT_FOUND';
+  if (status === 422 || status === 400) return 'VALIDATION';
+  if (status >= 500) return 'SERVER';
+  return 'UNKNOWN';
+}
+<% } -%>

package/dist/templates/__when_apiLayer_fetch__/src/services/http/index.ts.ejs

@@ -0,0 +1,5 @@
+export { request, apiGet, apiPost, apiPut, apiPatch, apiDelete, ApiError } from './client';
+<% if (isTypeScript) { -%>
+export type { ApiErrorCode } from './errors';
+export type { HttpMethod, RequestOptions } from './client';
+<% } -%>

package/dist/templates/__when_buildTool_webpack__/webpack.config.js.ejs

@@ -105,7 +105,7 @@ export default (_env, argv) => {
       }),
     ],
     devServer: {
-      port: 5173,
+      port: 3000,
       historyApiFallback: true,
       hot: true,
       open: false,

package/dist/templates/__when_e2eTesting_cypress__/cypress.config.ts.ejs

@@ -1,8 +1,9 @@
 import { defineConfig } from 'cypress';
 
+<% const e2ePort = buildTool === 'webpack' ? 3000 : 5173; -%>
 export default defineConfig({
   e2e: {
-    baseUrl: 'http://127.0.0.1:5173',
+    baseUrl: 'http://127.0.0.1:<%= e2ePort %>',
     supportFile: false,
   },
 });

package/dist/templates/__when_e2eTesting_playwright__/playwright.config.ts.ejs

@@ -3,6 +3,7 @@ import { defineConfig, devices } from '@playwright/test';
 /**
  * Run once before first e2e: `<%= packageManager === 'npm' ? 'npm run' : packageManager %> test:e2e:install`
  */
+<% const e2ePort = buildTool === 'webpack' ? 3000 : 5173; -%>
 export default defineConfig({
   testDir: './tests/e2e',
   fullyParallel: true,
@@ -10,7 +11,7 @@ export default defineConfig({
   retries: process.env.CI ? 1 : 0,
   reporter: process.env.CI ? 'github' : 'list',
   use: {
-    baseURL: 'http://127.0.0.1:5173',
+    baseURL: 'http://127.0.0.1:<%= e2ePort %>',
     trace: 'on-first-retry',
     screenshot: 'only-on-failure',
   },
@@ -19,13 +20,13 @@ export default defineConfig({
       '<%= buildTool === 'vite'
         ? 'npx vite --host 127.0.0.1 --port 5173'
         : buildTool === 'webpack'
-          ? 'npx webpack serve --mode development --port 5173'
+          ? 'npx webpack serve --mode development --port 3000'
           : packageManager === 'npm'
             ? 'npm run dev'
             : packageManager === 'yarn'
               ? 'yarn dev'
               : 'pnpm dev' %>',
-    url: 'http://127.0.0.1:5173',
+    url: 'http://127.0.0.1:<%= e2ePort %>',
     reuseExistingServer: !process.env.CI,
     timeout: 120_000,
   },

package/dist/templates/__when_serverState_rtk-query__/src/store/postsApi.ts.ejs

@@ -1,19 +1,42 @@
 import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';
 <% if (isTypeScript) { -%>
-import type { Post } from '@/services/api';
+import type { FeedbackPayload, Post } from '@/types/models';
 <% } -%>
 import { env } from '@/config/env';
 
-const baseUrl = env.apiBaseUrl;
-
+/**
+ * RTK Query owns HTTP for this stack — no separate Axios/Fetch client is generated.
+ * Use `prepareHeaders` for auth and `tagTypes` for cache invalidation.
+ */
 export const postsApi = createApi({
   reducerPath: 'postsApi',
-  baseQuery: fetchBaseQuery({ baseUrl }),
+  baseQuery: fetchBaseQuery({
+    baseUrl: env.apiBaseUrl,
+    prepareHeaders: (headers) => {
+      const token =
+        typeof window !== 'undefined' ? window.localStorage.getItem('access_token') : null;
+      if (token) {
+        headers.set('Authorization', `Bearer ${token}`);
+      }
+      headers.set('Accept', 'application/json');
+      return headers;
+    },
+  }),
+  tagTypes: ['Posts'],
   endpoints: (builder) => ({
     getPosts: builder.query<% if (isTypeScript) { %><Post[], void><% } %>({
       query: () => '/posts?_limit=5',
+      providesTags: ['Posts'],
+    }),
+    createFeedback: builder.mutation<% if (isTypeScript) { %><{ id: number }, FeedbackPayload><% } %>({
+      query: (body) => ({
+        url: '/posts',
+        method: 'POST',
+        body,
+      }),
+      invalidatesTags: ['Posts'],
     }),
   }),
 });
 
-export const { useGetPostsQuery } = postsApi;
+export const { useGetPostsQuery, useCreateFeedbackMutation } = postsApi;

package/dist/templates/__when_unitTesting_vitest__/tests/feedback.test.tsx.ejs

@@ -4,6 +4,19 @@ import userEvent from '@testing-library/user-event';
 import { FeedbackForm } from '@/features/feedback/FeedbackForm';
 import { renderWithProviders } from './test-utils';
 
+<% if (serverState === 'rtk-query') { -%>
+const createFeedback = vi.fn(() => ({
+  unwrap: vi.fn(async () => ({ id: 101 })),
+}));
+
+vi.mock('@/store/postsApi', async (importOriginal) => {
+  const actual = await importOriginal<% if (isTypeScript) { %><typeof import('@/store/postsApi')><% } %>();
+  return {
+    ...actual,
+    useCreateFeedbackMutation: () => [createFeedback, { isLoading: false }],
+  };
+});
+<% } else { -%>
 vi.mock('@/services/api', async (importOriginal) => {
   const actual = await importOriginal<% if (isTypeScript) { %><typeof import('@/services/api')><% } %>();
   return {
@@ -11,6 +24,7 @@ vi.mock('@/services/api', async (importOriginal) => {
     createFeedback: vi.fn(async () => ({ id: 101 })),
   };
 });
+<% } -%>
 
 describe('FeedbackForm', () => {
   beforeEach(() => {
@@ -30,7 +44,9 @@ describe('FeedbackForm', () => {
 
   it('submits valid feedback and shows success status', async () => {
     const user = userEvent.setup();
+<% if (serverState !== 'rtk-query') { -%>
     const { createFeedback } = await import('@/services/api');
+<% } -%>
     renderWithProviders(<FeedbackForm />);
 
     await user.type(screen.getByPlaceholderText('Ada Lovelace'), 'Ada Lovelace');

package/dist/templates/__when_unitTesting_vitest__/tests/posts.test.tsx.ejs

@@ -4,6 +4,7 @@ import userEvent from '@testing-library/user-event';
 import { PostsPanel } from '@/features/posts/PostsPanel';
 import { renderWithProviders } from './test-utils';
 
+<% if (serverState !== 'rtk-query') { -%>
 vi.mock('@/services/api', async (importOriginal) => {
   const actual = await importOriginal<% if (isTypeScript) { %><typeof import('@/services/api')><% } %>();
   return {
@@ -14,9 +15,6 @@ vi.mock('@/services/api', async (importOriginal) => {
     ]),
   };
 });
-
-<% if (serverState === 'rtk-query') { -%>
-// RTK Query uses its own endpoint; mock still covers the transport used by other modes.
 <% } -%>
 
 describe('PostsPanel', () => {

package/dist/templates/docs/architecture.md.ejs

@@ -21,52 +21,71 @@ You selected a coherent default-friendly stack during scaffolding. The generator
 
 ```text
 src/
-  main.<%= jsxExt %>    # bootstrap + render
-  providers.<%= jsxExt %>
-  App.<%= jsxExt %>     # route tree
+  main.<%= jsxExt %>       # bootstrap + render
+  providers.<%= jsxExt %>  # global providers (store, query, theme)
+  App.<%= jsxExt %>        # route tree
   assets/
-  components/         # shared UI (layout/, ui/)
-  config/
-  features/           # domain modules
+  components/            # shared UI (layout/, ui/)
+  config/                # env + app config
+  features/              # domain modules (counter, posts, feedback)
   hooks/
-  lib/
-  routes/             # / /counter /posts /feedback /about
-  services/
-  store/
+  lib/                   # validation, monitoring helpers
+  routes/                # page-level route components
+  services/              # HTTP client + domain API (when selected)
+  store/                 # client state + RTK Query APIs (when selected)
   styles/
-  types/
+  types/                 # shared domain models
   utils/
 ```
 
 **Rules of thumb**
 
 - Put new product work in `src/features/<domain>/`.
-- Keep `components/` dumb and reusable.
+- Keep `components/` presentational and reusable.
 - Import with the `@/` alias.
 - Prefer a feature's public surface over deep cross-feature imports.
+- Keep providers thin — wiring belongs in `providers.<%= jsxExt %>`, business logic does not.
 
 ## Routes
 
-| Path | Purpose |
-|------|---------|
-| `/` | Home overview |
-| `/counter` | Client state demo |
-| `/posts` | Server state / data fetching |
-| `/feedback` | Forms + validation |
-| `/about` | Orientation |
+| Path | Purpose | Primary demo |
+|------|---------|--------------|
+| `/` | Home overview | Stack orientation |
+| `/counter` | Client state | <%= stackLabels.stateManagement %> |
+| `/posts` | Server state | <%= stackLabels.serverState %> |
+| `/feedback` | Forms + validation | <%= stackLabels.forms %> |
+| `/about` | Orientation | Architecture notes |
 
 ## Path aliases
 
-`@/*` maps to `src/*` in TypeScript/JS config and in your bundler.
+`@/*` maps to `src/*` in TypeScript/JS config and in your bundler. Prefer `@/features/...` over long relative paths.
 
 ## Runtime composition
 
-`src/main.<%= jsxExt %>` → `AppProviders` → `App` (router) → layout → pages.
+```text
+main → AppProviders → App (router) → layout → page → feature panels
+```
 
-Providers are ordered: client state → server cache → UI theme.
+Provider order matters: client store → server cache → UI theme.
 
 ## Boundaries
 
-- **UI** should call HTTP through `services/`.
-- **Schemas** live in `lib/validation`.
-- **Env access** stays in `config/`, `services/`, and `lib/monitoring`.
+<% if (serverState === 'rtk-query') { -%>
+- **HTTP** for remote resources lives in RTK Query APIs (`src/store/*Api.<%= ext %>`), not in components.
+- Use `fetchBaseQuery` + `prepareHeaders` for auth, base URL, and shared headers.
+- Do **not** add a parallel Axios/Fetch client unless you have a clear non-RTK integration (uploads to a different host, third-party SDK, etc.).
+<% } else { -%>
+- **UI** should call domain helpers in `src/services/api.<%= ext %>`.
+- **Transport** details (interceptors, tokens, timeouts) stay in `src/services/http/`.
+- Components should not call `axios` / `fetch` directly.
+<% } -%>
+- **Schemas** live in `lib/validation` and are reused by forms and API payloads.
+- **Env access** stays in `config/`, services/store, and `lib/monitoring`.
+- **Client state** holds UI/ephemeral state; **server state** caches remote entities.
+
+## Scaling tips
+
+1. Split large features into `components/`, `hooks/`, and `api/` subfolders inside the feature.
+2. Promote shared types into `src/types/` once two features need them.
+3. Keep route files thin — they compose features, they should not own data logic.
+4. Prefer explicit query keys / endpoint names over anonymous fetch calls.

package/dist/templates/docs/best-practices.md.ejs

@@ -2,9 +2,24 @@
 
 ## Code organization
 
-- Colocate tests next to units or under `tests/` for cross-cutting suites.
+- Colocate feature UI, hooks, and tests under `src/features/<domain>/`.
 - Prefer small modules with clear exports over “utils dump” files.
 - Name features after domains (`billing`, `auth`), not technical junk drawers.
+- Keep route files as composers — they should not own fetching or form schemas.
+
+## HTTP & data
+
+<% if (serverState === 'rtk-query') { -%>
+- Define one API slice per domain (or a carefully shared base API).
+- Use `tagTypes` for cache invalidation instead of manual refetches when possible.
+- Put auth in `prepareHeaders`.
+- Prefer generated hooks in components; avoid dispatching raw endpoint actions unless needed.
+<% } else { -%>
+- Never call `axios` / `fetch` from React components — use `src/services/api.<%= ext %>`.
+- Keep interceptors and error normalization in `src/services/http/`.
+- Pass `AbortSignal` from query libraries into HTTP helpers.
+<% } -%>
+- Treat server cache and client UI state as separate concerns.
 
 ## Linting & formatting
 
@@ -13,16 +28,27 @@
 - Husky + lint-staged formats staged files so diffs stay clean.
 - commitlint enforces Conventional Commits on `git commit`.
 
+**Commit style examples**
+
+```text
+feat(posts): add pagination to posts query
+fix(feedback): surface API validation errors
+chore(deps): bump testing-library
+```
+
 ## Environment variables
 
 - Never commit `.env`.
-- Prefix client-visible vars for your bundler.
+- Prefix client-visible vars for your bundler (`VITE_*`).
 - Validate required env at boot for production deploys.
+- Document every variable in `.env.example` with a one-line purpose.
 
 ## Testing strategy
 
 <% if (unitTesting === 'vitest' || unitTesting === 'jest') { -%>
 - Unit/integration with **<%= stackLabels.unitTesting %>** + Testing Library for components.
+- Prefer `getByRole` / label text over test IDs.
+- Mock network at the domain boundary (`services/api` or RTK endpoints), not inside random UI helpers.
 <% } else if (unitTesting === 'rtl') { -%>
 - React Testing Library is installed — pair it with a runner of your choice.
 <% } else { -%>
@@ -30,19 +56,27 @@
 <% } -%>
 <% if (e2eTesting !== 'none') { -%>
 - E2E with **<%= stackLabels.e2eTesting %>** for critical user journeys (load home, submit form).
+- Keep e2e thin: happy paths + one failure path per critical flow.
 <% } -%>
 <% if (visualTesting === 'storybook') { -%>
 - Storybook for isolated UI development and visual review.
+- Write stories for states (loading, empty, error, success), not only the happy path.
 <% } else if (visualTesting === 'chromatic') { -%>
 - Chromatic for visual regression against baselines.
 <% } -%>
 
 Aim for: fast unit tests on logic, fewer integration tests on features, thin e2e on happy paths.
 
+## Accessibility
+
+- Prefer semantic HTML (`button`, `label`, `nav`) before ARIA.
+- Ensure keyboard focus order matches visual order.
+- Pair every input with a visible label; surface errors with `aria-live` / `role="status"` where appropriate.
+
 ## Deployment notes
 
 1. `<%= packageManager === 'npm' ? 'npm run' : packageManager %> build`
-2. Serve `dist/` (or your bundler's output) behind HTTPS.
+2. Serve the bundler output (`dist/` / `build/`) behind HTTPS.
 3. Configure SPA fallback to `index.html` for client routes.
 4. Inject production env vars in the host (Vercel, Netlify, Cloudflare, nginx, etc.).
 5. Enable error tracking DSN in production only.
@@ -54,3 +88,5 @@ Aim for: fast unit tests on logic, fewer integration tests on features, thin e2e
 - [ ] Bundle analyzed for accidental secrets
 - [ ] Monitoring verified with a test event
 - [ ] Accessibility pass on primary flows
+- [ ] Error states designed for `/posts` and `/feedback`
+- [ ] Auth expiry path handled (401 → re-login / token refresh)

package/dist/templates/docs/examples/README.md.ejs

@@ -1,14 +1,14 @@
 # Examples index
 
-Each file documents a concern wired into this scaffold:
+Each guide below explains **how to use** the wired library, **community best practices**, and **copy-paste examples** that match this project's folder layout.
 
-| File | Topic |
-|------|-------|
-| `state.md` | Client state patterns |
-| `data-fetching.md` | Server state / caching |
-| `forms.md` | Forms + validation |
-| `styling.md` | Visual system |
-| `api.md` | HTTP layer |
-| `testing.md` | Unit / E2E / visual |
+| File | Topic | Live route |
+|------|-------|------------|
+| `state.md` | Client state patterns | `/counter` |
+| `data-fetching.md` | Server state / caching | `/posts` |
+| `forms.md` | Forms + validation | `/feedback` |
+| `styling.md` | Visual system | all pages |
+| `api.md` | HTTP layer | used by posts/feedback |
+| `testing.md` | Unit / E2E / visual | `tests/` |
 
-Open the home page to see live counterparts of these examples.
+Start with the live route, then read the matching doc while you extend the feature.