create-react-starter-kit 1.0.0

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "create-react-starter-kit",
+  "version": "1.0.0",
+  "description": "Interactive CLI to scaffold a production-ready React app with your preferred stack",
+  "keywords": [
+    "react",
+    "starter-kit",
+    "boilerplate",
+    "scaffold",
+    "cli",
+    "create-react-app",
+    "vite",
+    "typescript",
+    "generator"
+  ],
+  "author": "",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-react-starter-kit": "./bin/create-react-starter-kit.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsc && node scripts/copy-templates.mjs",
+    "dev": "tsc --watch",
+    "start": "node bin/create-react-starter-kit.js",
+    "validate": "npm run build && node scripts/validate-cli.mjs",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "ejs": "^3.1.10",
+    "execa": "^9.5.2",
+    "fs-extra": "^11.3.0",
+    "inquirer": "^12.4.2",
+    "ora": "^8.2.0",
+    "validate-npm-package-name": "^6.0.0"
+  },
+  "devDependencies": {
+    "@types/ejs": "^3.1.5",
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22.13.10",
+    "@types/validate-npm-package-name": "^3.0.3",
+    "typescript": "^5.8.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/example/create-react-starter-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/example/create-react-starter-kit/issues"
+  },
+  "homepage": "https://github.com/example/create-react-starter-kit#readme"
+}

package/templates/.env.example.ejs

@@ -0,0 +1,21 @@
+# API
+VITE_API_BASE_URL=https://jsonplaceholder.typicode.com
+
+<% if (errorTracking === 'sentry') { -%>
+# Sentry
+VITE_SENTRY_DSN=
+<% } -%>
+<% if (errorTracking === 'bugsnag') { -%>
+# Bugsnag
+VITE_BUGSNAG_API_KEY=
+<% } -%>
+<% if (errorTracking === 'logrocket') { -%>
+# LogRocket
+VITE_LOGROCKET_APP_ID=
+<% } -%>
+<% if (errorTracking === 'datadog') { -%>
+# Datadog RUM
+VITE_DATADOG_APPLICATION_ID=
+VITE_DATADOG_CLIENT_TOKEN=
+VITE_DATADOG_SITE=datadoghq.com
+<% } -%>

package/templates/.husky/commit-msg

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+npx --no -- commitlint --edit "$1"

package/templates/.husky/pre-commit

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+npx lint-staged

package/templates/README.md.ejs

@@ -0,0 +1,169 @@
+# <%= projectName %>
+
+Production-ready React starter generated by **create-react-starter-kit**.
+
+## Overview
+
+This app ships with a curated stack chosen during scaffolding, a working demo page, and documentation so you can extend the project without re-wiring libraries by hand.
+
+## Selected stack
+
+| Area | Choice |
+|------|--------|
+| Build tool | <%= stackLabels.buildTool %> |
+| Language | <%= stackLabels.language %> |
+| Routing | <%= stackLabels.router %> |
+| State | <%= stackLabels.stateManagement %> |
+| Server state | <%= stackLabels.serverState %> |
+| Forms | <%= stackLabels.forms %> |
+| Validation | <%= stackLabels.validation %> |
+| Styling | <%= stackLabels.styling %> |
+| UI library | <%= stackLabels.uiLibrary %> |
+| Unit tests | <%= stackLabels.unitTesting %> |
+| E2E tests | <%= stackLabels.e2eTesting %> |
+| Visual | <%= stackLabels.visualTesting %> |
+| Linting | <%= stackLabels.linting %> |
+| Formatting | <%= stackLabels.formatting %> |
+| API layer | <%= stackLabels.apiLayer %> |
+| Package manager | <%= stackLabels.packageManager %> |
+| Error tracking | <%= stackLabels.errorTracking %> |
+| Git hooks | Husky + lint-staged + commitlint |
+| Structure | Feature-based (domain-driven) + `@/` aliases |
+
+## Quick start
+
+```bash
+<% if (packageManager === 'pnpm') { -%>
+pnpm install
+pnpm dev
+<% } else if (packageManager === 'yarn') { -%>
+yarn
+yarn dev
+<% } else { -%>
+npm install
+npm run dev
+<% } -%>
+```
+
+Open the URL printed in the terminal (typically `http://localhost:5173`).
+
+## Environment setup
+
+1. Copy `.env.example` to `.env`.
+2. Fill in API and monitoring keys as needed.
+3. Never commit secrets — `.env` is gitignored.
+
+| Variable | Purpose |
+|----------|---------|
+| `VITE_API_BASE_URL` | REST API base URL |
+<% if (errorTracking === 'sentry') { -%>
+| `VITE_SENTRY_DSN` | Sentry DSN |
+<% } -%>
+<% if (errorTracking === 'bugsnag') { -%>
+| `VITE_BUGSNAG_API_KEY` | Bugsnag API key |
+<% } -%>
+<% if (errorTracking === 'logrocket') { -%>
+| `VITE_LOGROCKET_APP_ID` | LogRocket app id |
+<% } -%>
+<% if (errorTracking === 'datadog') { -%>
+| `VITE_DATADOG_APPLICATION_ID` | Datadog application id |
+| `VITE_DATADOG_CLIENT_TOKEN` | Datadog client token |
+<% } -%>
+
+## Folder structure
+
+```text
+src/
+  app/           # App shell, providers, bootstrap
+  assets/        # Images / media imported from code
+  components/    # Shared UI (layout/, ui/)
+  config/        # Env helpers / app config
+  features/      # Domain modules (scalable default)
+  hooks/         # Shared hooks
+  lib/           # Third-party wrappers / helpers
+  routes/        # Route-level pages
+  store/         # Client state
+  services/      # API clients
+  styles/        # Global styles
+  types/         # Shared types
+  utils/         # Pure helpers
+docs/            # Architecture & usage docs
+tests/           # Extra test helpers / e2e
+```
+
+Organization: **feature-based / domain-driven** with `@/` path aliases. See `docs/architecture.md`.
+
+## Scripts
+
+| Script | Description |
+|--------|-------------|
+| `dev` | Start development server |
+| `build` | Production build |
+<% if (unitTesting !== 'none') { -%>
+| `test` | Unit tests |
+<% } -%>
+<% if (e2eTesting !== 'none') { -%>
+| `test:e2e` | End-to-end tests |
+<% } -%>
+| `lint` | Lint the codebase |
+| `format` | Format sources |
+<% if (visualTesting === 'storybook') { -%>
+| `storybook` | Component workshop |
+<% } -%>
+
+## Technology explanations
+
+Each selected library includes:
+
+- a live example on the home/demo page
+- a short doc under `docs/examples/`
+- when-to-use guidance and a best-practice note
+
+Start with `docs/selected-stack.md` and `docs/getting-started.md`.
+
+## Example usage
+
+The demo page (`/`) shows:
+
+- navigation + layout
+<% if (stateManagement !== 'none') { -%>
+- client state (<%= stackLabels.stateManagement %>)
+<% } -%>
+<% if (serverState !== 'none') { -%>
+- data fetching (<%= stackLabels.serverState %>)
+<% } -%>
+<% if (forms !== 'none') { -%>
+- forms (<%= stackLabels.forms %>)
+<% } -%>
+<% if (validation !== 'none') { -%>
+- validation (<%= stackLabels.validation %>)
+<% } -%>
+- styling (<%= stackLabels.styling %>)
+<% if (uiLibrary !== 'none') { -%>
+- UI primitives (<%= stackLabels.uiLibrary %>)
+<% } -%>
+- API integration (<%= stackLabels.apiLayer %>)
+
+## Production best practices
+
+- Keep secrets out of the client bundle; only expose `VITE_*` (or equivalent) public vars.
+- Prefer feature folders for domain logic; keep `components/` shared and dumb.
+- Gate monitoring behind environment checks.
+- Run lint + unit + e2e in CI before merge.
+- See `docs/best-practices.md` for deeper guidance.
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| Port in use | Change the port in your build tool config or kill the process |
+| Module not found | Re-run install with <%= packageManager %> |
+| Env vars undefined | Restart the dev server after editing `.env` |
+| Tailwind classes missing | Confirm `content` paths in `tailwind.config` |
+| Type errors | Run `<%= packageManager === 'npm' ? 'npx' : packageManager %> tsc --noEmit` |
+
+More help: `docs/getting-started.md`.
+
+---
+
+Generated with [create-react-starter-kit](https://www.npmjs.com/package/create-react-starter-kit) · <%= year %>

package/templates/__js__/jsconfig.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src", "tests"]
+}

package/templates/__ts__/src/vite-env.d.ts

@@ -0,0 +1,16 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_API_BASE_URL?: string;
+  readonly VITE_SENTRY_DSN?: string;
+  readonly VITE_BUGSNAG_API_KEY?: string;
+  readonly VITE_LOGROCKET_APP_ID?: string;
+  readonly VITE_DATADOG_APPLICATION_ID?: string;
+  readonly VITE_DATADOG_CLIENT_TOKEN?: string;
+  readonly VITE_DATADOG_SITE?: string;
+  readonly MODE?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/templates/__ts__/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src", "tests"]
+}

package/templates/__when_buildTool_esbuild__/scripts/esbuild.build.mjs.ejs

@@ -0,0 +1,23 @@
+import path from 'node:path';
+import * as esbuild from 'esbuild';
+
+await esbuild.build({
+  entryPoints: ['src/main.<%= jsxExt %>'],
+  bundle: true,
+  outfile: 'dist/main.js',
+  format: 'esm',
+  minify: true,
+  sourcemap: true,
+  alias: {
+    '@': path.resolve('src'),
+  },
+  loader: {
+    '.<%= jsxExt %>': '<%= isTypeScript ? 'tsx' : 'jsx' %>',
+    '.css': 'css',
+  },
+  define: {
+    'process.env.NODE_ENV': '"production"',
+  },
+});
+
+console.log('Built dist/main.js');

package/templates/__when_buildTool_esbuild__/scripts/esbuild.dev.mjs.ejs

@@ -0,0 +1,48 @@
+import * as esbuild from 'esbuild';
+import { createServer } from 'node:http';
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+
+const ctx = await esbuild.context({
+  entryPoints: ['src/main.<%= jsxExt %>'],
+  bundle: true,
+  outfile: 'dist/main.js',
+  format: 'esm',
+  sourcemap: true,
+  alias: {
+    '@': path.resolve('src'),
+  },
+  loader: {
+    '.<%= jsxExt %>': '<%= isTypeScript ? 'tsx' : 'jsx' %>',
+    '.css': 'css',
+  },
+  define: {
+    'process.env.NODE_ENV': '"development"',
+  },
+});
+
+await ctx.watch();
+
+const server = createServer((req, res) => {
+  const url = req.url === '/' ? '/index.html' : req.url;
+  const filePath = path.join(process.cwd(), url.startsWith('/dist') ? '.' : '', url === '/index.html' ? 'index.html' : url.slice(1));
+  const resolved = url === '/index.html' ? path.join(process.cwd(), 'index.html') : path.join(process.cwd(), url.slice(1));
+  if (!existsSync(resolved)) {
+    res.writeHead(404);
+    res.end('Not found');
+    return;
+  }
+  const content = readFileSync(resolved);
+  const type = resolved.endsWith('.js')
+    ? 'text/javascript'
+    : resolved.endsWith('.css')
+      ? 'text/css'
+      : 'text/html';
+  res.writeHead(200, { 'Content-Type': type });
+  res.end(content);
+  void filePath;
+});
+
+server.listen(5173, () => {
+  console.log('esbuild app at http://localhost:5173');
+});

package/templates/__when_buildTool_parcel__/.parcelrc

@@ -0,0 +1,9 @@
+{
+  "extends": "parcel-bundler/lib/utils",
+  "source": "index.html",
+  "targets": {
+    "default": {
+      "distDir": "./dist"
+    }
+  }
+}

package/templates/__when_buildTool_rollup__/rollup.config.js.ejs

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import alias from '@rollup/plugin-alias';
+import resolve from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+import replace from '@rollup/plugin-replace';
+<% if (isTypeScript) { -%>
+import typescript from '@rollup/plugin-typescript';
+<% } -%>
+import postcss from 'rollup-plugin-postcss';
+
+export default {
+  input: 'src/main.<%= jsxExt %>',
+  output: {
+    file: 'dist/main.js',
+    format: 'esm',
+    sourcemap: true,
+  },
+  plugins: [
+    alias({
+      entries: [{ find: '@', replacement: path.resolve('src') }],
+    }),
+    replace({
+      preventAssignment: true,
+      'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV || 'development'),
+    }),
+    resolve({ browser: true, extensions: ['.<%= jsxExt %>', '.<%= ext %>', '.js', '.jsx'] }),
+    commonjs(),
+<% if (isTypeScript) { -%>
+    typescript({ tsconfig: './tsconfig.json' }),
+<% } -%>
+    postcss({ extract: true }),
+  ],
+};

package/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/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/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/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/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/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/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/templates/__when_formatting_prettier__/.prettierrc

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

package/templates/__when_formatting_stylelint__/.stylelintrc.json

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

package/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"
+    }
+  }
+}