create-react-starter-kit 1.0.6 → 1.0.7

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 {};
+<% } -%>

package/dist/templates/src/services/api.ts.ejs

@@ -1,84 +0,0 @@
-<% if (apiLayer === 'axios') { -%>
-import axios from 'axios';
-import { env } from '@/config/env';
-
-const baseURL = env.apiBaseUrl;
-
-export const apiClient = axios.create({
-  baseURL,
-  headers: { 'Content-Type': 'application/json' },
-  timeout: 10_000,
-});
-
-apiClient.interceptors.response.use(
-  (response) => response,
-  (error) => {
-    console.error('[api]', error);
-    return Promise.reject(error);
-  },
-);
-
-export async function apiGet<% if (isTypeScript) { %><T = unknown><% } %>(path<% if (isTypeScript) { %>: string<% } %>)<% if (isTypeScript) { %>: Promise<T><% } %> {
-  const { data } = await apiClient.get<% if (isTypeScript) { %><T><% } %>(path);
-  return data;
-}
-
-export async function apiPost<% if (isTypeScript) { %><T = unknown, B = unknown><% } %>(
-  path<% if (isTypeScript) { %>: string<% } %>,
-  body<% if (isTypeScript) { %>: B<% } %>,
-)<% if (isTypeScript) { %>: Promise<T><% } %> {
-  const { data } = await apiClient.post<% if (isTypeScript) { %><T><% } %>(path, body);
-  return data;
-}
-<% } else { -%>
-import { env } from '@/config/env';
-
-const baseURL = env.apiBaseUrl;
-
-async function request<% if (isTypeScript) { %><T = unknown><% } %>(
-  path<% if (isTypeScript) { %>: string<% } %>,
-  init<% if (isTypeScript) { %>?: RequestInit<% } %>,
-)<% if (isTypeScript) { %>: Promise<T><% } %> {
-  const response = await fetch(`${baseURL}${path}`, {
-    headers: { 'Content-Type': 'application/json', ...(init?.headers ?? {}) },
-    ...init,
-  });
-
-  if (!response.ok) {
-    throw new Error(`Request failed: ${response.status}`);
-  }
-
-  return response.json();
-}
-
-export async function apiGet<% if (isTypeScript) { %><T = unknown><% } %>(path<% if (isTypeScript) { %>: string<% } %>)<% if (isTypeScript) { %>: Promise<T><% } %> {
-  return request<% if (isTypeScript) { %><T><% } %>(path);
-}
-
-export async function apiPost<% if (isTypeScript) { %><T = unknown, B = unknown><% } %>(
-  path<% if (isTypeScript) { %>: string<% } %>,
-  body<% if (isTypeScript) { %>: B<% } %>,
-)<% if (isTypeScript) { %>: Promise<T><% } %> {
-  return request<% if (isTypeScript) { %><T><% } %>(path, {
-    method: 'POST',
-    body: JSON.stringify(body),
-  });
-}
-<% } -%>
-
-<% if (isTypeScript) { -%>
-export interface Post {
-  userId: number;
-  id: number;
-  title: string;
-  body: string;
-}
-<% } -%>
-
-export async function fetchPosts() {
-  return apiGet<% if (isTypeScript) { %><Post[]><% } %>('/posts?_limit=5');
-}
-
-export async function createFeedback(payload<% if (isTypeScript) { %>: { name: string; email: string; message: string }<% } %>) {
-  return apiPost('/posts', payload);
-}

package/templates/src/services/api.ts.ejs

@@ -1,84 +0,0 @@
-<% if (apiLayer === 'axios') { -%>
-import axios from 'axios';
-import { env } from '@/config/env';
-
-const baseURL = env.apiBaseUrl;
-
-export const apiClient = axios.create({
-  baseURL,
-  headers: { 'Content-Type': 'application/json' },
-  timeout: 10_000,
-});
-
-apiClient.interceptors.response.use(
-  (response) => response,
-  (error) => {
-    console.error('[api]', error);
-    return Promise.reject(error);
-  },
-);
-
-export async function apiGet<% if (isTypeScript) { %><T = unknown><% } %>(path<% if (isTypeScript) { %>: string<% } %>)<% if (isTypeScript) { %>: Promise<T><% } %> {
-  const { data } = await apiClient.get<% if (isTypeScript) { %><T><% } %>(path);
-  return data;
-}
-
-export async function apiPost<% if (isTypeScript) { %><T = unknown, B = unknown><% } %>(
-  path<% if (isTypeScript) { %>: string<% } %>,
-  body<% if (isTypeScript) { %>: B<% } %>,
-)<% if (isTypeScript) { %>: Promise<T><% } %> {
-  const { data } = await apiClient.post<% if (isTypeScript) { %><T><% } %>(path, body);
-  return data;
-}
-<% } else { -%>
-import { env } from '@/config/env';
-
-const baseURL = env.apiBaseUrl;
-
-async function request<% if (isTypeScript) { %><T = unknown><% } %>(
-  path<% if (isTypeScript) { %>: string<% } %>,
-  init<% if (isTypeScript) { %>?: RequestInit<% } %>,
-)<% if (isTypeScript) { %>: Promise<T><% } %> {
-  const response = await fetch(`${baseURL}${path}`, {
-    headers: { 'Content-Type': 'application/json', ...(init?.headers ?? {}) },
-    ...init,
-  });
-
-  if (!response.ok) {
-    throw new Error(`Request failed: ${response.status}`);
-  }
-
-  return response.json();
-}
-
-export async function apiGet<% if (isTypeScript) { %><T = unknown><% } %>(path<% if (isTypeScript) { %>: string<% } %>)<% if (isTypeScript) { %>: Promise<T><% } %> {
-  return request<% if (isTypeScript) { %><T><% } %>(path);
-}
-
-export async function apiPost<% if (isTypeScript) { %><T = unknown, B = unknown><% } %>(
-  path<% if (isTypeScript) { %>: string<% } %>,
-  body<% if (isTypeScript) { %>: B<% } %>,
-)<% if (isTypeScript) { %>: Promise<T><% } %> {
-  return request<% if (isTypeScript) { %><T><% } %>(path, {
-    method: 'POST',
-    body: JSON.stringify(body),
-  });
-}
-<% } -%>
-
-<% if (isTypeScript) { -%>
-export interface Post {
-  userId: number;
-  id: number;
-  title: string;
-  body: string;
-}
-<% } -%>
-
-export async function fetchPosts() {
-  return apiGet<% if (isTypeScript) { %><Post[]><% } %>('/posts?_limit=5');
-}
-
-export async function createFeedback(payload<% if (isTypeScript) { %>: { name: string; email: string; message: string }<% } %>) {
-  return apiPost('/posts', payload);
-}