create-react-starter-kit 1.0.2 → 1.0.3

package/dist/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/dist/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/dist/templates/__when_visualTesting_storybook__/.storybook/main.js.ejs

@@ -1,11 +1,14 @@
 /** @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',
+  },
 };
 
 export default config;

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

@@ -0,0 +1,40 @@
+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' %>';
+
+/** @type { import('@storybook/react').Preview } */
+const 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/dist/templates/__when_visualTesting_storybook__/.storybook/preview.tsx.ejs

@@ -0,0 +1,40 @@
+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' %>';
+
+/** @type { import('@storybook/react').Preview } */
+const 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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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`.

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

@@ -38,7 +38,7 @@ Only variables prefixed for your bundler (e.g. `VITE_`) are exposed to the brows
 ## Extending the app
 
 - Add a domain under `src/features/<name>/`.
-- Register routes in `src/app/App.<%= jsxExt %>`.
+- Register routes in `src/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'`.

package/{templates/src/app → dist/templates/src}/App.tsx.ejs

@@ -3,6 +3,9 @@ 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';
+import { CounterPage } from '@/routes/CounterPage';
+import { PostsPage } from '@/routes/PostsPage';
+import { FeedbackPage } from '@/routes/FeedbackPage';
 
 export function App() {
   return (
@@ -11,6 +14,9 @@ export function App() {
         <Route element={<AppLayout />}>
           <Route path="/" element={<HomePage />} />
           <Route path="/about" element={<AboutPage />} />
+          <Route path="/counter" element={<CounterPage />} />
+          <Route path="/posts" element={<PostsPage />} />
+          <Route path="/feedback" element={<FeedbackPage />} />
           <Route path="*" element={<Navigate to="/" replace />} />
         </Route>
       </Routes>
@@ -28,6 +34,9 @@ import {
 import { AppLayout } from '@/components/layout/AppLayout';
 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';
 
 function RootComponent() {
   return (
@@ -53,7 +62,31 @@ const aboutRoute = createRoute({
   component: AboutPage,
 });
 
-const routeTree = rootRoute.addChildren([indexRoute, aboutRoute]);
+const counterRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/counter',
+  component: CounterPage,
+});
+
+const postsRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/posts',
+  component: PostsPage,
+});
+
+const feedbackRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/feedback',
+  component: FeedbackPage,
+});
+
+const routeTree = rootRoute.addChildren([
+  indexRoute,
+  aboutRoute,
+  counterRoute,
+  postsRoute,
+  feedbackRoute,
+]);
 
 const router = createRouter({ routeTree });
 

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

@@ -13,6 +13,14 @@ interface AppLayoutProps {
 }
 <% } -%>
 
+const links = [
+  { to: '/', label: 'Home', end: true },
+  { to: '/counter', label: 'Counter' },
+  { to: '/posts', label: 'Posts' },
+  { to: '/feedback', label: 'Feedback' },
+  { to: '/about', label: 'About' },
+] as const;
+
 export function AppLayout(<% if (router === 'tanstack-router') { %>{ children }<% if (isTypeScript) { %>: AppLayoutProps<% } %><% } %>) {
 <% if (router === 'tanstack-router') { -%>
   const pathname = useRouterState({ select: (s) => s.location.pathname });
@@ -30,19 +38,34 @@ export function AppLayout(<% if (router === 'tanstack-router') { %>{ children }<
         </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>
+          {links.map((link) => (
+            <NavLink
+              key={link.to}
+              to={link.to}
+              end={'end' in link ? link.end : false}
+              className={({ isActive }) => (isActive ? 'nav-link active' : 'nav-link')}
+            >
+              {link.label}
+            </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>
+          {links.map((link) => (
+            <Link
+              key={link.to}
+              to={link.to}
+              className={
+                link.to === '/'
+                  ? pathname === '/'
+                    ? 'nav-link active'
+                    : 'nav-link'
+                  : pathname.startsWith(link.to)
+                    ? 'nav-link active'
+                    : 'nav-link'
+              }
+            >
+              {link.label}
+            </Link>
+          ))}
 <% } -%>
         </nav>
       </header>