create-react-starter-kit 1.0.0

package/dist/templates/__when_buildTool_rspack__/rspack.config.js.ejs

@@ -0,0 +1,36 @@
+import path from 'node:path';
+import { defineConfig } from '@rspack/cli';
+import { HtmlRspackPlugin } from '@rspack/core';
+
+export default defineConfig({
+  entry: {
+    main: './src/main.<%= jsxExt %>',
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve('src'),
+    },
+  },
+  builtins: {
+    react: {
+      runtime: 'automatic',
+    },
+  },
+  module: {
+    rules: [
+      {
+        test: /\.css$/,
+        type: 'css',
+      },
+    ],
+  },
+  plugins: [
+    new HtmlRspackPlugin({
+      template: './index.html',
+    }),
+  ],
+  devServer: {
+    port: 5173,
+    historyApiFallback: true,
+  },
+});

package/dist/templates/__when_buildTool_vite__/vite.config.ts.ejs

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+<% if (unitTesting === 'vitest') { -%>
+import { defineConfig as defineVitestConfig, mergeConfig } from 'vitest/config';
+<% } -%>
+
+const rootDir = path.dirname(fileURLToPath(import.meta.url));
+
+const viteConfig = defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': path.resolve(rootDir, 'src'),
+    },
+  },
+  server: {
+    port: 5173,
+  },
+});
+
+<% if (unitTesting === 'vitest') { -%>
+export default mergeConfig(
+  viteConfig,
+  defineVitestConfig({
+    test: {
+      globals: true,
+      environment: 'jsdom',
+      setupFiles: './tests/setup.<%= ext %>',
+      exclude: ['**/node_modules/**', '**/dist/**', '**/e2e/**', '**/*.e2e.*'],
+    },
+  }),
+);
+<% } else { -%>
+export default viteConfig;
+<% } -%>

package/dist/templates/__when_buildTool_webpack__/webpack.config.js.ejs

@@ -0,0 +1,68 @@
+<% if (isTypeScript) { -%>
+import type { Configuration } from 'webpack';
+import type { Configuration as DevServerConfiguration } from 'webpack-dev-server';
+<% } -%>
+import path from 'node:path';
+import HtmlWebpackPlugin from 'html-webpack-plugin';
+
+<% if (isTypeScript) { -%>
+const config: Configuration & { devServer?: DevServerConfiguration } = {
+<% } else { -%>
+const config = {
+<% } -%>
+  entry: './src/main.<%= jsxExt %>',
+  output: {
+    path: path.resolve('dist'),
+    filename: '[name].[contenthash].js',
+    clean: true,
+    publicPath: '/',
+  },
+  resolve: {
+    extensions: ['.<%= jsxExt %>', '.<%= ext %>', '.js', '.jsx', '.json'],
+    alias: {
+      '@': path.resolve('src'),
+    },
+  },
+  module: {
+    rules: [
+      {
+        test: /\.(<%= isTypeScript ? 'ts|tsx' : 'js|jsx' %>)$/,
+        exclude: /node_modules/,
+        use: {
+          loader: 'babel-loader',
+          options: {
+            presets: [
+              '@babel/preset-env',
+              ['@babel/preset-react', { runtime: 'automatic' }],
+<% if (isTypeScript) { -%>
+              '@babel/preset-typescript',
+<% } -%>
+            ],
+          },
+        },
+      },
+      {
+        test: /\.css$/,
+        use: ['style-loader', 'css-loader'<% if (styling === 'sass') { %>, 'sass-loader'<% } %>],
+      },
+<% if (styling === 'sass') { -%>
+      {
+        test: /\.scss$/,
+        use: ['style-loader', 'css-loader', 'sass-loader'],
+      },
+<% } -%>
+    ],
+  },
+  plugins: [
+    new HtmlWebpackPlugin({
+      template: './index.html',
+    }),
+  ],
+  devServer: {
+    port: 5173,
+    historyApiFallback: true,
+    hot: true,
+  },
+};
+
+export default config;

package/dist/templates/__when_e2eTesting_cypress__/cypress/e2e/home.cy.ts.ejs

@@ -0,0 +1,6 @@
+describe('Home', () => {
+  it('loads the starter', () => {
+    cy.visit('/');
+    cy.contains('<%= projectName %>');
+  });
+});

package/dist/templates/__when_e2eTesting_cypress__/cypress.config.ts.ejs

@@ -0,0 +1,8 @@
+import { defineConfig } from 'cypress';
+
+export default defineConfig({
+  e2e: {
+    baseUrl: 'http://127.0.0.1:5173',
+    supportFile: false,
+  },
+});

package/dist/templates/__when_e2eTesting_playwright__/playwright.config.ts.ejs

@@ -0,0 +1,16 @@
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,
+  use: {
+    baseURL: 'http://127.0.0.1:5173',
+    trace: 'on-first-retry',
+  },
+  webServer: {
+    command: '<%= packageManager === 'npm' ? 'npm run dev' : packageManager + ' dev' %>',
+    url: 'http://127.0.0.1:5173',
+    reuseExistingServer: !process.env.CI,
+  },
+  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+});

package/dist/templates/__when_e2eTesting_playwright__/tests/e2e/home.spec.ts.ejs

@@ -0,0 +1,6 @@
+import { test, expect } from '@playwright/test';
+
+test('home page loads', async ({ page }) => {
+  await page.goto('/');
+  await expect(page.getByRole('heading', { name: /<%= projectName %>/i })).toBeVisible();
+});

package/dist/templates/__when_formatting_prettier__/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2
+}

package/dist/templates/__when_formatting_stylelint__/.stylelintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["stylelint-config-standard"]
+}

package/dist/templates/__when_linting_biome__/biome.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "organizeImports": { "enabled": true },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space"
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single"
+    }
+  }
+}

package/dist/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/dist/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/dist/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/dist/templates/__when_styling_tailwind__/postcss.config.js

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

package/dist/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/dist/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/dist/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/dist/templates/__when_unitTesting_jest__/tests/setup.ts.ejs

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

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

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

package/dist/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/dist/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/dist/templates/__when_unitTesting_vitest__/tests/setup.ts.ejs

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

package/dist/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/dist/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/dist/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/dist/templates/commitlint.config.js

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

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