create-react-starter-kit 1.0.5 → 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_vite__/vite.config.ts.ejs

@@ -28,7 +28,15 @@ export default mergeConfig(
       globals: true,
       environment: 'jsdom',
       setupFiles: './tests/setup.<%= ext %>',
-      exclude: ['**/node_modules/**', '**/dist/**', '**/e2e/**', '**/*.e2e.*'],
+      include: ['tests/**/*.{test,spec}.{<%= isTypeScript ? 'ts,tsx' : 'js,jsx' %>}'],
+      exclude: [
+        '**/node_modules/**',
+        '**/dist/**',
+        '**/build/**',
+        '**/tests/e2e/**',
+        '**/e2e/**',
+        '**/*.e2e.*',
+      ],
     },
   }),
 );

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_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/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/__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/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.