create-react-starter-kit 1.0.0

package/templates/__when_linting_eslint__/eslint.config.js.ejs

@@ -0,0 +1,42 @@
+import js from '@eslint/js';
+import globals from 'globals';
+import react from 'eslint-plugin-react';
+import reactHooks from 'eslint-plugin-react-hooks';
+<% if (isTypeScript) { -%>
+import tseslint from 'typescript-eslint';
+<% } -%>
+<% if (formatting === 'prettier') { -%>
+import prettier from 'eslint-config-prettier';
+<% } -%>
+
+export default [
+  { ignores: ['dist', 'coverage', 'storybook-static'] },
+  js.configs.recommended,
+<% if (isTypeScript) { -%>
+  ...tseslint.configs.recommended,
+<% } -%>
+  {
+    files: ['**/*.{<%= isTypeScript ? 'ts,tsx' : 'js,jsx' %>}'],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+      globals: globals.browser,
+    },
+    plugins: {
+      react,
+      'react-hooks': reactHooks,
+    },
+    settings: {
+      react: { version: 'detect' },
+    },
+    rules: {
+      ...react.configs.recommended.rules,
+      ...reactHooks.configs.recommended.rules,
+      'react/react-in-jsx-scope': 'off',
+      'react/prop-types': 'off',
+    },
+  },
+<% if (formatting === 'prettier') { -%>
+  prettier,
+<% } -%>
+];

package/templates/__when_serverState_rtk-query__/src/store/postsApi.ts.ejs

@@ -0,0 +1,19 @@
+import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';
+<% if (isTypeScript) { -%>
+import type { Post } from '@/services/api';
+<% } -%>
+import { env } from '@/config/env';
+
+const baseUrl = env.apiBaseUrl;
+
+export const postsApi = createApi({
+  reducerPath: 'postsApi',
+  baseQuery: fetchBaseQuery({ baseUrl }),
+  endpoints: (builder) => ({
+    getPosts: builder.query<% if (isTypeScript) { %><Post[], void><% } %>({
+      query: () => '/posts?_limit=5',
+    }),
+  }),
+});
+
+export const { useGetPostsQuery } = postsApi;

package/templates/__when_stateManagement_context__/src/store/context.tsx.ejs

@@ -0,0 +1,57 @@
+import {
+  createContext,
+  useContext,
+  useMemo,
+  useReducer,
+<% if (isTypeScript) { -%>
+  type ReactNode,
+  type Dispatch,
+<% } -%>
+} from 'react';
+
+<% if (isTypeScript) { -%>
+interface State {
+  value: number;
+}
+
+type Action =
+  | { type: 'increment' }
+  | { type: 'decrement' }
+  | { type: 'set'; payload: number };
+
+interface AppStateContextValue {
+  state: State;
+  dispatch: Dispatch<Action>;
+}
+<% } -%>
+
+const initialState<% if (isTypeScript) { %>: State<% } %> = { value: 0 };
+
+function reducer(state<% if (isTypeScript) { %>: State<% } %>, action<% if (isTypeScript) { %>: Action<% } %>)<% if (isTypeScript) { %>: State<% } %> {
+  switch (action.type) {
+    case 'increment':
+      return { value: state.value + 1 };
+    case 'decrement':
+      return { value: state.value - 1 };
+    case 'set':
+      return { value: action.payload };
+    default:
+      return state;
+  }
+}
+
+const AppStateContext = createContext<% if (isTypeScript) { %><AppStateContextValue | null><% } %>(null);
+
+export function AppStateProvider({ children }<% if (isTypeScript) { %>: { children: ReactNode }<% } %>) {
+  const [state, dispatch] = useReducer(reducer, initialState);
+  const value = useMemo(() => ({ state, dispatch }), [state]);
+  return <AppStateContext.Provider value={value}>{children}</AppStateContext.Provider>;
+}
+
+export function useAppState() {
+  const ctx = useContext(AppStateContext);
+  if (!ctx) {
+    throw new Error('useAppState must be used within AppStateProvider');
+  }
+  return ctx;
+}

package/templates/__when_styling_tailwind__/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/templates/__when_styling_tailwind__/tailwind.config.js.ejs

@@ -0,0 +1,23 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: ['./index.html', './src/**/*.{<%= isTypeScript ? 'js,ts,jsx,tsx' : 'js,jsx' %>}'],
+  theme: {
+    extend: {
+      colors: {
+        brand: {
+          50: '#f0f7ff',
+          100: '#dceeff',
+          500: '#2563eb',
+          600: '#1d4ed8',
+          700: '#1e40af',
+          900: '#0f172a',
+        },
+      },
+      fontFamily: {
+        display: ['"DM Sans"', 'system-ui', 'sans-serif'],
+        body: ['"IBM Plex Sans"', 'system-ui', 'sans-serif'],
+      },
+    },
+  },
+  plugins: [],
+};

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

@@ -0,0 +1,11 @@
+{
+<% if (isTypeScript) { -%>
+  "preset": "ts-jest",
+<% } -%>
+  "testEnvironment": "jsdom",
+  "setupFilesAfterEnv": ["<rootDir>/tests/setup.<%= ext %>"],
+  "moduleNameMapper": {
+    "^@/(.*)$": "<rootDir>/src/$1",
+    "\\\\.(css|scss)$": "<rootDir>/tests/styleMock.<%= ext %>"
+  }
+}

package/templates/__when_unitTesting_jest__/tests/App.test.tsx.ejs

@@ -0,0 +1,13 @@
+import { render, screen } from '@testing-library/react';
+import { AppProviders } from '@/app/providers';
+import { HomePage } from '@/routes/HomePage';
+
+test('renders the project hero', () => {
+  render(
+    <AppProviders>
+      <HomePage />
+    </AppProviders>,
+  );
+
+  expect(screen.getByRole('heading', { name: /<%= projectName %>/i })).toBeInTheDocument();
+});

package/templates/__when_unitTesting_jest__/tests/setup.ts.ejs

@@ -0,0 +1 @@
+import '@testing-library/jest-dom';

package/templates/__when_unitTesting_jest__/tests/styleMock.ts.ejs

@@ -0,0 +1 @@
+export default {};

package/templates/__when_unitTesting_rtl__/tests/App.test.tsx.ejs

@@ -0,0 +1,13 @@
+import { render, screen } from '@testing-library/react';
+import { AppProviders } from '@/app/providers';
+import { HomePage } from '@/routes/HomePage';
+
+test('renders the project hero', () => {
+  render(
+    <AppProviders>
+      <HomePage />
+    </AppProviders>,
+  );
+
+  expect(screen.getByRole('heading', { name: /<%= projectName %>/i })).toBeInTheDocument();
+});

package/templates/__when_unitTesting_vitest__/tests/App.test.tsx.ejs

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { AppProviders } from '@/app/providers';
+import { HomePage } from '@/routes/HomePage';
+
+describe('HomePage', () => {
+  it('renders the project hero', () => {
+    render(
+      <AppProviders>
+        <HomePage />
+      </AppProviders>,
+    );
+
+    expect(screen.getByRole('heading', { name: /<%= projectName %>/i })).toBeInTheDocument();
+  });
+});

package/templates/__when_unitTesting_vitest__/tests/setup.ts.ejs

@@ -0,0 +1 @@
+import '@testing-library/jest-dom';

package/templates/__when_visualTesting_storybook__/.storybook/main.js.ejs

@@ -0,0 +1,11 @@
+/** @type { import('@storybook/<%= buildTool === 'vite' || buildTool === 'esbuild' ? 'react-vite' : 'react-webpack5' %>').StorybookConfig } */
+const config = {
+  stories: ['../src/**/*.stories.@(<%= isTypeScript ? 'ts|tsx' : 'js|jsx' %>)'],
+  addons: [],
+  framework: {
+    name: '@storybook/<%= buildTool === 'vite' || buildTool === 'esbuild' ? 'react-vite' : 'react-webpack5' %>',
+    options: {},
+  },
+};
+
+export default config;

package/templates/__when_visualTesting_storybook__/.storybook/preview.js

@@ -0,0 +1,8 @@
+/** @type { import('@storybook/react').Preview } */
+const preview = {
+  parameters: {
+    controls: { matchers: { color: /(background|color)$/i, date: /Date$/i } },
+  },
+};
+
+export default preview;

package/templates/__when_visualTesting_storybook__/src/components/ui/UiButton.stories.tsx.ejs

@@ -0,0 +1,15 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { UiButton } from '@/components/ui/UiButton';
+
+const meta = {
+  title: 'UI/UiButton',
+  component: UiButton,
+  args: {
+    children: 'Click me',
+  },
+} satisfies Meta<typeof UiButton>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Primary: Story = {};

package/templates/commitlint.config.js

@@ -0,0 +1,3 @@
+export default {
+  extends: ['@commitlint/config-conventional'],
+};

package/templates/docs/architecture.md.ejs

@@ -0,0 +1,74 @@
+# Architecture
+
+## Why this stack
+
+You selected a coherent default-friendly stack during scaffolding. The generator wires providers, scripts, and a demo page so packages are not orphaned in `package.json`.
+
+| Concern | Choice | Role |
+|---------|--------|------|
+| Bundler | <%= stackLabels.buildTool %> | Dev server + production build |
+| Language | <%= stackLabels.language %> | Source language / typing |
+| Routing | <%= stackLabels.router %> | URL → UI mapping |
+| Client state | <%= stackLabels.stateManagement %> | Local interactive state |
+| Server state | <%= stackLabels.serverState %> | Remote data cache |
+| Forms | <%= stackLabels.forms %> | Form state & submit |
+| Validation | <%= stackLabels.validation %> | Schema rules |
+| Styling | <%= stackLabels.styling %> | Visual system |
+| UI kit | <%= stackLabels.uiLibrary %> | Components / primitives |
+| API | <%= stackLabels.apiLayer %> | HTTP transport |
+
+## Folder organization (feature-based)
+
+This scaffold uses a **feature-based / domain-driven** layout — the pattern most large React teams settle on as apps grow (similar in spirit to how companies structure product domains: keep code that changes together close together).
+
+```text
+src/
+  app/           # bootstrap, providers, root App shell
+  assets/        # images, fonts, static media imported from code
+  components/    # shared, feature-agnostic UI (layout/, ui/)
+  config/        # env helpers and app-level constants
+  features/      # domain modules (counter, posts, feedback, …)
+  hooks/         # shared hooks
+  lib/           # third-party wrappers / cross-cutting helpers
+  routes/        # route-level pages
+  services/      # API clients / transport
+  store/         # global client state (when selected)
+  styles/        # global styles / tokens
+  types/         # shared TypeScript types
+  utils/         # pure helpers
+```
+
+**Rules of thumb**
+
+- Put new product work in `src/features/<domain>/`.
+- Keep `components/` dumb and reusable.
+- Import with the `@/` alias (e.g. `import { apiGet } from '@/services/api'`).
+- Prefer a feature's public surface over deep cross-feature imports.
+
+## Path aliases
+
+`@/*` maps to `src/*` in TypeScript/JS config and in your bundler (`<%= stackLabels.buildTool %>`).
+
+```ts
+import { HomePage } from '@/routes/HomePage';
+import { useToast } from '@/components/ui/Toast';
+```
+
+## Runtime composition
+
+`src/main.<%= jsxExt %>` → providers (`src/app/providers.<%= jsxExt %>`) → router (`src/app/App.<%= jsxExt %>`) → layouts/pages.
+
+Providers are ordered deliberately: state → server cache → UI theme → toasts.
+
+## Boundaries
+
+- **UI** must not call `fetch`/`axios` directly in deep leaves — go through `services/`.
+- **Schemas** live in `lib/validation` so forms and API payloads share rules.
+- **Env access** stays in `config/`, `services/`, and `lib/monitoring`.
+
+## Production readiness patterns
+
+- Code-split heavy routes when the app grows.
+- Fail closed on missing monitoring DSN (already gated).
+- Keep lint/format/test scripts green in CI.
+- Document public env vars only in `.env.example`.

package/templates/docs/best-practices.md.ejs

@@ -0,0 +1,56 @@
+# Best practices
+
+## Code organization
+
+- Colocate tests next to units or under `tests/` for cross-cutting suites.
+- Prefer small modules with clear exports over “utils dump” files.
+- Name features after domains (`billing`, `auth`), not technical junk drawers.
+
+## Linting & formatting
+
+- Tooling: **<%= stackLabels.linting %>** + **<%= stackLabels.formatting %>**
+- Run lint before push; treat warnings as debt with a burn-down plan.
+- Husky + lint-staged formats staged files so diffs stay clean.
+- commitlint enforces Conventional Commits on `git commit`.
+
+## Environment variables
+
+- Never commit `.env`.
+- Prefix client-visible vars for your bundler.
+- Validate required env at boot for production deploys.
+
+## Testing strategy
+
+<% if (unitTesting === 'vitest' || unitTesting === 'jest') { -%>
+- Unit/integration with **<%= stackLabels.unitTesting %>** + Testing Library for components.
+<% } else if (unitTesting === 'rtl') { -%>
+- React Testing Library is installed — pair it with a runner of your choice.
+<% } else { -%>
+- Unit testing was skipped; add a runner before your first production release.
+<% } -%>
+<% if (e2eTesting !== 'none') { -%>
+- E2E with **<%= stackLabels.e2eTesting %>** for critical user journeys (load home, submit form).
+<% } -%>
+<% if (visualTesting === 'storybook') { -%>
+- Storybook for isolated UI development and visual review.
+<% } 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.
+
+## Deployment notes
+
+1. `<%= packageManager === 'npm' ? 'npm run' : packageManager %> build`
+2. Serve `dist/` (or your bundler's output) 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.
+
+## Production checklist
+
+- [ ] Env vars documented and set
+- [ ] Lint + tests in CI
+- [ ] Bundle analyzed for accidental secrets
+- [ ] Monitoring verified with a test event
+- [ ] Accessibility pass on primary flows

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

@@ -0,0 +1,14 @@
+# Examples index
+
+Each file documents a concern wired into this scaffold:
+
+| 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 |
+
+Open the home page to see live counterparts of these examples.

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

@@ -0,0 +1,17 @@
+# API layer example
+
+**Choice:** <%= stackLabels.apiLayer %>
+
+## When to use
+
+All HTTP traffic should go through a single module for base URL, headers, and error logging.
+
+## Best practice
+
+- Type responses at the boundary.
+- Surface user-friendly errors in UI; log technical details to monitoring.
+- Do not scatter `fetch`/`axios` calls across components.
+
+## Snippet
+
+`src/services/api.<%= ext %>` — `apiGet`, `apiPost`, `fetchPosts`, `createFeedback`.

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

@@ -0,0 +1,18 @@
+# Data fetching example
+
+**Library:** <%= stackLabels.serverState %>
+**Transport:** <%= stackLabels.apiLayer %>
+
+**Live demo:** Posts panel on `/`
+
+## When to use
+
+Any remote read/write that benefits from caching, deduplication, retries, or background refresh.
+
+## Best practice
+
+Separate server cache from client UI state. Key queries by resource identity, not by component instance.
+
+## Snippet
+
+See `src/features/posts/PostsPanel.<%= jsxExt %>` and `src/services/api.<%= ext %>`.

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

@@ -0,0 +1,18 @@
+# Forms & validation example
+
+**Forms:** <%= stackLabels.forms %>
+**Validation:** <%= stackLabels.validation %>
+
+**Live demo:** Feedback form on `/`
+
+## When to use
+
+Multi-field input with client-side rules and async submit.
+
+## Best practice
+
+Define schemas once in `src/lib/validation.<%= ext %>` and reuse across UI and API boundaries.
+
+## Snippet
+
+See `src/features/feedback/FeedbackForm.<%= jsxExt %>`.

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

@@ -0,0 +1,17 @@
+# Client state example
+
+**Library:** <%= stackLabels.stateManagement %>
+
+**Live demo:** Counter panel on `/`
+
+## When to use
+
+Shared interactive state that is not fetched from an API (wizard steps, UI toggles, local counters).
+
+## Best practice
+
+Keep stores/slices focused. Prefer feature-local state; promote to global only when multiple distant trees need it.
+
+## Snippet
+
+See `src/features/counter/CounterPanel.<%= jsxExt %>` and `src/store/`.

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

@@ -0,0 +1,23 @@
+# Styling & UI example
+
+**Styling:** <%= stackLabels.styling %>
+**UI library:** <%= stackLabels.uiLibrary %>
+
+## When to use
+
+Establish design tokens early; use a component library for complex accessible primitives.
+
+## Best practice
+
+<% if (uiLibrary === 'shadcn') { -%>
+Treat shadcn-style primitives as owned source — customize freely, keep `cn()` helpers consistent.
+<% } else if (uiLibrary === 'none') { -%>
+Invest in a small set of shared primitives (`UiButton`, layout) before adding a full kit.
+<% } else { -%>
+Wrap third-party components in thin adapters (`UiButton`) so swapping kits later is cheaper.
+<% } -%>
+
+## Snippet
+
+Global styles: `src/styles/global.<%= styling === 'sass' && uiLibrary !== 'shadcn' ? 'scss' : 'css' %>`
+Button adapter: `src/components/ui/UiButton.<%= jsxExt %>`

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

@@ -0,0 +1,27 @@
+# Testing example
+
+| Layer | Choice |
+|-------|--------|
+| Unit | <%= stackLabels.unitTesting %> |
+| E2E | <%= stackLabels.e2eTesting %> |
+| Visual | <%= stackLabels.visualTesting %> |
+
+## When to use
+
+- Unit: pure logic + component behavior
+- E2E: critical journeys across routes
+- Visual: regressions in UI appearance
+
+## Best practice
+
+Keep e2e thin. Prefer Testing Library queries that reflect how users find elements (`getByRole`, labels).
+
+## Locations
+
+- Setup: `tests/setup.<%= ext %>` (when applicable)
+- Component smoke: `tests/App.test.<%= jsxExt %>`
+<% if (e2eTesting === 'playwright') { -%>
+- E2E: `tests/e2e/home.spec.<%= ext %>`
+<% } else if (e2eTesting === 'cypress') { -%>
+- E2E: `cypress/e2e/home.cy.<%= ext %>`
+<% } -%>

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

@@ -0,0 +1,55 @@
+# Getting started
+
+Welcome to **<%= projectName %>**, a React starter generated by `create-react-starter-kit`.
+
+## Prerequisites
+
+- Node.js 18+
+- <%= stackLabels.packageManager %>
+
+## Install & run
+
+```bash
+<% if (packageManager === 'pnpm') { -%>
+pnpm install
+pnpm dev
+<% } else if (packageManager === 'yarn') { -%>
+yarn
+yarn dev
+<% } else { -%>
+npm install
+npm run dev
+<% } -%>
+```
+
+## Environment variables
+
+Copy `.env.example` → `.env` and fill values. Restart the dev server after changes.
+
+Only variables prefixed for your bundler (e.g. `VITE_`) are exposed to the browser. Keep secrets on the server.
+
+## 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.
+
+## Extending the app
+
+- Add a domain under `src/features/<name>/`.
+- Register routes in `src/app/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'`.
+
+## Testing
+
+<% if (unitTesting !== 'none') { -%>
+- Unit: `<%= packageManager === 'npm' ? 'npm run' : packageManager %> test`
+<% } -%>
+<% if (e2eTesting !== 'none') { -%>
+- E2E: `<%= packageManager === 'npm' ? 'npm run' : packageManager %> test:e2e`
+<% } -%>
+
+See `docs/best-practices.md` for CI and production notes.

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

@@ -0,0 +1,55 @@
+# Selected stack
+
+This document explains each choice made when generating **<%= projectName %>**.
+
+## Build — <%= stackLabels.buildTool %>
+
+Fast local feedback and a production bundle. Prefer keeping config minimal; add plugins only when needed.
+
+**Best practice:** lock Node and package manager versions in CI for reproducible builds.
+
+## Language — <%= stackLabels.language %>
+
+<% if (isTypeScript) { -%>
+TypeScript catches contract mistakes early. Keep `strict` on; avoid `any` except at true boundaries.
+<% } else { -%>
+JavaScript keeps the barrier low. 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.
+
+## 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.
+
+## Server state — <%= stackLabels.serverState %>
+
+Caches remote data, handles loading/error, and deduplicates requests. Example: posts panel on the home page.
+
+## Forms — <%= stackLabels.forms %> / Validation — <%= stackLabels.validation %>
+
+Schemas define the contract; the form library binds inputs. Share schemas with API payloads when possible.
+
+## Styling — <%= stackLabels.styling %> / UI — <%= stackLabels.uiLibrary %>
+
+Tokens and primitives establish visual consistency. Prefer composition over one-off CSS.
+
+## API — <%= stackLabels.apiLayer %>
+
+Centralize base URL, headers, and error logging in `src/services/api.<%= ext %>`.
+
+## Quality gates
+
+| Area | Choice |
+|------|--------|
+| Unit | <%= stackLabels.unitTesting %> |
+| E2E | <%= stackLabels.e2eTesting %> |
+| Visual | <%= stackLabels.visualTesting %> |
+| Lint | <%= stackLabels.linting %> |
+| Format | <%= stackLabels.formatting %> |
+| Git hooks | Husky + lint-staged + commitlint |
+| Structure | Feature-based + `@/` aliases |
+
+See `docs/examples/` for focused usage notes.