create-react-starter-kit 1.0.2 → 1.0.4

package/templates/__when_linting_biome__/biome.json

@@ -1,5 +1,17 @@
 {
   "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "files": {
+    "ignore": [
+      "node_modules",
+      "dist",
+      "build",
+      "coverage",
+      "storybook-static",
+      ".parcel-cache",
+      "playwright-report",
+      "test-results"
+    ]
+  },
   "organizeImports": { "enabled": true },
   "linter": {
     "enabled": true,

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

@@ -1,11 +1,20 @@
 import { render, screen } from '@testing-library/react';
-import { AppProviders } from '@/app/providers';
+<% if (router === 'react-router') { -%>
+import { MemoryRouter } from 'react-router-dom';
+<% } -%>
+import { AppProviders } from '@/providers';
 import { HomePage } from '@/routes/HomePage';
 
 test('renders the project hero', () => {
   render(
     <AppProviders>
+<% if (router === 'react-router') { -%>
+      <MemoryRouter>
+        <HomePage />
+      </MemoryRouter>
+<% } else { -%>
       <HomePage />
+<% } -%>
     </AppProviders>,
   );
 

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

@@ -1,11 +1,20 @@
 import { render, screen } from '@testing-library/react';
-import { AppProviders } from '@/app/providers';
+<% if (router === 'react-router') { -%>
+import { MemoryRouter } from 'react-router-dom';
+<% } -%>
+import { AppProviders } from '@/providers';
 import { HomePage } from '@/routes/HomePage';
 
 test('renders the project hero', () => {
   render(
     <AppProviders>
+<% if (router === 'react-router') { -%>
+      <MemoryRouter>
+        <HomePage />
+      </MemoryRouter>
+<% } else { -%>
       <HomePage />
+<% } -%>
     </AppProviders>,
   );
 

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

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { CounterPanel } from '@/features/counter/CounterPanel';
+import { renderWithProviders } from './test-utils';
+
+describe('CounterPanel', () => {
+<% if (stateManagement === 'none') { -%>
+  it('shows guidance when no state library is selected', () => {
+    renderWithProviders(<CounterPanel />);
+    expect(screen.getByText(/Client state library was set to None/i)).toBeInTheDocument();
+  });
+<% } else { -%>
+  it('starts at 0 and updates when increment/decrement are clicked', async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<CounterPanel />);
+
+    expect(screen.getByTestId('counter-value')).toHaveTextContent('0');
+
+    await user.click(screen.getByRole('button', { name: 'Increment' }));
+    expect(screen.getByTestId('counter-value')).toHaveTextContent('1');
+
+    await user.click(screen.getByRole('button', { name: 'Increment' }));
+    expect(screen.getByTestId('counter-value')).toHaveTextContent('2');
+
+    await user.click(screen.getByRole('button', { name: 'Decrement' }));
+    expect(screen.getByTestId('counter-value')).toHaveTextContent('1');
+  });
+
+  it('exposes accessible button labels', () => {
+    renderWithProviders(<CounterPanel />);
+    expect(screen.getByRole('button', { name: 'Increment' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Decrement' })).toBeInTheDocument();
+  });
+<% } -%>
+});

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

@@ -0,0 +1,49 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { FeedbackForm } from '@/features/feedback/FeedbackForm';
+import { renderWithProviders } from './test-utils';
+
+vi.mock('@/services/api', async (importOriginal) => {
+  const actual = await importOriginal<% if (isTypeScript) { %><typeof import('@/services/api')><% } %>();
+  return {
+    ...actual,
+    createFeedback: vi.fn(async () => ({ id: 101 })),
+  };
+});
+
+describe('FeedbackForm', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('shows validation errors when submitting empty values', async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<FeedbackForm />);
+
+    await user.click(screen.getByRole('button', { name: /Send feedback/i }));
+
+    await waitFor(() => {
+      expect(screen.getAllByText(/at least|valid email|required/i).length).toBeGreaterThan(0);
+    });
+  });
+
+  it('submits valid feedback and shows success status', async () => {
+    const user = userEvent.setup();
+    const { createFeedback } = await import('@/services/api');
+    renderWithProviders(<FeedbackForm />);
+
+    await user.type(screen.getByPlaceholderText('Ada Lovelace'), 'Ada Lovelace');
+    await user.type(screen.getByPlaceholderText('ada@example.com'), 'ada@example.com');
+    await user.type(
+      screen.getByPlaceholderText('What should we improve?'),
+      'Please add more routing examples.',
+    );
+    await user.click(screen.getByRole('button', { name: /Send feedback/i }));
+
+    await waitFor(() => {
+      expect(createFeedback).toHaveBeenCalled();
+      expect(screen.getByRole('status')).toHaveTextContent(/submitted successfully/i);
+    });
+  });
+});

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

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { screen } from '@testing-library/react';
+import { HomePage } from '@/routes/HomePage';
+import { AboutPage } from '@/routes/AboutPage';
+import { renderWithProviders } from './test-utils';
+
+describe('HomePage', () => {
+  it('renders the project hero and demo cards', () => {
+    renderWithProviders(<HomePage />);
+
+    expect(screen.getByRole('heading', { name: /<%= projectName %>/i })).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: /Go to counter/i })).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: /Go to posts/i })).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: /Go to feedback/i })).toBeInTheDocument();
+  });
+});
+
+describe('AboutPage', () => {
+  it('explains routes and project layout', () => {
+    renderWithProviders(<AboutPage />);
+
+    expect(screen.getByRole('heading', { name: /About this starter/i })).toBeInTheDocument();
+    expect(screen.getByText(/\/counter/)).toBeInTheDocument();
+    expect(screen.getByText(/feature-based/i)).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,58 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { PostsPanel } from '@/features/posts/PostsPanel';
+import { renderWithProviders } from './test-utils';
+
+vi.mock('@/services/api', async (importOriginal) => {
+  const actual = await importOriginal<% if (isTypeScript) { %><typeof import('@/services/api')><% } %>();
+  return {
+    ...actual,
+    fetchPosts: vi.fn(async () => [
+      { userId: 1, id: 1, title: 'Alpha post', body: 'body-1' },
+      { userId: 1, id: 2, title: 'Beta post', body: 'body-2' },
+    ]),
+  };
+});
+
+<% if (serverState === 'rtk-query') { -%>
+// RTK Query uses its own endpoint; mock still covers the transport used by other modes.
+<% } -%>
+
+describe('PostsPanel', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+<% if (serverState === 'rtk-query') { -%>
+  it('renders the posts panel chrome', async () => {
+    renderWithProviders(<PostsPanel />);
+    expect(screen.getByRole('heading', { name: 'Server state' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /Refresh/i })).toBeInTheDocument();
+  });
+<% } else { -%>
+  it('renders fetched posts', async () => {
+    renderWithProviders(<PostsPanel />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Alpha post/i)).toBeInTheDocument();
+    });
+    expect(screen.getByText(/Beta post/i)).toBeInTheDocument();
+  });
+
+  it('refreshes posts when Refresh is clicked', async () => {
+    const user = userEvent.setup();
+    const { fetchPosts } = await import('@/services/api');
+    renderWithProviders(<PostsPanel />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Alpha post/i)).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByRole('button', { name: /Refresh/i }));
+    await waitFor(() => {
+      expect(fetchPosts).toHaveBeenCalled();
+    });
+  });
+<% } -%>
+});

package/templates/__when_unitTesting_vitest__/tests/test-utils.tsx.ejs

@@ -0,0 +1,50 @@
+<% if (isTypeScript) { -%>
+import type { ReactElement, ReactNode } from 'react';
+<% } -%>
+import { render } from '@testing-library/react';
+<% if (router === 'react-router') { -%>
+import { MemoryRouter } from 'react-router-dom';
+<% } -%>
+import { AppProviders } from '@/providers';
+
+<% if (isTypeScript) { -%>
+interface Options {
+  route?: string;
+}
+
+function Wrapper({ children, route = '/' }: { children: ReactNode; route?: string }) {
+<% if (router === 'react-router') { -%>
+  return (
+    <AppProviders>
+      <MemoryRouter initialEntries={[route]}>{children}</MemoryRouter>
+    </AppProviders>
+  );
+<% } else { -%>
+  return <AppProviders>{children}</AppProviders>;
+<% } -%>
+}
+
+export function renderWithProviders(ui: ReactElement, options: Options = {}) {
+  return render(ui, {
+    wrapper: ({ children }) => <Wrapper route={options.route}>{children}</Wrapper>,
+  });
+}
+<% } else { -%>
+function Wrapper({ children, route = '/' }) {
+<% if (router === 'react-router') { -%>
+  return (
+    <AppProviders>
+      <MemoryRouter initialEntries={[route]}>{children}</MemoryRouter>
+    </AppProviders>
+  );
+<% } else { -%>
+  return <AppProviders>{children}</AppProviders>;
+<% } -%>
+}
+
+export function renderWithProviders(ui, options = {}) {
+  return render(ui, {
+    wrapper: ({ children }) => <Wrapper route={options.route}>{children}</Wrapper>,
+  });
+}
+<% } -%>

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

@@ -1,11 +1,42 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+<% if (buildTool === 'vite' || buildTool === 'esbuild') { -%>
+import { mergeConfig } from 'vite';
+<% } -%>
+
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+
 /** @type { import('@storybook/<%= buildTool === 'vite' || buildTool === 'esbuild' ? 'react-vite' : 'react-webpack5' %>').StorybookConfig } */
 const config = {
   stories: ['../src/**/*.stories.@(<%= isTypeScript ? 'ts|tsx' : 'js|jsx' %>)'],
-  addons: [],
+  addons: ['@storybook/addon-essentials'],
   framework: {
     name: '@storybook/<%= buildTool === 'vite' || buildTool === 'esbuild' ? 'react-vite' : 'react-webpack5' %>',
     options: {},
   },
+  docs: {
+    autodocs: 'tag',
+  },
+<% if (buildTool === 'vite' || buildTool === 'esbuild') { -%>
+  async viteFinal(config) {
+    return mergeConfig(config, {
+      resolve: {
+        alias: {
+          '@': path.resolve(dirname, '../src'),
+        },
+      },
+    });
+  },
+<% } else { -%>
+  async webpackFinal(config) {
+    config.resolve = config.resolve ?? {};
+    config.resolve.alias = {
+      ...(config.resolve.alias ?? {}),
+      '@': path.resolve(dirname, '../src'),
+    };
+    return config;
+  },
+<% } -%>
 };
 
 export default config;

package/templates/__when_visualTesting_storybook__/.storybook/preview.tsx.ejs

@@ -0,0 +1,42 @@
+<% if (isTypeScript) { -%>
+import type { Preview } from '@storybook/react';
+<% } -%>
+import { AppProviders } from '../src/providers';
+<% if (router === 'react-router') { -%>
+import { MemoryRouter } from 'react-router-dom';
+<% } -%>
+import '../src/styles/global.<%= styling === 'sass' && uiLibrary !== 'shadcn' ? 'scss' : 'css' %>';
+
+const preview<% if (isTypeScript) { %>: Preview<% } %> = {
+  parameters: {
+    layout: 'padded',
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+    docs: {
+      toc: true,
+    },
+  },
+  decorators: [
+    (Story) => (
+      <AppProviders>
+<% if (router === 'react-router') { -%>
+        <MemoryRouter>
+          <div style={{ maxWidth: 960, margin: '0 auto' }}>
+            <Story />
+          </div>
+        </MemoryRouter>
+<% } else { -%>
+        <div style={{ maxWidth: 960, margin: '0 auto' }}>
+          <Story />
+        </div>
+<% } -%>
+      </AppProviders>
+    ),
+  ],
+};
+
+export default preview;

package/templates/__when_visualTesting_storybook__/src/components/StackBadge.stories.tsx.ejs

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { StackBadge } from '@/components/StackBadge';
+
+const meta = {
+  title: 'Components/StackBadge',
+  component: StackBadge,
+  tags: ['autodocs'],
+  args: {
+    label: 'Build',
+    value: '<%= stackLabels.buildTool %>',
+  },
+} satisfies Meta<typeof StackBadge>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const Language: Story = {
+  args: {
+    label: 'Language',
+    value: '<%= stackLabels.language %>',
+  },
+};
+
+export const Row: Story = {
+  render: () => (
+    <div className="stack-row">
+      <StackBadge label="Build" value="<%= stackLabels.buildTool %>" />
+      <StackBadge label="Router" value="<%= stackLabels.router %>" />
+      <StackBadge label="State" value="<%= stackLabels.stateManagement %>" />
+      <StackBadge label="Data" value="<%= stackLabels.serverState %>" />
+    </div>
+  ),
+};

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

@@ -1,15 +1,38 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { UiButton } from '@/components/ui/UiButton';
 
+/**
+ * Shared button adapter used across demos.
+ * Prefer this over raw HTML buttons so UI library swaps stay localized.
+ */
 const meta = {
-  title: 'UI/UiButton',
+  title: 'Components/UiButton',
   component: UiButton,
+  tags: ['autodocs'],
   args: {
     children: 'Click me',
   },
+  argTypes: {
+    onClick: { action: 'clicked' },
+    children: { control: 'text' },
+  },
 } satisfies Meta<typeof UiButton>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Primary: Story = {};
+
+export const SubmitLabel: Story = {
+  args: {
+    children: 'Send feedback',
+    type: 'submit',
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    children: 'Disabled',
+    disabled: true,
+  },
+};

package/templates/__when_visualTesting_storybook__/src/features/counter/CounterPanel.stories.tsx.ejs

@@ -0,0 +1,25 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { CounterPanel } from '@/features/counter/CounterPanel';
+
+/**
+ * Client-state demo used on `/counter`.
+ * Interact with +/- to verify store wiring in isolation.
+ */
+const meta = {
+  title: 'Features/CounterPanel',
+  component: CounterPanel,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Demonstrates <%= stackLabels.stateManagement %> for ephemeral UI state. Prefer this over putting server entities into client stores.',
+      },
+    },
+  },
+} satisfies Meta<typeof CounterPanel>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/templates/__when_visualTesting_storybook__/src/features/feedback/FeedbackForm.stories.tsx.ejs

@@ -0,0 +1,25 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { FeedbackForm } from '@/features/feedback/FeedbackForm';
+
+/**
+ * Forms demo used on `/feedback`.
+ * Try empty submit for validation, then a valid payload for success status.
+ */
+const meta = {
+  title: 'Features/FeedbackForm',
+  component: FeedbackForm,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Built with <%= stackLabels.forms %><% if (validation !== 'none') { %> and <%= stackLabels.validation %><% } %>. Submits to the demo REST API.',
+      },
+    },
+  },
+} satisfies Meta<typeof FeedbackForm>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Empty: Story = {};

package/templates/__when_visualTesting_storybook__/src/features/posts/PostsPanel.stories.tsx.ejs

@@ -0,0 +1,25 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { PostsPanel } from '@/features/posts/PostsPanel';
+
+/**
+ * Server-state demo used on `/posts`.
+ * Needs network access to JSONPlaceholder (or your `VITE_API_BASE_URL`).
+ */
+const meta = {
+  title: 'Features/PostsPanel',
+  component: PostsPanel,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Fetches posts with <%= stackLabels.serverState === 'None' ? stackLabels.apiLayer : stackLabels.serverState %>. Use Refresh to exercise refetch behavior.',
+      },
+    },
+  },
+} satisfies Meta<typeof PostsPanel>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/templates/__when_visualTesting_storybook__/src/routes/Pages.stories.tsx.ejs

@@ -0,0 +1,42 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { HomePage } from '@/routes/HomePage';
+import { AboutPage } from '@/routes/AboutPage';
+import { CounterPage } from '@/routes/CounterPage';
+import { PostsPage } from '@/routes/PostsPage';
+import { FeedbackPage } from '@/routes/FeedbackPage';
+
+const meta = {
+  title: 'Pages/Routes',
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Route-level pages composed from feature panels. Useful for visual review of layout and copy.',
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+export const Home: Story = {
+  render: () => <HomePage />,
+};
+
+export const About: Story = {
+  render: () => <AboutPage />,
+};
+
+export const Counter: Story = {
+  render: () => <CounterPage />,
+};
+
+export const Posts: Story = {
+  render: () => <PostsPage />,
+};
+
+export const Feedback: Story = {
+  render: () => <FeedbackPage />,
+};

package/templates/docs/architecture.md.ejs

@@ -2,7 +2,7 @@
 
 ## 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`.
+You selected a coherent default-friendly stack during scaffolding. The generator wires providers, scripts, and demo routes so packages are not orphaned in `package.json`.
 
 | Concern | Choice | Role |
 |---------|--------|------|
@@ -19,56 +19,54 @@ You selected a coherent default-friendly stack during scaffolding. The generator
 
 ## 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
+  main.<%= jsxExt %>    # bootstrap + render
+  providers.<%= jsxExt %>
+  App.<%= jsxExt %>     # route tree
+  assets/
+  components/         # shared UI (layout/, ui/)
+  config/
+  features/           # domain modules
+  hooks/
+  lib/
+  routes/             # / /counter /posts /feedback /about
+  services/
+  store/
+  styles/
+  types/
+  utils/
 ```
 
 **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'`).
+- Import with the `@/` alias.
 - Prefer a feature's public surface over deep cross-feature imports.
 
-## Path aliases
+## Routes
 
-`@/*` maps to `src/*` in TypeScript/JS config and in your bundler (`<%= stackLabels.buildTool %>`).
+| Path | Purpose |
+|------|---------|
+| `/` | Home overview |
+| `/counter` | Client state demo |
+| `/posts` | Server state / data fetching |
+| `/feedback` | Forms + validation |
+| `/about` | Orientation |
 
-```ts
-import { HomePage } from '@/routes/HomePage';
-import { useToast } from '@/components/ui/Toast';
-```
+## Path aliases
+
+`@/*` maps to `src/*` in TypeScript/JS config and in your bundler.
 
 ## Runtime composition
 
-`src/main.<%= jsxExt %>` → providers (`src/app/providers.<%= jsxExt %>`) → router (`src/app/App.<%= jsxExt %>`) → layouts/pages.
+`src/main.<%= jsxExt %>` → `AppProviders` → `App` (router) → layout → pages.
 
-Providers are ordered deliberately: state → server cache → UI theme → toasts.
+Providers are ordered: client state → server cache → UI theme.
 
 ## 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.
+- **UI** should call HTTP through `services/`.
+- **Schemas** live in `lib/validation`.
 - **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`.