create-react-starter-kit 1.0.5 → 1.0.7

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

package/templates/docs/getting-started.md.ejs

@@ -2,10 +2,13 @@
 
 Welcome to **<%= projectName %>**, a React starter generated by `create-react-starter-kit`.
 
+This guide walks you from first install to extending the app with confidence.
+
 ## Prerequisites
 
-- Node.js 18+
-- <%= stackLabels.packageManager %>
+- **Node.js 18+** (20 LTS recommended)
+- **<%= stackLabels.packageManager %>** installed globally or via Corepack
+- A modern browser for the demo UI
 
 ## Install & run
 
@@ -22,26 +25,68 @@ npm run dev
 <% } -%>
 ```
 
+Dev server URL (default): **http://localhost:<%= buildTool === 'webpack' ? 3000 : 5173 %>**
+
+Useful scripts:
+
+| Script | Purpose |
+|--------|---------|
+| `dev` | Local development server |
+| `build` | Production bundle |
+| `preview` | Serve the production build locally |
+<% if (unitTesting !== 'none') { -%>
+| `test` / `test:watch` | Unit tests |
+<% } -%>
+<% if (e2eTesting !== 'none') { -%>
+| `test:e2e` | End-to-end tests |
+<% } -%>
+<% if (visualTesting === 'storybook') { -%>
+| `storybook` | Component explorer |
+<% } -%>
+| `lint` / `format` | Code quality |
+
 ## Environment variables
 
-Copy `.env.example` → `.env` and fill values. Restart the dev server after changes.
+1. Copy `.env.example` → `.env`
+2. Fill values for your environment
+3. Restart `dev` after changes
 
-Only variables prefixed for your bundler (e.g. `VITE_`) are exposed to the browser. Keep secrets on the server.
+Only client-safe variables (typically `VITE_*`) are exposed to the browser. Never put private API keys in front-end env vars.
+
+| Variable | Purpose |
+|----------|---------|
+| `VITE_API_BASE_URL` | REST API base URL (defaults to JSONPlaceholder for demos) |
+<% if (errorTracking === 'sentry') { -%>
+| `VITE_SENTRY_DSN` | Sentry DSN |
+<% } else if (errorTracking === 'bugsnag') { -%>
+| `VITE_BUGSNAG_API_KEY` | Bugsnag API key |
+<% } else if (errorTracking === 'logrocket') { -%>
+| `VITE_LOGROCKET_APP_ID` | LogRocket app id |
+<% } else if (errorTracking === 'datadog') { -%>
+| `VITE_DATADOG_APPLICATION_ID` / `VITE_DATADOG_CLIENT_TOKEN` | Datadog RUM |
+<% } -%>
 
 ## What to explore first
 
-1. Open `/` — demo panels for state, data fetching, and forms.
-2. Open `/about` — orientation for the folder layout.
-3. Read `docs/selected-stack.md` — why each library is present.
-4. Skim `docs/examples/` — focused usage notes per concern.
+1. **`/`** — stack badges and orientation
+2. **`/counter`** — client state (<%= stackLabels.stateManagement %>)
+3. **`/posts`** — server state (<%= stackLabels.serverState %>)
+4. **`/feedback`** — forms + validation (<%= stackLabels.forms %> / <%= stackLabels.validation %>)
+5. **`docs/selected-stack.md`** — why each library was chosen
+6. **`docs/examples/`** — deep usage guides with copy-paste patterns
 
-## Extending the app
+## Extending the app (recommended flow)
 
-- Add a domain under `src/features/<name>/`.
-- Register routes in `src/App.<%= jsxExt %>`.
-- Put shared UI in `src/components/`.
-- Put HTTP clients in `src/services/`.
-- Import with `@/` (maps to `src/`), e.g. `import { env } from '@/config/env'`.
+1. Create a feature folder: `src/features/<domain>/`
+2. Add UI, hooks, and domain types next to that feature
+3. Register a route in `src/App.<%= jsxExt %>`
+4. Put shared primitives in `src/components/`
+<% if (apiLayer === 'none') { -%>
+5. Add RTK Query endpoints in `src/store/` (or a feature-local `*Api` slice)
+<% } else { -%>
+5. Add HTTP helpers in `src/services/api.<%= ext %>` (and keep transport details in `src/services/http/`)
+<% } -%>
+6. Import with `@/` — e.g. `import { env } from '@/config/env'`
 
 ## Testing
 
@@ -51,5 +96,8 @@ Only variables prefixed for your bundler (e.g. `VITE_`) are exposed to the brows
 <% if (e2eTesting !== 'none') { -%>
 - E2E: `<%= packageManager === 'npm' ? 'npm run' : packageManager %> test:e2e`
 <% } -%>
+<% if (visualTesting === 'storybook') { -%>
+- Storybook: `<%= packageManager === 'npm' ? 'npm run' : packageManager %> storybook`
+<% } -%>
 
-See `docs/best-practices.md` for CI and production notes.
+See `docs/best-practices.md` and `docs/examples/testing.md` for strategy and CI notes.

package/templates/docs/selected-stack.md.ejs

@@ -1,44 +1,146 @@
 # Selected stack
 
-This document explains each choice made when generating **<%= projectName %>**.
+This document explains each choice made when generating **<%= projectName %>**, how to use it day-to-day, and the practices that keep the codebase maintainable.
 
 ## Build — <%= stackLabels.buildTool %>
 
-Fast local feedback and a production bundle. Prefer keeping config minimal; add plugins only when needed.
+<% if (buildTool === 'vite') { -%>
+Vite gives fast HMR and a Rollup-based production build. Config lives in `vite.config.<%= ext %>`.
 
-**Best practice:** lock Node and package manager versions in CI for reproducible builds.
+**Day-to-day:** `<%= packageManager === 'npm' ? 'npm run' : packageManager %> dev` → http://localhost:5173
+<% } else if (buildTool === 'webpack') { -%>
+Webpack is configured in `webpack.config.js` with Babel (or TS pipeline), HtmlWebpackPlugin, and a dev server.
+
+**Day-to-day:** `<%= packageManager === 'npm' ? 'npm run' : packageManager %> dev` → http://localhost:3000
+<% } else { -%>
+Your bundler is wired with scripts in `package.json`. Prefer keeping config minimal; add plugins only when needed.
+<% } -%>
+
+**Best practices**
+
+- Lock Node and package manager versions in CI.
+- Treat `build` as the source of truth for production issues (not only `dev`).
+- Keep path aliases (`@/`) in sync between TS config and the bundler.
 
 ## Language — <%= stackLabels.language %>
 
 <% if (isTypeScript) { -%>
-TypeScript catches contract mistakes early. Keep `strict` on; avoid `any` except at true boundaries.
+TypeScript catches contract mistakes early. Keep `strict` on; avoid `any` except at true boundaries (third-party quirks, gradual migrations).
+
+**Pattern:** model API payloads in `src/types/models.<%= ext %>`, not inline in components.
 <% } else { -%>
-JavaScript keeps the barrier low. Consider migrating hot modules to TypeScript as the app grows.
+JavaScript keeps the barrier low. Prefer JSDoc for public helpers, and consider migrating hot modules to TypeScript as the app grows.
 <% } -%>
 
 ## Routing — <%= stackLabels.router %>
 
 Client-side navigation with nested layouts. Keep route modules thin; push data loading into features.
 
+**Best practices**
+
+- Colocate route-level UI under `src/routes/`.
+- Avoid fetching in layout components unless every child needs the data.
+- Use loading/error UI at the feature boundary.
+
 ## Client state — <%= stackLabels.stateManagement %>
 
 Use for UI state (modals, wizards, ephemeral counters). Do **not** mirror server entities here if you have a server-state library.
 
+**Live demo:** `/counter` → `src/features/counter/`
+
+**Best practices**
+
+- Feature-local state first; promote to global only when multiple distant trees need it.
+- Keep stores/slices focused on one domain.
+- Prefer selectors/hooks over reading the whole store in components.
+
 ## Server state — <%= stackLabels.serverState %>
 
-Caches remote data, handles loading/error, and deduplicates requests. Example: posts panel on the home page.
+Caches remote data, handles loading/error, and deduplicates requests.
+
+**Live demo:** `/posts` → `src/features/posts/PostsPanel.<%= jsxExt %>`
+
+<% if (serverState === 'rtk-query') { -%>
+**How to use**
+
+1. Define endpoints in `src/store/postsApi.<%= ext %>` (or a new `*Api` slice).
+2. Export hooks (`useGetPostsQuery`, `useCreateFeedbackMutation`).
+3. Call hooks from features — no manual `useEffect` fetching.
+
+**Best practices**
+
+- Use `tagTypes` + `providesTags` / `invalidatesTags` for cache coherence.
+- Put auth headers in `prepareHeaders`, not in every endpoint.
+- Prefer mutations for writes; invalidate related query tags after success.
+<% } else if (serverState === 'tanstack-query') { -%>
+**How to use**
+
+```tsx
+const { data, isLoading, error, refetch } = useQuery({
+  queryKey: ['posts'],
+  queryFn: ({ signal }) => fetchPosts(signal),
+});
+```
+
+**Best practices**
+
+- Stable, hierarchical query keys: `['posts']`, `['posts', id]`.
+- Pass `signal` into your HTTP helpers so navigations cancel in-flight work.
+- Keep `queryFn` thin — call domain API helpers, not raw HTTP.
+<% } else if (serverState === 'swr') { -%>
+**How to use**
+
+SWR is configured in `providers.<%= jsxExt %>` with a shared `fetcher`. Components call `useSWR(key)`.
+
+**Best practices**
+
+- Keys should be URLs or stable resource identifiers.
+- Use `mutate` for local revalidation after writes.
+<% } else { -%>
+No dedicated server-state library was selected. Prefer adding one before the app grows past a few screens.
+<% } -%>
 
 ## Forms — <%= stackLabels.forms %> / Validation — <%= stackLabels.validation %>
 
 Schemas define the contract; the form library binds inputs. Share schemas with API payloads when possible.
 
+**Live demo:** `/feedback` → `src/features/feedback/FeedbackForm.<%= jsxExt %>`
+**Schemas:** `src/lib/validation.<%= ext %>`
+
+**Best practices**
+
+- Validate on submit (and optionally on blur) — avoid blocking every keystroke unless UX requires it.
+- Keep error messages user-facing; log technical details separately.
+- Reuse the same schema on the server if you own both sides.
+
 ## Styling — <%= stackLabels.styling %> / UI — <%= stackLabels.uiLibrary %>
 
 Tokens and primitives establish visual consistency. Prefer composition over one-off CSS.
 
+**Best practices**
+
+- Wrap third-party primitives in thin adapters (`UiButton`) so swapping kits later is cheaper.
+- Keep global tokens in `src/styles/`; keep feature-specific styles close to the feature.
+
 ## API — <%= stackLabels.apiLayer %>
 
-Centralize base URL, headers, and error logging in `src/services/api.<%= ext %>`.
+<% if (apiLayer === 'none') { -%>
+HTTP is owned by **RTK Query** (`fetchBaseQuery`). There is intentionally **no** separate Axios/Fetch client in this project.
+
+See `docs/examples/data-fetching.md` and `src/store/postsApi.<%= ext %>`.
+<% } else if (apiLayer === 'axios') { -%>
+Axios is configured under `src/services/http/` with:
+
+- request interceptors (auth token, request IDs)
+- response interceptors (normalized `ApiError`, 401 event)
+- domain helpers in `src/services/api.<%= ext %>`
+
+See `docs/examples/api.md` for patterns and examples.
+<% } else { -%>
+A shared Fetch wrapper lives under `src/services/http/` with timeout, auth headers, request IDs, and normalized `ApiError`s. Domain helpers sit in `src/services/api.<%= ext %>`.
+
+See `docs/examples/api.md` for patterns and examples.
+<% } -%>
 
 ## Quality gates
 
@@ -52,4 +154,4 @@ Centralize base URL, headers, and error logging in `src/services/api.<%= ext %>`
 | Git hooks | Husky + lint-staged + commitlint |
 | Structure | Feature-based + `@/` aliases |
 
-See `docs/examples/` for focused usage notes.
+See `docs/examples/` for focused usage notes with deeper examples.

package/templates/src/features/feedback/FeedbackForm.tsx.ejs

@@ -32,7 +32,11 @@ import { validateFeedback<% if (isTypeScript) { %>, type FeedbackValues<% } %> }
 import { feedbackSchema<% if (isTypeScript) { %>, type FeedbackValues<% } %> } from '@/lib/validation';
 <% } -%>
 <% } -%>
+<% if (serverState === 'rtk-query') { -%>
+import { useCreateFeedbackMutation } from '@/store/postsApi';
+<% } else { -%>
 import { createFeedback } from '@/services/api';
+<% } -%>
 import { UiButton } from '@/components/ui/UiButton';
 
 const defaults<% if (isTypeScript) { %>: FeedbackValues<% } %> = {
@@ -43,6 +47,12 @@ const defaults<% if (isTypeScript) { %>: FeedbackValues<% } %> = {
 
 export function FeedbackForm() {
   const [status, setStatus] = useState<% if (isTypeScript) { %><string | null><% } %>(null);
+<% if (serverState === 'rtk-query') { -%>
+  const [createFeedbackMutation] = useCreateFeedbackMutation();
+  const createFeedback = async (values<% if (isTypeScript) { %>: FeedbackValues<% } %>) => {
+    await createFeedbackMutation(values).unwrap();
+  };
+<% } -%>
 
 <% if (forms === 'react-hook-form') { -%>
   const {

package/templates/src/features/posts/PostsPanel.tsx.ejs

@@ -14,7 +14,7 @@ export function PostsPanel() {
 <% if (serverState === 'tanstack-query') { -%>
   const { data, isLoading, error, refetch, isFetching } = useQuery({
     queryKey: ['posts'],
-    queryFn: fetchPosts,
+    queryFn: ({ signal }) => fetchPosts(signal),
   });
 <% } else if (serverState === 'swr') { -%>
   const { data, error, isLoading, isValidating, mutate } = useSWR('/posts?_limit=5');

package/templates/src/routes/PostsPage.tsx.ejs

@@ -7,8 +7,13 @@ export function PostsPage() {
         <p className="eyebrow">Server state</p>
         <h1>Posts</h1>
         <p className="lede">
-          Fetches sample posts via <strong><%= stackLabels.serverState === 'None' ? stackLabels.apiLayer : stackLabels.serverState %></strong>{' '}
-          and <strong><%= stackLabels.apiLayer %></strong>.
+          Fetches sample posts via <strong><%= stackLabels.serverState === 'None' ? stackLabels.apiLayer : stackLabels.serverState %></strong>
+<% if (apiLayer !== 'none' && serverState !== 'rtk-query') { -%>
+          {' '}and <strong><%= stackLabels.apiLayer %></strong>
+<% } else if (serverState === 'rtk-query') { -%>
+          {' '}(HTTP via <code>fetchBaseQuery</code>)
+<% } -%>
+          .
         </p>
       </header>
       <PostsPanel />

package/templates/src/types/index.ts.ejs

@@ -1,6 +1,6 @@
 <% if (isTypeScript) { -%>
 /** Shared domain types used across features. */
-export type { Post } from '@/services/api';
+export type { Post, FeedbackPayload } from './models';
 <% } else { -%>
 // Shared types live here when you migrate hot paths to TypeScript.
 export {};

package/templates/src/types/models.ts.ejs

@@ -0,0 +1,18 @@
+<% if (isTypeScript) { -%>
+/** Shared domain models used by features and the HTTP / RTK layers. */
+export interface Post {
+  userId: number;
+  id: number;
+  title: string;
+  body: string;
+}
+
+export interface FeedbackPayload {
+  name: string;
+  email: string;
+  message: string;
+}
+<% } else { -%>
+// Shared domain models live here when you migrate hot paths to TypeScript.
+export {};
+<% } -%>