create-react-starter-kit 1.0.0

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

package/dist/templates/index.html.ejs

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title><%= projectName %></title>
+  </head>
+  <body>
+    <div id="root"></div>
+<% if (buildTool === 'vite') { -%>
+    <script type="module" src="/src/main.<%= jsxExt %>"></script>
+<% } else if (buildTool === 'parcel') { -%>
+    <script type="module" src="./src/main.<%= jsxExt %>"></script>
+<% } else if (buildTool === 'esbuild' || buildTool === 'rollup') { -%>
+    <script type="module" src="/dist/main.js"></script>
+<% } -%>
+  </body>
+</html>

package/dist/templates/public/vite.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
+  <rect width="32" height="32" rx="8" fill="#1d4ed8"/>
+  <path d="M8 22L16 8l8 14H8z" fill="#fff"/>
+</svg>

package/dist/templates/src/app/App.tsx.ejs

@@ -0,0 +1,71 @@
+<% if (router === 'react-router') { -%>
+import { BrowserRouter, Navigate, Route, Routes } from 'react-router-dom';
+import { AppLayout } from '@/components/layout/AppLayout';
+import { HomePage } from '@/routes/HomePage';
+import { AboutPage } from '@/routes/AboutPage';
+
+export function App() {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route element={<AppLayout />}>
+          <Route path="/" element={<HomePage />} />
+          <Route path="/about" element={<AboutPage />} />
+          <Route path="*" element={<Navigate to="/" replace />} />
+        </Route>
+      </Routes>
+    </BrowserRouter>
+  );
+}
+<% } else { -%>
+import {
+  Outlet,
+  RouterProvider,
+  createRootRoute,
+  createRoute,
+  createRouter,
+} from '@tanstack/react-router';
+import { AppLayout } from '@/components/layout/AppLayout';
+import { HomePage } from '@/routes/HomePage';
+import { AboutPage } from '@/routes/AboutPage';
+
+function RootComponent() {
+  return (
+    <AppLayout>
+      <Outlet />
+    </AppLayout>
+  );
+}
+
+const rootRoute = createRootRoute({
+  component: RootComponent,
+});
+
+const indexRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/',
+  component: HomePage,
+});
+
+const aboutRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/about',
+  component: AboutPage,
+});
+
+const routeTree = rootRoute.addChildren([indexRoute, aboutRoute]);
+
+const router = createRouter({ routeTree });
+
+<% if (isTypeScript) { -%>
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router;
+  }
+}
+<% } -%>
+
+export function App() {
+  return <RouterProvider router={router} />;
+}
+<% } -%>

package/dist/templates/src/app/providers.tsx.ejs

@@ -0,0 +1,93 @@
+<% if (isTypeScript) { -%>
+import type { ReactNode } from 'react';
+<% } -%>
+<% if (serverState === 'tanstack-query') { -%>
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+<% } -%>
+<% if (serverState === 'swr') { -%>
+import { SWRConfig } from 'swr';
+import { apiGet } from '@/services/api';
+<% } -%>
+<% if (stateManagement === 'redux') { -%>
+import { Provider } from 'react-redux';
+import { store } from '@/store';
+<% } -%>
+<% if (stateManagement === 'jotai') { -%>
+import { Provider as JotaiProvider } from 'jotai';
+<% } -%>
+<% if (stateManagement === 'context') { -%>
+import { AppStateProvider } from '@/store/context';
+<% } -%>
+<% if (uiLibrary === 'chakra') { -%>
+import { ChakraProvider, defaultSystem } from '@chakra-ui/react';
+<% } -%>
+<% if (uiLibrary === 'mui') { -%>
+import { CssBaseline, ThemeProvider, createTheme } from '@mui/material';
+<% } -%>
+import { ToastProvider } from '@/components/ui/Toast';
+
+<% if (serverState === 'tanstack-query') { -%>
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 30_000,
+      retry: 1,
+    },
+  },
+});
+<% } -%>
+<% if (uiLibrary === 'mui') { -%>
+const theme = createTheme({
+  palette: {
+    primary: { main: '#1d4ed8' },
+  },
+});
+<% } -%>
+
+<% if (isTypeScript) { -%>
+interface AppProvidersProps {
+  children: ReactNode;
+}
+<% } -%>
+
+export function AppProviders({ children }<% if (isTypeScript) { %>: AppProvidersProps<% } %>) {
+  let tree = children;
+
+<% if (stateManagement === 'context') { -%>
+  tree = <AppStateProvider>{tree}</AppStateProvider>;
+<% } -%>
+<% if (stateManagement === 'jotai') { -%>
+  tree = <JotaiProvider>{tree}</JotaiProvider>;
+<% } -%>
+<% if (stateManagement === 'redux') { -%>
+  tree = <Provider store={store}>{tree}</Provider>;
+<% } -%>
+<% if (serverState === 'tanstack-query') { -%>
+  tree = <QueryClientProvider client={queryClient}>{tree}</QueryClientProvider>;
+<% } -%>
+<% if (serverState === 'swr') { -%>
+  tree = (
+    <SWRConfig
+      value={{
+        fetcher: (url<% if (isTypeScript) { %>: string<% } %>) => apiGet(url),
+        revalidateOnFocus: false,
+      }}
+    >
+      {tree}
+    </SWRConfig>
+  );
+<% } -%>
+<% if (uiLibrary === 'mui') { -%>
+  tree = (
+    <ThemeProvider theme={theme}>
+      <CssBaseline />
+      {tree}
+    </ThemeProvider>
+  );
+<% } -%>
+<% if (uiLibrary === 'chakra') { -%>
+  tree = <ChakraProvider value={defaultSystem}>{tree}</ChakraProvider>;
+<% } -%>
+
+  return <ToastProvider>{tree}</ToastProvider>;
+}

package/dist/templates/src/components/StackBadge.tsx.ejs

@@ -0,0 +1,15 @@
+<% if (isTypeScript) { -%>
+interface StackBadgeProps {
+  label: string;
+  value: string;
+}
+<% } -%>
+
+export function StackBadge({ label, value }<% if (isTypeScript) { %>: StackBadgeProps<% } %>) {
+  return (
+    <div className="stack-badge">
+      <span className="stack-badge-label">{label}</span>
+      <span className="stack-badge-value">{value}</span>
+    </div>
+  );
+}

package/dist/templates/src/components/layout/AppLayout.tsx.ejs

@@ -0,0 +1,64 @@
+<% if (isTypeScript) { -%>
+import type { ReactNode } from 'react';
+<% } -%>
+<% if (router === 'react-router') { -%>
+import { NavLink, Outlet } from 'react-router-dom';
+<% } else { -%>
+import { Link, useRouterState } from '@tanstack/react-router';
+<% } -%>
+
+<% if (isTypeScript && router === 'tanstack-router') { -%>
+interface AppLayoutProps {
+  children?: ReactNode;
+}
+<% } -%>
+
+export function AppLayout(<% if (router === 'tanstack-router') { %>{ children }<% if (isTypeScript) { %>: AppLayoutProps<% } %><% } %>) {
+<% if (router === 'tanstack-router') { -%>
+  const pathname = useRouterState({ select: (s) => s.location.pathname });
+<% } -%>
+
+  return (
+    <div className="app-shell">
+      <header className="app-header">
+        <div className="brand">
+          <span className="brand-mark" aria-hidden="true" />
+          <div>
+            <p className="brand-name"><%= projectName %></p>
+            <p className="brand-tagline">Production React starter</p>
+          </div>
+        </div>
+        <nav className="app-nav" aria-label="Primary">
+<% if (router === 'react-router') { -%>
+          <NavLink to="/" end className={({ isActive }) => (isActive ? 'nav-link active' : 'nav-link')}>
+            Home
+          </NavLink>
+          <NavLink to="/about" className={({ isActive }) => (isActive ? 'nav-link active' : 'nav-link')}>
+            About
+          </NavLink>
+<% } else { -%>
+          <Link to="/" className={pathname === '/' ? 'nav-link active' : 'nav-link'}>
+            Home
+          </Link>
+          <Link to="/about" className={pathname === '/about' ? 'nav-link active' : 'nav-link'}>
+            About
+          </Link>
+<% } -%>
+        </nav>
+      </header>
+      <main className="app-main">
+<% if (router === 'react-router') { -%>
+        <Outlet />
+<% } else { -%>
+        {children}
+<% } -%>
+      </main>
+      <footer className="app-footer">
+        <p>
+          Scaffolded with create-react-starter-kit · <%= stackLabels.buildTool %> ·{' '}
+          <%= stackLabels.language %>
+        </p>
+      </footer>
+    </div>
+  );
+}

package/dist/templates/src/components/ui/Toast.tsx.ejs

@@ -0,0 +1,61 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+<% if (isTypeScript) { -%>
+  type ReactNode,
+<% } -%>
+} from 'react';
+
+<% if (isTypeScript) { -%>
+type ToastTone = 'info' | 'success' | 'error';
+
+interface ToastItem {
+  id: string;
+  message: string;
+  tone: ToastTone;
+}
+
+interface ToastContextValue {
+  push: (message: string, tone?: ToastTone) => void;
+}
+<% } -%>
+
+const ToastContext = createContext<% if (isTypeScript) { %><ToastContextValue | null><% } %>(null);
+
+export function ToastProvider({ children }<% if (isTypeScript) { %>: { children: ReactNode }<% } %>) {
+  const [items, setItems] = useState<% if (isTypeScript) { %><ToastItem[]><% } %>([]);
+
+  const push = useCallback((message<% if (isTypeScript) { %>: string<% } %>, tone<% if (isTypeScript) { %>: ToastTone<% } %> = 'info') => {
+    const id = crypto.randomUUID();
+    setItems((prev) => [...prev, { id, message, tone }]);
+    window.setTimeout(() => {
+      setItems((prev) => prev.filter((item) => item.id !== id));
+    }, 3200);
+  }, []);
+
+  const value = useMemo(() => ({ push }), [push]);
+
+  return (
+    <ToastContext.Provider value={value}>
+      {children}
+      <div className="toast-viewport" aria-live="polite">
+        {items.map((item) => (
+          <div key={item.id} className={`toast toast-${item.tone}`}>
+            {item.message}
+          </div>
+        ))}
+      </div>
+    </ToastContext.Provider>
+  );
+}
+
+export function useToast() {
+  const ctx = useContext(ToastContext);
+  if (!ctx) {
+    throw new Error('useToast must be used within ToastProvider');
+  }
+  return ctx;
+}