create-react-starter-kit 1.0.5 → 1.0.7

package/templates/__when_unitTesting_jest__/jest.config.json.ejs

@@ -4,6 +4,14 @@
 <% } -%>
   "testEnvironment": "jsdom",
   "setupFilesAfterEnv": ["<rootDir>/tests/setup.<%= ext %>"],
+  "testMatch": ["**/tests/**/*.test.[jt]s?(x)"],
+  "testPathIgnorePatterns": [
+    "/node_modules/",
+    "/dist/",
+    "/build/",
+    "/tests/e2e/",
+    "/e2e/"
+  ],
   "moduleNameMapper": {
     "^@/(.*)$": "<rootDir>/src/$1",
     "\\\\.(css|scss)$": "<rootDir>/tests/styleMock.<%= ext %>"

package/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/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/templates/__when_unitTesting_vitest__/vitest.config.ts.ejs

@@ -0,0 +1,31 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vitest/config';
+
+const rootDir = path.dirname(fileURLToPath(import.meta.url));
+
+// Standalone Vitest config for non-Vite build tools (Webpack, Parcel, etc.).
+// Vite projects configure Vitest inside vite.config instead.
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': path.resolve(rootDir, 'src'),
+    },
+  },
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: './tests/setup.<%= ext %>',
+    include: ['tests/**/*.{test,spec}.{<%= isTypeScript ? 'ts,tsx' : 'js,jsx' %>}'],
+    exclude: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/build/**',
+      '**/tests/e2e/**',
+      '**/e2e/**',
+      '**/*.e2e.*',
+    ],
+  },
+});

package/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/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/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.

package/templates/docs/examples/api.md.ejs

@@ -2,16 +2,173 @@
 
 **Choice:** <%= stackLabels.apiLayer %>
 
-## When to use
+<% if (apiLayer === 'none') { -%>
+## Why there is no Axios/Fetch client
 
-All HTTP traffic should go through a single module for base URL, headers, and error logging.
+You selected **RTK Query**, which already provides:
 
-## Best practice
+- a shared base query (`fetchBaseQuery`)
+- caching, deduplication, and generated hooks
+- a single place for headers via `prepareHeaders`
 
-- Type responses at the boundary.
-- Surface user-friendly errors in UI; log technical details to monitoring.
-- Do not scatter `fetch`/`axios` calls across components.
+Adding Axios/Fetch beside RTK Query usually creates **two HTTP stacks**, duplicated auth logic, and inconsistent error handling.
 
-## Snippet
+**Where HTTP lives:** `src/store/postsApi.<%= ext %>`
 
-`src/services/api.<%= ext %>` — `apiGet`, `apiPost`, `fetchPosts`, `createFeedback`.
+### Extending RTK Query
+
+```ts
+// add to endpoints
+getPostById: builder.query({
+  query: (id) => `/posts/${id}`,
+  providesTags: (_result, _error, id) => [{ type: 'Posts', id }],
+}),
+```
+
+### Auth header pattern
+
+```ts
+prepareHeaders: (headers) => {
+  const token = localStorage.getItem('access_token');
+  if (token) headers.set('Authorization', `Bearer ${token}`);
+  return headers;
+},
+```
+
+### When you might still add Axios/Fetch later
+
+- Uploading to a third-party host that RTK should not cache
+- Streaming / non-JSON APIs
+- A legacy SDK that must use its own client
+
+If that happens, isolate it under `src/services/` and keep RTK as the default for app REST resources.
+
+See `docs/examples/data-fetching.md` for UI usage.
+<% } else if (apiLayer === 'axios') { -%>
+## Layout
+
+```text
+src/services/
+  http/
+    client.<%= ext %>   # axios instance + interceptors
+    errors.<%= ext %>   # ApiError normalization
+    index.<%= ext %>    # public exports
+  api.<%= ext %>        # domain methods (fetchPosts, createFeedback)
+```
+
+## How to use
+
+### From a query library
+
+```ts
+import { fetchPosts, createFeedback } from '@/services/api';
+
+// TanStack Query
+queryFn: ({ signal }) => fetchPosts(signal)
+
+// mutation
+await createFeedback({ name, email, message })
+```
+
+### Direct low-level calls (rare)
+
+```ts
+import { apiGet, apiPost, ApiError } from '@/services/http';
+
+try {
+  const post = await apiGet(`/posts/${id}`);
+} catch (error) {
+  if (error instanceof ApiError && error.isUnauthorized) {
+    // redirect to login / refresh token
+  }
+}
+```
+
+## What the Axios setup includes
+
+| Concern | Implementation |
+|---------|----------------|
+| Base URL | `env.apiBaseUrl` |
+| Timeout | 15s |
+| Auth | `Authorization: Bearer <token>` from `localStorage.access_token` |
+| Request tracing | `X-Request-Id` on every request |
+| Errors | Normalized `ApiError` with `status`, `code`, `requestId` |
+| 401 handling | Dispatches `auth:unauthorized` browser event |
+| Verbs | `apiGet` / `apiPost` / `apiPut` / `apiPatch` / `apiDelete` |
+| Cancellation | Pass `{ signal }` from AbortController / query libs |
+
+## Best practices
+
+- **Components never import axios.** Use domain helpers or at least `@/services/http`.
+- Keep token reads inside the HTTP layer (`getAccessToken`), not in every feature.
+- Listen once for `auth:unauthorized` near the app shell to centralize logout/redirect.
+- Type responses at the boundary (`apiGet<Post[]>`).
+- Log technical details; show user-friendly messages in UI.
+- Prefer adding methods to `api.<%= ext %>` over spreading URLs across features.
+
+## Extending with a refresh-token flow
+
+1. Detect `ApiError.isUnauthorized` in the response interceptor.
+2. Queue in-flight requests while refreshing.
+3. Retry the original request with the new access token.
+4. Fail the queue and redirect if refresh fails.
+
+Keep that logic in `http/client.<%= ext %>` so features stay unaware.
+
+## Example: add a new domain method
+
+```ts
+// src/services/api.ts
+export async function fetchPost(id: number, signal?: AbortSignal) {
+  return apiGet<Post>(`/posts/${id}`, { signal });
+}
+```
+<% } else { -%>
+## Layout
+
+```text
+src/services/
+  http/
+    client.<%= ext %>   # fetch wrapper + timeout/auth/errors
+    errors.<%= ext %>   # ApiError normalization
+    index.<%= ext %>
+  api.<%= ext %>        # domain methods
+```
+
+## How to use
+
+```ts
+import { fetchPosts, createFeedback } from '@/services/api';
+import { apiGet, ApiError } from '@/services/http';
+
+await fetchPosts(signal);
+await createFeedback(payload);
+
+try {
+  await apiGet('/posts/1');
+} catch (error) {
+  if (error instanceof ApiError && error.isRetryable) {
+    // show retry UI
+  }
+}
+```
+
+## What the Fetch setup includes
+
+| Concern | Implementation |
+|---------|----------------|
+| Base URL | `env.apiBaseUrl` |
+| Timeout | AbortController (15s default) |
+| Auth | Bearer token from `localStorage.access_token` |
+| Request tracing | `X-Request-Id` |
+| Errors | Normalized `ApiError` |
+| 401 handling | `auth:unauthorized` event |
+| Verbs | get/post/put/patch/delete helpers |
+
+## Best practices
+
+- Prefer domain helpers over raw `request()` in components.
+- Pass `signal` from TanStack Query / user cancellation.
+- Keep JSON as the default; use `rawBody: true` for `FormData` uploads.
+- Centralize auth and error mapping — do not re-implement per feature.
+<% } -%>

package/templates/docs/examples/data-fetching.md.ejs

@@ -1,18 +1,119 @@
 # Data fetching example
 
 **Library:** <%= stackLabels.serverState %>
+<% if (apiLayer !== 'none') { -%>
 **Transport:** <%= stackLabels.apiLayer %>
+<% } else { -%>
+**Transport:** RTK Query `fetchBaseQuery` (no separate Axios/Fetch client)
+<% } -%>
 
-**Live demo:** Posts panel on `/`
+**Live demo:** `/posts` → `src/features/posts/PostsPanel.<%= jsxExt %>`
 
 ## When to use
 
-Any remote read/write that benefits from caching, deduplication, retries, or background refresh.
+Any remote read/write that benefits from caching, deduplication, retries, or background refresh:
 
-## Best practice
+- lists and detail pages
+- polling dashboards
+- mutations that should refresh related queries
 
-Separate server cache from client UI state. Key queries by resource identity, not by component instance.
+## How to use in this project
 
-## Snippet
+<% if (serverState === 'rtk-query') { -%>
+### 1. Define endpoints
 
-See `src/features/posts/PostsPanel.<%= jsxExt %>` and `src/services/api.<%= ext %>`.
+See `src/store/postsApi.<%= ext %>`:
+
+```ts
+export const postsApi = createApi({
+  reducerPath: 'postsApi',
+  baseQuery: fetchBaseQuery({
+    baseUrl: env.apiBaseUrl,
+    prepareHeaders: (headers) => {
+      const token = localStorage.getItem('access_token');
+      if (token) headers.set('Authorization', `Bearer ${token}`);
+      return headers;
+    },
+  }),
+  tagTypes: ['Posts'],
+  endpoints: (builder) => ({
+    getPosts: builder.query({
+      query: () => '/posts?_limit=5',
+      providesTags: ['Posts'],
+    }),
+    createFeedback: builder.mutation({
+      query: (body) => ({ url: '/posts', method: 'POST', body }),
+      invalidatesTags: ['Posts'],
+    }),
+  }),
+});
+```
+
+### 2. Consume hooks in UI
+
+```tsx
+const { data, isLoading, error, refetch, isFetching } = useGetPostsQuery();
+const [createFeedback] = useCreateFeedbackMutation();
+await createFeedback(values).unwrap();
+```
+
+### Best practices (RTK Query)
+
+- Prefer **tags** over manual `refetch()` for coherence after writes.
+- Keep `prepareHeaders` as the single place for auth.
+- Split large APIs with `injectEndpoints` as the app grows.
+- Use `transformResponse` for shaping DTO → UI models at the boundary.
+- Handle errors with `error` from the hook; surface user-friendly messages in UI.
+<% } else if (serverState === 'tanstack-query') { -%>
+### Query example
+
+```tsx
+const { data, isLoading, error, refetch } = useQuery({
+  queryKey: ['posts'],
+  queryFn: ({ signal }) => fetchPosts(signal),
+});
+```
+
+`fetchPosts` lives in `src/services/api.<%= ext %>` and already goes through the shared HTTP client.
+
+### Mutation example
+
+```tsx
+const mutation = useMutation({
+  mutationFn: createFeedback,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['posts'] }),
+});
+```
+
+### Best practices (TanStack Query)
+
+- Hierarchical keys: `['posts']`, `['posts', postId]`, `['users', userId, 'posts']`
+- Always accept/pass `AbortSignal` for cancellable requests
+- Set sensible `staleTime` (already defaulted in `providers.<%= jsxExt %>`)
+- Keep `queryFn` pure: no React state writes inside it
+<% } else if (serverState === 'swr') { -%>
+### Example
+
+```tsx
+const { data, error, isLoading, mutate } = useSWR('/posts?_limit=5');
+```
+
+The shared fetcher in `providers.<%= jsxExt %>` calls `apiGet`.
+
+### Best practices (SWR)
+
+- Use stable keys (URL or serialized params)
+- Call `mutate` after writes to revalidate
+- Prefer the global fetcher; override per-hook only when necessary
+<% } else { -%>
+Manual fetching is used in the posts panel. As soon as you add caching needs, introduce TanStack Query, SWR, or RTK Query.
+<% } -%>
+
+## Best practice (all libraries)
+
+Separate **server cache** from **client UI state**. Key queries by resource identity, not by component instance.
+
+## Related docs
+
+- HTTP transport details: `docs/examples/api.md`
+- Architecture boundaries: `docs/architecture.md`