create-react-starter-kit 1.0.1 → 1.0.3

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`.

package/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/{dist/templates/src/app → 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/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>

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

@@ -13,10 +13,8 @@ import { counterAtom } from '@/store';
 import { useAppState } from '@/store/context';
 <% } -%>
 import { UiButton } from '@/components/ui/UiButton';
-import { useToast } from '@/components/ui/Toast';
 
 export function CounterPanel() {
-  const { push } = useToast();
 <% if (stateManagement === 'redux') { -%>
   const value = useSelector((state<% if (isTypeScript) { %>: RootState<% } %>) => state.counter.value);
   const dispatch = useDispatch();
@@ -48,12 +46,20 @@ export function CounterPanel() {
         <p><%= stackLabels.stateManagement %> example — local interactive counter.</p>
       </header>
 <% if (stateManagement === 'none') { -%>
-      <p className="muted">Client state library was set to None. Add one later under <code>src/store</code>.</p>
+      <p className="muted">
+        Client state library was set to None. Add one later under <code>src/store</code>.
+      </p>
 <% } else { -%>
       <div className="counter">
-        <UiButton onClick={() => { onDec(); push('Decremented', 'info'); }}>−</UiButton>
-        <strong className="counter-value" aria-live="polite">{value}</strong>
-        <UiButton onClick={() => { onInc(); push('Incremented', 'success'); }}>+</UiButton>
+        <UiButton aria-label="Decrement" onClick={onDec}>
+          −
+        </UiButton>
+        <strong className="counter-value" data-testid="counter-value" aria-live="polite">
+          {value}
+        </strong>
+        <UiButton aria-label="Increment" onClick={onInc}>
+          +
+        </UiButton>
       </div>
 <% } -%>
       <p className="panel-note">

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

@@ -1,3 +1,4 @@
+import { useState } from 'react';
 <% if (forms === 'react-hook-form') { -%>
 import { useForm } from 'react-hook-form';
 <% if (validation === 'zod') { -%>
@@ -25,7 +26,6 @@ import { feedbackSchema } from '@/lib/validation';
 import type { FeedbackValues } from '@/lib/validation';
 <% } -%>
 <% } else { -%>
-import { useState } from 'react';
 <% if (validation === 'none') { -%>
 import { validateFeedback<% if (isTypeScript) { %>, type FeedbackValues<% } %> } from '@/lib/validation';
 <% } else { -%>
@@ -33,7 +33,6 @@ import { feedbackSchema<% if (isTypeScript) { %>, type FeedbackValues<% } %> } f
 <% } -%>
 <% } -%>
 import { createFeedback } from '@/services/api';
-import { useToast } from '@/components/ui/Toast';
 import { UiButton } from '@/components/ui/UiButton';
 
 const defaults<% if (isTypeScript) { %>: FeedbackValues<% } %> = {
@@ -43,7 +42,7 @@ const defaults<% if (isTypeScript) { %>: FeedbackValues<% } %> = {
 };
 
 export function FeedbackForm() {
-  const { push } = useToast();
+  const [status, setStatus] = useState<% if (isTypeScript) { %><string | null><% } %>(null);
 
 <% if (forms === 'react-hook-form') { -%>
   const {
@@ -71,7 +70,7 @@ export function FeedbackForm() {
     }
 <% } -%>
     await createFeedback(values);
-    push('Feedback submitted (demo API)', 'success');
+    setStatus('Feedback submitted successfully (demo API).');
     reset();
   };
 
@@ -107,6 +106,11 @@ export function FeedbackForm() {
           {isSubmitting ? 'Sending…' : 'Send feedback'}
         </UiButton>
       </form>
+      {status && (
+        <p className="success-text" role="status">
+          {status}
+        </p>
+      )}
       <p className="panel-note">
         <strong>When to use:</strong> complex forms with validation and async submit.
         <br />
@@ -137,7 +141,7 @@ export function FeedbackForm() {
           feedbackSchema.parse(values);
 <% } -%>
           await createFeedback(values);
-          push('Feedback submitted (demo API)', 'success');
+          setStatus('Feedback submitted successfully (demo API).');
           helpers.resetForm();
         }}
       >
@@ -164,6 +168,11 @@ export function FeedbackForm() {
           </Form>
         )}
       </Formik>
+      {status && (
+        <p className="success-text" role="status">
+          {status}
+        </p>
+      )}
       <p className="panel-note">
         <strong>When to use:</strong> form-heavy screens with Formik's render/props model.
         <br />
@@ -187,7 +196,7 @@ export function FeedbackForm() {
       if (result.error) throw result.error;
 <% } -%>
       await createFeedback(value);
-      push('Feedback submitted (demo API)', 'success');
+      setStatus('Feedback submitted successfully (demo API).');
       form.reset();
     },
   });
@@ -255,6 +264,11 @@ export function FeedbackForm() {
         </form.Field>
         <UiButton type="submit">Send feedback</UiButton>
       </form>
+      {status && (
+        <p className="success-text" role="status">
+          {status}
+        </p>
+      )}
       <p className="panel-note">
         <strong>When to use:</strong> headless, type-safe forms with fine-grained reactivity.
         <br />
@@ -315,7 +329,7 @@ export function FeedbackForm() {
     setIsSubmitting(true);
     try {
       await createFeedback(values);
-      push('Feedback submitted (demo API)', 'success');
+      setStatus('Feedback submitted successfully (demo API).');
       setValues(defaults);
     } finally {
       setIsSubmitting(false);
@@ -362,6 +376,11 @@ export function FeedbackForm() {
           {isSubmitting ? 'Sending…' : 'Send feedback'}
         </UiButton>
       </form>
+      {status && (
+        <p className="success-text" role="status">
+          {status}
+        </p>
+      )}
       <p className="panel-note">
         <strong>When to use:</strong> simple forms without a dedicated form library.
         <br />

package/templates/src/main.tsx.ejs

@@ -1,7 +1,7 @@
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
-import { AppProviders } from '@/app/providers';
-import { App } from '@/app/App';
+import { AppProviders } from '@/providers';
+import { App } from '@/App';
 import { initMonitoring } from '@/lib/monitoring';
 import '@/styles/global.<%= styling === 'sass' && uiLibrary !== 'shadcn' ? 'scss' : 'css' %>';
 

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

@@ -24,7 +24,6 @@ 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({
@@ -89,5 +88,5 @@ export function AppProviders({ children }<% if (isTypeScript) { %>: AppProviders
   tree = <ChakraProvider value={defaultSystem}>{tree}</ChakraProvider>;
 <% } -%>
 
-  return <ToastProvider>{tree}</ToastProvider>;
+  return <>{tree}</>;
 }

package/templates/src/routes/AboutPage.tsx.ejs

@@ -4,26 +4,27 @@ export function AboutPage() {
       <h1>About this starter</h1>
       <p>
         Generated with <strong>create-react-starter-kit</strong> using a scalable{' '}
-        <strong>feature-based</strong> layout (domain modules under <code>src/features</code>) —
-        the same organizational approach used across large production React codebases.
+        <strong>feature-based</strong> layout (domain modules under <code>src/features</code>).
       </p>
       <ul className="about-list">
         <li>
-          <strong>Extend features</strong> under <code>src/features/&lt;name&gt;/</code> — keep
-          domain logic close to the UI that owns it.
+          <strong>Routes:</strong> <code>/</code>, <code>/counter</code>, <code>/posts</code>,{' '}
+          <code>/feedback</code>, <code>/about</code>
         </li>
         <li>
-          <strong>Shared primitives</strong> live in <code>src/components/</code> and{' '}
-          <code>src/lib/</code>. Prefer imports via the <code>@/</code> path alias.
+          <strong>Extend features</strong> under <code>src/features/&lt;name&gt;/</code>.
         </li>
         <li>
-          <strong>Docs</strong> in <code>docs/</code> explain architecture, testing, and production
-          habits for this stack.
+          <strong>Shared UI</strong> lives in <code>src/components/</code>. Prefer the{' '}
+          <code>@/</code> path alias.
+        </li>
+        <li>
+          <strong>Bootstrap</strong> is in <code>src/main.<%= jsxExt %></code> with providers in{' '}
+          <code>src/providers.<%= jsxExt %></code> and routing in <code>src/App.<%= jsxExt %></code>.
         </li>
       </ul>
       <p>
-        Prefer reading <code>docs/getting-started.md</code> next, then{' '}
-        <code>docs/selected-stack.md</code> for library-specific guidance.
+        Read <code>docs/getting-started.md</code> next, then <code>docs/selected-stack.md</code>.
       </p>
     </div>
   );

package/templates/src/routes/CounterPage.tsx.ejs

@@ -0,0 +1,17 @@
+import { CounterPanel } from '@/features/counter/CounterPanel';
+
+export function CounterPage() {
+  return (
+    <div className="page">
+      <header className="page-intro">
+        <p className="eyebrow">Client state</p>
+        <h1>Counter</h1>
+        <p className="lede">
+          Interactive counter wired to <strong><%= stackLabels.stateManagement %></strong>. Use this
+          pattern for UI state that is not server cache.
+        </p>
+      </header>
+      <CounterPanel />
+    </div>
+  );
+}

package/templates/src/routes/FeedbackPage.tsx.ejs

@@ -0,0 +1,21 @@
+import { FeedbackForm } from '@/features/feedback/FeedbackForm';
+
+export function FeedbackPage() {
+  return (
+    <div className="page">
+      <header className="page-intro">
+        <p className="eyebrow">Forms</p>
+        <h1>Feedback</h1>
+        <p className="lede">
+          Submit demo feedback with <strong><%= stackLabels.forms %></strong>
+<% if (validation !== 'none') { -%>
+          {' '}
+          and <strong><%= stackLabels.validation %></strong> validation
+<% } -%>
+          .
+        </p>
+      </header>
+      <FeedbackForm />
+    </div>
+  );
+}

package/templates/src/routes/HomePage.tsx.ejs

@@ -1,29 +1,45 @@
-import { CounterPanel } from '@/features/counter/CounterPanel';
-import { PostsPanel } from '@/features/posts/PostsPanel';
-import { FeedbackForm } from '@/features/feedback/FeedbackForm';
+<% if (router === 'react-router') { -%>
+import { Link } from 'react-router-dom';
+<% } else { -%>
+import { Link } from '@tanstack/react-router';
+<% } -%>
 import { StackBadge } from '@/components/StackBadge';
-import { useToast } from '@/components/ui/Toast';
-import { UiButton } from '@/components/ui/UiButton';
 
-export function HomePage() {
-  const { push } = useToast();
+const demos = [
+  {
+    to: '/counter',
+    title: 'Counter',
+    body: 'Client state demo with <%= stackLabels.stateManagement %>.',
+  },
+  {
+    to: '/posts',
+    title: 'Posts',
+    body: 'Server state / data fetching with <%= stackLabels.serverState %>.',
+  },
+  {
+    to: '/feedback',
+    title: 'Feedback',
+    body: 'Forms and validation with <%= stackLabels.forms %><% if (validation !== 'none') { %> + <%= stackLabels.validation %><% } %>.',
+  },
+] as const;
 
+export function HomePage() {
   return (
     <div className="page home-page">
       <section className="hero">
         <p className="eyebrow">Starter workspace</p>
         <h1><%= projectName %></h1>
         <p className="lede">
-          A minimal, production-shaped React app wired for your selected stack. Explore the panels
-          below — each one is a real usage example, not a placeholder.
+          A production-shaped React starter. Open each demo route to explore client state, server
+          data, and forms — each page is a real working example for your selected stack.
         </p>
         <div className="hero-actions">
-          <UiButton onClick={() => push('Toast system is ready', 'success')}>
-            Show toast
-          </UiButton>
-          <a className="text-link" href="/about">
-            Read about the stack →
-          </a>
+          <Link className="ui-button" to="/counter">
+            Open counter demo
+          </Link>
+          <Link className="text-link" to="/about">
+            About this starter →
+          </Link>
         </div>
         <div className="stack-row">
           <StackBadge label="Build" value="<%= stackLabels.buildTool %>" />
@@ -35,12 +51,18 @@ export function HomePage() {
         </div>
       </section>
 
-      <section className="panels">
-<% if (stateManagement !== 'none') { -%>
-        <CounterPanel />
-<% } -%>
-        <PostsPanel />
-        <FeedbackForm />
+      <section className="panels" aria-label="Demo routes">
+        {demos.map((demo) => (
+          <article key={demo.to} className="panel">
+            <header className="panel-header">
+              <h2>{demo.title}</h2>
+              <p>{demo.body}</p>
+            </header>
+            <Link className="text-link" to={demo.to}>
+              Go to {demo.title.toLowerCase()} →
+            </Link>
+          </article>
+        ))}
       </section>
     </div>
   );

package/templates/src/routes/PostsPage.tsx.ejs

@@ -0,0 +1,17 @@
+import { PostsPanel } from '@/features/posts/PostsPanel';
+
+export function PostsPage() {
+  return (
+    <div className="page">
+      <header className="page-intro">
+        <p className="eyebrow">Server state</p>
+        <h1>Posts</h1>
+        <p className="lede">
+          Fetches sample posts via <strong><%= stackLabels.serverState === 'None' ? stackLabels.apiLayer : stackLabels.serverState %></strong>{' '}
+          and <strong><%= stackLabels.apiLayer %></strong>.
+        </p>
+      </header>
+      <PostsPanel />
+    </div>
+  );
+}