create-react-starter-kit 1.0.6 → 1.0.7

package/dist/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/dist/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`

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

@@ -3,16 +3,76 @@
 **Forms:** <%= stackLabels.forms %>
 **Validation:** <%= stackLabels.validation %>
 
-**Live demo:** Feedback form on `/`
+**Live demo:** `/feedback` → `src/features/feedback/FeedbackForm.<%= jsxExt %>`
+**Schemas:** `src/lib/validation.<%= ext %>`
 
 ## When to use
 
-Multi-field input with client-side rules and async submit.
+Multi-field input with client-side rules and async submit:
 
-## Best practice
+- contact / feedback forms
+- settings screens
+- multi-step wizards (add a stepper on top of the same schema)
 
-Define schemas once in `src/lib/validation.<%= ext %>` and reuse across UI and API boundaries.
+## How to use in this project
 
-## Snippet
+1. Define the schema once in `src/lib/validation.<%= ext %>`.
+2. Bind inputs with <%= stackLabels.forms %>.
+3. On submit, call the API layer:
+<% if (serverState === 'rtk-query') { -%>
+   - RTK mutation: `useCreateFeedbackMutation()` → `.unwrap()`
+<% } else { -%>
+   - `createFeedback()` from `@/services/api`
+<% } -%>
+4. Show success with `role="status"` and reset the form.
 
-See `src/features/feedback/FeedbackForm.<%= jsxExt %>`.
+<% if (forms === 'react-hook-form') { -%>
+### React Hook Form pattern
+
+```tsx
+const {
+  register,
+  handleSubmit,
+  formState: { errors, isSubmitting },
+} = useForm({
+  defaultValues,
+  resolver: zodResolver(feedbackSchema), // when using Zod
+});
+
+const onSubmit = handleSubmit(async (values) => {
+  await createFeedback(values);
+});
+```
+<% } else if (forms === 'formik') { -%>
+### Formik pattern
+
+Use `<Formik>` + `<Field>` and pass a Yup schema via `validationSchema` when selected.
+<% } else if (forms === 'tanstack-form') { -%>
+### TanStack Form pattern
+
+Create the form with `useForm`, validate with your schema inside `onSubmit`, and bind each field through `form.Field`.
+<% } else { -%>
+### Native form pattern
+
+Keep values in `useState`, run the schema/validator on submit, then call the API helper.
+<% } -%>
+
+## Best practices
+
+- **Single source of truth for rules** — schemas in `src/lib`, not duplicated `if` checks in JSX.
+- Validate **on submit** first; add on-blur validation when users need earlier feedback.
+- Map API validation errors (422) back onto fields when the backend returns field paths.
+- Disable the submit button while `isSubmitting` to prevent double posts.
+- Keep forms accessible: real `<label>`, `aria-invalid`, and visible error text.
+- Do not store form drafts in global client state unless the draft must survive across routes.
+
+## Testing tips
+
+- Assert validation messages for empty submit.
+- Mock the network boundary (API helper or RTK mutation) and assert the success status region.
+- Prefer `userEvent` over `fireEvent` for realistic typing.
+
+## Related
+
+- HTTP / RTK details: `docs/examples/api.md`
+- Live UI: `/feedback`

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

@@ -2,16 +2,60 @@
 
 **Library:** <%= stackLabels.stateManagement %>
 
-**Live demo:** Counter panel on `/`
+**Live demo:** `/counter` → `src/features/counter/CounterPanel.<%= jsxExt %>`
+**Store wiring:** `src/store/`
 
 ## When to use
 
-Shared interactive state that is not fetched from an API (wizard steps, UI toggles, local counters).
+Shared interactive state that is **not** fetched from an API:
 
-## Best practice
+- wizard steps, UI toggles, selected tabs
+- ephemeral counters / filters that reset often
+- cross-route UI that should survive navigation but not a full reload
 
-Keep stores/slices focused. Prefer feature-local state; promote to global only when multiple distant trees need it.
+If the data comes from your backend, prefer **<%= stackLabels.serverState %>** instead.
 
-## Snippet
+## How to use in this project
 
-See `src/features/counter/CounterPanel.<%= jsxExt %>` and `src/store/`.
+<% if (stateManagement === 'redux') { -%>
+1. Counter slice lives in `src/store/index.<%= ext %>` (`counterSlice` + `store`).
+2. Read/write with `useSelector` / `useDispatch` from the feature panel (or add typed hooks later).
+
+```tsx
+import { useDispatch, useSelector } from 'react-redux';
+import { increment, type RootState } from '@/store';
+
+const value = useSelector((s: RootState) => s.counter.value);
+const dispatch = useDispatch();
+dispatch(increment());
+```
+<% } else if (stateManagement === 'zustand') { -%>
+Create/consume the store from `src/store/index.<%= ext %>` with selectors so components only re-render on the slices they need.
+
+```tsx
+import { useCounterStore } from '@/store';
+
+const value = useCounterStore((s) => s.value);
+const increment = useCounterStore((s) => s.increment);
+```
+<% } else if (stateManagement === 'jotai') { -%>
+Define atoms in `src/store/index.<%= ext %>` and compose them. Wrap the tree with `Provider` (already done in `providers.<%= jsxExt %>`).
+<% } else if (stateManagement === 'context') { -%>
+Use the provided context + reducer pattern in `src/store/context`. Keep the context value stable; expose actions through a custom hook.
+<% } else { -%>
+No global client-state library was selected. Prefer React local state until multiple distant trees need the same data.
+<% } -%>
+
+## Best practices
+
+- **Feature-local first.** Promote to global only when props drilling becomes painful across routes.
+- **One concern per store/slice.** Avoid a single “appState” blob.
+- **Do not mirror server entities** in client state when you already use <%= stackLabels.serverState %>.
+- Prefer selectors/hooks over reading the entire store in leaf components.
+- Keep side effects (HTTP, analytics) out of reducers; trigger them from thunks/listeners/components.
+
+## Common pitfalls
+
+- Putting API responses into Redux/Zustand “because we might need them later”
+- Updating global state on every keystroke in a form (forms belong to <%= stackLabels.forms %>)
+- Forgetting to reset ephemeral UI state when leaving a flow

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

@@ -5,19 +5,67 @@
 
 ## When to use
 
-Establish design tokens early; use a component library for complex accessible primitives.
+Establish design tokens early; use a component library for complex accessible primitives (dialogs, menus, focus traps).
 
-## Best practice
+## How to use in this project
+
+| Piece | Location |
+|-------|----------|
+| Global styles / tokens | `src/styles/global.<%= styling === 'sass' && uiLibrary !== 'shadcn' ? 'scss' : 'css' %>` |
+| Button adapter | `src/components/ui/UiButton.<%= jsxExt %>` |
+| Layout chrome | `src/components/layout/` |
+
+<% if (styling === 'tailwind') { -%>
+### Tailwind
+
+Utility classes are available across the app. Prefer composing utilities in components over one-off CSS files unless the rule is truly global.
+
+```tsx
+<button className="rounded-md bg-slate-900 px-3 py-2 text-white hover:bg-slate-800">
+  Save
+</button>
+```
+
+**Best practices**
+
+- Extract repeated class clusters into small components (`UiButton`) instead of giant `className` strings everywhere.
+- Keep design tokens (colors, spacing) consistent; avoid magic hex values in features.
+<% } else if (styling === 'css-modules') { -%>
+### CSS Modules
+
+Colocate `*.module.css` next to the component. Import the `styles` object and reference `styles.root`.
+<% } else if (styling === 'styled-components') { -%>
+### Styled Components
+
+Create styled primitives next to the component. Prefer transient props (`$active`) so DOM attributes stay clean.
+<% } else { -%>
+### Sass/SCSS
+
+Shared variables/mixins belong under `src/styles/`. Feature-specific partials can live next to the feature.
+<% } -%>
 
 <% if (uiLibrary === 'shadcn') { -%>
-Treat shadcn-style primitives as owned source — customize freely, keep `cn()` helpers consistent.
+## shadcn/ui notes
+
+Treat shadcn-style primitives as **owned source** — customize freely, keep `cn()` helpers consistent, and avoid patching node_modules.
 <% } else if (uiLibrary === 'none') { -%>
-Invest in a small set of shared primitives (`UiButton`, layout) before adding a full kit.
+## No UI kit
+
+Invest in a small set of shared primitives (`UiButton`, layout) before adding a full kit. This keeps accessibility and spacing consistent.
 <% } else { -%>
-Wrap third-party components in thin adapters (`UiButton`) so swapping kits later is cheaper.
+## <%= stackLabels.uiLibrary %> notes
+
+Wrap third-party components in thin adapters (`UiButton`) so swapping kits later is cheaper and theme overrides stay centralized (see `providers.<%= jsxExt %>`).
 <% } -%>
 
-## Snippet
+## Best practices
+
+- One visual language: spacing, type scale, and radius should feel intentional.
+- Prefer composition over deep CSS specificity wars.
+- Ensure focus states are visible for keyboard users.
+- Keep marketing/landing flair out of app chrome unless product requires it.
+
+## Related
 
-Global styles: `src/styles/global.<%= styling === 'sass' && uiLibrary !== 'shadcn' ? 'scss' : 'css' %>`
-Button adapter: `src/components/ui/UiButton.<%= jsxExt %>`
+- Architecture: `docs/architecture.md`
+- Accessibility checklist: `docs/best-practices.md`

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

@@ -8,20 +8,74 @@
 
 ## When to use
 
-- Unit: pure logic + component behavior
-- E2E: critical journeys across routes
-- Visual: regressions in UI appearance
+| Layer | Use for | Avoid using for |
+|-------|---------|-----------------|
+| Unit / RTL | logic, component behavior, form validation | full auth/payment journeys |
+| E2E | critical user journeys across routes | asserting every CSS class |
+| Visual | regressions in appearance / states | business-rule correctness |
 
-## Best practice
+## How to run
 
-Keep e2e thin. Prefer Testing Library queries that reflect how users find elements (`getByRole`, labels).
+<% if (unitTesting !== 'none') { -%>
+```bash
+<%= packageManager === 'npm' ? 'npm run' : packageManager %> test
+<%= packageManager === 'npm' ? 'npm run' : packageManager %> test:watch
+```
+<% } -%>
+<% if (e2eTesting === 'playwright') { -%>
+```bash
+<%= packageManager === 'npm' ? 'npm run' : packageManager %> test:e2e:install   # once
+<%= packageManager === 'npm' ? 'npm run' : packageManager %> test:e2e
+<%= packageManager === 'npm' ? 'npm run' : packageManager %> test:e2e:ui
+```
 
-## Locations
+E2E base URL: `http://127.0.0.1:<%= buildTool === 'webpack' ? 3000 : 5173 %>`
+<% } else if (e2eTesting === 'cypress') { -%>
+```bash
+<%= packageManager === 'npm' ? 'npm run' : packageManager %> test:e2e
+```
+<% } -%>
+<% if (visualTesting === 'storybook') { -%>
+```bash
+<%= packageManager === 'npm' ? 'npm run' : packageManager %> storybook
+```
+<% } -%>
+
+## Project layout
 
 - Setup: `tests/setup.<%= ext %>` (when applicable)
-- Component smoke: `tests/App.test.<%= jsxExt %>`
+- Unit suites: `tests/*.test.<%= jsxExt %>`
 <% if (e2eTesting === 'playwright') { -%>
-- E2E: `tests/e2e/home.spec.<%= ext %>`
+- E2E: `tests/e2e/*.spec.<%= ext %>` (excluded from unit runner)
 <% } else if (e2eTesting === 'cypress') { -%>
-- E2E: `cypress/e2e/home.cy.<%= ext %>`
+- E2E: `cypress/e2e/*`
+<% } -%>
+<% if (visualTesting === 'storybook') { -%>
+- Stories: `src/**/*.stories.<%= jsxExt %>`
 <% } -%>
+
+## Best practices
+
+- Query the way users do: `getByRole`, label text, placeholder — not implementation details.
+- Mock at the **network/domain boundary**:
+<% if (serverState === 'rtk-query') { -%>
+  - mock RTK hooks/endpoints for unit tests when you are not integration-testing the store
+<% } else { -%>
+  - mock `@/services/api` helpers rather than axios/fetch internals
+<% } -%>
+- Keep e2e **thin**: home load, posts happy path, feedback submit.
+- Do not let unit tests import Playwright specs (unit config excludes `tests/e2e`).
+- For async UI, prefer `findBy*` / `waitFor` over arbitrary `sleep`.
+
+## Example unit test shape
+
+```tsx
+renderWithProviders(<FeedbackForm />);
+await user.click(screen.getByRole('button', { name: /Send feedback/i }));
+expect(screen.getAllByText(/required|valid email/i).length).toBeGreaterThan(0);
+```
+
+## Related
+
+- Strategy & CI: `docs/best-practices.md`
+- Forms guide: `docs/examples/forms.md`