create-top-secret-starter 0.2.1 → 0.3.0

package/templates/template-router/src/routes/-not-found.tsx

@@ -1,27 +1,45 @@
 import { useRouter } from '@tanstack/react-router'
 import { ArrowLeft, SearchX } from 'lucide-react'
 
-import { BackHomeButton, StatusPage } from '@/components/status-page'
+import { BackHomeButton } from '@/components/back-home-button'
 import { Button } from '@/components/ui/button'
+import {
+  Empty,
+  EmptyContent,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle
+} from '@/components/ui/empty'
 
 export const NotFoundPage = () => {
   const router = useRouter()
 
   return (
-    <StatusPage
-      code='404'
-      icon={<SearchX />}
-      title='Page not found'
-      description='The page you’re looking for doesn’t exist or may have been moved.'
-      actions={
-        <>
-          <Button variant='outline' onClick={() => router.history.back()}>
-            <ArrowLeft data-icon='inline-start' />
-            Go back
-          </Button>
-          <BackHomeButton />
-        </>
-      }
-    />
+    <main className='flex min-h-svh items-center justify-center p-6'>
+      <Empty className='max-w-md border-none'>
+        <EmptyHeader>
+          <EmptyMedia variant='icon'>
+            <SearchX />
+          </EmptyMedia>
+          <span className='text-muted-foreground font-mono text-xs tracking-widest tabular-nums'>
+            404
+          </span>
+          <EmptyTitle>Page not found</EmptyTitle>
+          <EmptyDescription>
+            The page you’re looking for doesn’t exist or may have been moved.
+          </EmptyDescription>
+        </EmptyHeader>
+        <EmptyContent>
+          <div className='grid w-full grid-cols-2 gap-2'>
+            <Button variant='outline' onClick={() => router.history.back()}>
+              <ArrowLeft data-icon='inline-start' />
+              Go back
+            </Button>
+            <BackHomeButton />
+          </div>
+        </EmptyContent>
+      </Empty>
+    </main>
   )
 }

package/templates/template-router/src/routes/sign-in.tsx

@@ -24,11 +24,6 @@ const DEMO_CREDENTIALS: Credentials = import.meta.env.DEV
   ? { email: 'demo@example.com', password: 'demo1234' }
   : { email: '', password: '' }
 
-const FIELDS = [
-  { name: 'email', label: 'Email', type: 'email', autoComplete: 'email' },
-  { name: 'password', label: 'Password', type: 'password', autoComplete: 'current-password' }
-] as const
-
 export const Route = createFileRoute('/sign-in')({
   validateSearch: searchSchema,
   beforeLoad: ({ search }) => redirectIfAuthenticated(search),
@@ -40,7 +35,11 @@ function SignInPage() {
   const { redirect: redirectTo } = Route.useSearch()
   const login = useLogin()
 
-  const { register, handleSubmit, formState } = useForm({
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting }
+  } = useForm({
     resolver: standardSchemaResolver(formSchema),
     defaultValues: DEMO_CREDENTIALS
   })
@@ -67,26 +66,34 @@ function SignInPage() {
             </div>
           )}
 
-          {FIELDS.map(field => {
-            const error = formState.errors[field.name]
-            return (
-              <Field key={field.name} data-invalid={Boolean(error)}>
-                <FieldLabel htmlFor={field.name}>{field.label}</FieldLabel>
-                <Input
-                  id={field.name}
-                  type={field.type}
-                  autoComplete={field.autoComplete}
-                  aria-invalid={Boolean(error)}
-                  aria-describedby={error ? `${field.name}-error` : undefined}
-                  {...register(field.name)}
-                />
-                <FieldError id={`${field.name}-error`} errors={[error]} />
-              </Field>
-            )
-          })}
+          <Field data-invalid={Boolean(errors.email)}>
+            <FieldLabel htmlFor='email'>Email</FieldLabel>
+            <Input
+              id='email'
+              type='email'
+              autoComplete='email'
+              aria-invalid={Boolean(errors.email)}
+              aria-describedby={errors.email ? 'email-error' : undefined}
+              {...register('email')}
+            />
+            <FieldError id='email-error' errors={[errors.email]} />
+          </Field>
+
+          <Field data-invalid={Boolean(errors.password)}>
+            <FieldLabel htmlFor='password'>Password</FieldLabel>
+            <Input
+              id='password'
+              type='password'
+              autoComplete='current-password'
+              aria-invalid={Boolean(errors.password)}
+              aria-describedby={errors.password ? 'password-error' : undefined}
+              {...register('password')}
+            />
+            <FieldError id='password-error' errors={[errors.password]} />
+          </Field>
 
-          <Button type='submit' disabled={formState.isSubmitting}>
-            {formState.isSubmitting ? 'Signing in…' : 'Sign in'}
+          <Button type='submit' disabled={isSubmitting}>
+            {isSubmitting ? 'Signing in…' : 'Sign in'}
           </Button>
         </FieldGroup>
       </form>

package/templates/template-start/.claude/hooks/stop-check.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Stop-hook gate: block finishing when the tree is red.
-# Runs the package scripts so the same commands work in the flat and the
+# Runs the package script so the same command works in the flat and the
 # workspace (apps/*) layout. Exit 2 blocks the turn and stderr becomes the
 # reason Claude reads; any other non-zero code is a silent no-op.
 set -uo pipefail
@@ -10,17 +10,8 @@ run="npm run"
 [ -f bun.lock ] && run="bun run"
 [ -f pnpm-lock.yaml ] && run="pnpm run"
 
-fail=0
-out=""
-for script in format:check typecheck lint test; do
-  if ! o=$($run "$script" 2>&1); then
-    fail=1
-    out+=$'\n'"=== $script ==="$'\n'"$o"$'\n'
-  fi
-done
-
-if [ "$fail" = "1" ]; then
-  printf 'checks failed — fix before finishing:\n%s' "$out" >&2
+if ! out=$($run verify 2>&1); then
+  printf 'verify failed — fix before finishing:\n%s' "$out" >&2
   exit 2
 fi
 exit 0

package/templates/template-start/CLAUDE.md

@@ -32,7 +32,9 @@ Don't write tests that merely restate the implementation — zero confidence val
 
 Package manager is **bun**; scripts are in `package.json`.
 
-A **Stop hook** (`.claude/hooks/stop-check.sh`) runs `format:check`, `typecheck`, `lint` and `test` before a turn can finish; a PostToolUse hook formats/lints every `.ts(x)` write. Don't hand-format to match — the hooks do it.
+**`bun run verify` is the single definition of green.** The Stop hook (`.claude/hooks/stop-check.sh`) runs it before a turn can finish — don't re-list the individual checks anywhere new.
+
+A PostToolUse hook formats/lints every `.ts(x)` write. Don't hand-format to match.
 
 ## Architecture
 
@@ -44,7 +46,9 @@ React 19 SPA with React Compiler on — no manual `useMemo`/`useCallback`.
 
 For how to add an API module, a form, a route or a UI primitive, use the **project-conventions** skill.
 
-The web app is **SPA-only**: `src/api/auth/session-store.ts` and the route guards touch `localStorage` and `document` at module load with no environment check. The TanStack Start template renders on the server, so SSR-safe copies of those two files live in `create-cli/start-overrides/` (and `backend-overlay/web-start/` for the backend variant) — change them together.
+Persisted state goes through `createStorageStore` in `src/lib/storage-store.ts` — the only module allowed to touch `localStorage`. It owns decoding, cross-tab sync and the SSR snapshot, so `session-store.ts` and the theme store work unchanged on the TanStack Start template's server runtime.
+
+Route guards are the remaining SPA-only code: they redirect on a session the server cannot see. SSR-safe copies live in `create-cli/start-overrides/` (and `backend-overlay/web-start/` for the backend variant) — change them together.
 
 Dev-only code must put `import.meta.env.DEV` **first** in the condition so Vite drops the branch at build time. `mocksEnabled` alone is a runtime value and would still ship the mock backend as a lazy chunk.
 

package/templates/template-start/doctor.config.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://react.doctor/schema/config.json",
+  "ignore": {
+    "files": ["src/components/ui/**", "src/routeTree.gen.ts"],
+    "overrides": [
+      {
+        "files": ["src/routes/**"],
+        "rules": ["react-doctor/only-export-components"]
+      },
+      {
+        "files": ["src/api/auth/session-store.ts"],
+        "rules": ["react-doctor/client-localstorage-no-version"]
+      }
+    ]
+  }
+}

package/templates/template-start/package.json

@@ -9,10 +9,12 @@
     "lint": "oxlint",
     "lint:fix": "oxlint --fix",
     "typecheck": "tsc -b",
+    "doctor": "react-doctor . --no-score --no-supply-chain --blocking error",
     "test": "vitest run",
     "format": "oxfmt",
     "format:check": "oxfmt --check",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "verify": "bun run format:check && bun run lint && bun run typecheck && bun run doctor && bun run test"
   },
   "dependencies": {
     "@base-ui/react": "^1.7.0",
@@ -46,6 +48,7 @@
     "happy-dom": "^20.13.2",
     "oxfmt": "0.66.0",
     "oxlint": "^1.81.0",
+    "react-doctor": "^0.9.13",
     "shadcn": "^4.20.1",
     "tailwindcss": "^4.3.3",
     "typescript": "^7.0.2",

package/templates/template-start/src/api/auth/guards.ts

@@ -3,8 +3,6 @@ import { redirect } from '@tanstack/react-router'
 
 import { sessionStore } from '@/api/auth/session-store'
 
-// `beforeLoad` runs outside React, so guards read the store directly instead of useSession().
-
 // Under SSR the session is unknowable (it lives in localStorage), so a server-side
 // redirect would be wrong for signed-in users. Guards defer to the client: they
 // no-op on the server and run again during hydration, where the session is real.

package/templates/template-start/src/api/auth/index.ts

@@ -21,7 +21,13 @@ export const logout = async () => {
 
 export const fetchMe = () => api.get('auth/me').json(UserSchema)
 
-export const useLogin = () => useMutation({ mutationFn: login })
+export const useLogin = () => {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: login,
+    onSuccess: () => queryClient.clear()
+  })
+}
 
 export const useLogout = () => {
   const queryClient = useQueryClient()

package/templates/template-start/src/api/auth/router-bridge.ts

@@ -4,8 +4,8 @@ import { sessionStore } from '@/api/auth/session-store'
 // re-run them. Token rotation also notifies, but must not restart loaders.
 export const invalidateOnAuthChange = (router: { invalidate: () => Promise<void> }) => {
   let signedIn = sessionStore.get() !== null
-  sessionStore.subscribe(session => {
-    if ((session !== null) === signedIn) return
+  sessionStore.subscribe(() => {
+    if ((sessionStore.get() !== null) === signedIn) return
     signedIn = !signedIn
     void router.invalidate()
   })

package/templates/template-start/src/api/auth/session-store.test.ts

@@ -42,7 +42,7 @@ describe('cross-tab sync', () => {
     )
 
     expect(store.get()?.user.id).toBe('u_1')
-    expect(listener).toHaveBeenCalledWith(expect.objectContaining({ accessToken: 'access' }))
+    expect(listener).toHaveBeenCalled()
   })
 
   it('drops the session when another tab signs out', async () => {

package/templates/template-start/src/api/auth/session-store.ts

@@ -1,62 +1,29 @@
-// Start override: this module also loads on the SSR runtime, where `localStorage`
-// does not exist. The SPA version reads it at module load and never guards.
-import { useSyncExternalStore } from 'react'
-
 import { SessionSchema, type Session, type Tokens } from '@/api/auth/schema'
-
-const KEY = 'session'
-
-type Listener = (session: Session | null) => void
-
-const parseRaw = (raw: string | null): Session | null => {
-  try {
-    return raw ? SessionSchema.parse(JSON.parse(raw)) : null
-  } catch {
-    return null
-  }
-}
-
-// The session lives in localStorage, so it exists only in the browser. During SSR
-// (TanStack Start) this module still gets imported by route guards: there the
-// session is always null and writes are impossible — auth resolves after hydration.
-const isBrowser = typeof window !== 'undefined'
-
-let current = isBrowser ? parseRaw(localStorage.getItem(KEY)) : null
-const listeners = new Set<Listener>()
-
-const notify = () => listeners.forEach(l => l(current))
-
-const commit = (next: Session | null) => {
-  if (!isBrowser) throw new Error('Session can only change in the browser')
-  current = next
-  if (next) localStorage.setItem(KEY, JSON.stringify(next))
-  else localStorage.removeItem(KEY)
-  notify()
-}
-
-if (isBrowser) {
-  window.addEventListener('storage', e => {
-    if (e.key !== KEY) return
-    current = parseRaw(e.newValue)
-    notify()
-  })
-}
+import { createStorageStore, useStorageStore } from '@/lib/storage-store'
+
+const store = createStorageStore<Session | null>({
+  key: 'session',
+  fallback: null,
+  decode: raw => {
+    try {
+      return raw ? SessionSchema.parse(JSON.parse(raw)) : null
+    } catch {
+      return null
+    }
+  },
+  encode: session => (session ? JSON.stringify(session) : null)
+})
 
 export const sessionStore = {
-  get: () => current,
-  set: (next: Session) => commit(next),
-  clear: () => commit(null),
+  get: store.get,
+  subscribe: store.subscribe,
+  set: (next: Session) => store.set(next),
+  clear: () => store.set(null),
   updateTokens: (tokens: Tokens) => {
+    const current = store.get()
     if (!current) throw new Error('Cannot update tokens: no active session')
-    commit({ ...current, ...tokens })
-  },
-  subscribe: (listener: Listener) => {
-    listeners.add(listener)
-    return () => {
-      listeners.delete(listener)
-    }
+    store.set({ ...current, ...tokens })
   }
 }
 
-export const useSession = () =>
-  useSyncExternalStore(sessionStore.subscribe, sessionStore.get, () => null)
+export const useSession = () => useStorageStore(store)

package/templates/template-start/src/components/back-home-button.tsx

@@ -0,0 +1,17 @@
+import type { VariantProps } from 'class-variance-authority'
+import { Link } from '@tanstack/react-router'
+import { House } from 'lucide-react'
+
+import { buttonVariants } from '@/components/ui/button'
+
+// not `<Button render={<Link/>}>`: Base UI's role="button" strips link semantics
+export const BackHomeButton = ({
+  variant = 'default'
+}: {
+  variant?: VariantProps<typeof buttonVariants>['variant']
+}) => (
+  <Link to='/' className={buttonVariants({ variant })}>
+    <House data-icon='inline-start' />
+    Back home
+  </Link>
+)

package/templates/template-start/src/env.ts

@@ -2,8 +2,7 @@ import * as z from 'zod/mini'
 
 const envSchema = z.object({
   // trailing slash required: `new URL(path, baseUrl)` drops the base's last segment without it
-  VITE_API_URL: z._default(z.string().check(z.minLength(1), z.endsWith('/')), '/api/'),
-  VITE_ENABLE_MOCKS: z._default(z.enum(['true', 'false']), 'true')
+  VITE_API_URL: z._default(z.string().check(z.minLength(1), z.endsWith('/')), '/api/')
 })
 
 const parsed = envSchema.safeParse(import.meta.env)
@@ -16,4 +15,4 @@ if (!parsed.success) {
 
 export const env = parsed.data
 
-export const mocksEnabled = import.meta.env.DEV && env.VITE_ENABLE_MOCKS === 'true'
+export const mocksEnabled = import.meta.env.DEV && import.meta.env.VITE_ENABLE_MOCKS !== 'false'

package/templates/template-start/src/lib/single-flight.test.ts

@@ -1,40 +1,5 @@
 import { singleFlight } from '@/lib/single-flight'
 
-const deferred = <T>() => {
-  let resolve!: (value: T) => void
-  let reject!: (reason?: unknown) => void
-  const promise = new Promise<T>((res, rej) => {
-    resolve = res
-    reject = rej
-  })
-  return { promise, resolve, reject }
-}
-
-it('collapses concurrent calls into a single in-flight invocation', async () => {
-  const d = deferred<number>()
-  const fn = vi.fn(() => d.promise)
-  const wrapped = singleFlight(fn)
-
-  const a = wrapped()
-  const b = wrapped()
-
-  expect(fn).toHaveBeenCalledTimes(1)
-  expect(a).toBe(b)
-
-  d.resolve(42)
-  await expect(a).resolves.toBe(42)
-})
-
-it('re-invokes after the previous call settles', async () => {
-  const fn = vi.fn(() => Promise.resolve('ok'))
-  const wrapped = singleFlight(fn)
-
-  await wrapped()
-  await wrapped()
-
-  expect(fn).toHaveBeenCalledTimes(2)
-})
-
 it('clears the pending slot on rejection so the next call retries', async () => {
   const fn = vi
     .fn<() => Promise<string>>()
@@ -44,5 +9,4 @@ it('clears the pending slot on rejection so the next call retries', async () =>
 
   await expect(wrapped()).rejects.toThrow('boom')
   await expect(wrapped()).resolves.toBe('recovered')
-  expect(fn).toHaveBeenCalledTimes(2)
 })

package/templates/template-start/src/lib/storage-store.ts

@@ -0,0 +1,61 @@
+import { useSyncExternalStore } from 'react'
+
+// The TanStack Start template imports these stores on the SSR runtime, where
+// `localStorage` does not exist: there the value is the fallback and writes throw.
+const isBrowser = typeof window !== 'undefined'
+
+export type StorageStore<T> = {
+  get: () => T
+  set: (next: T) => void
+  subscribe: (listener: () => void) => () => void
+  getServerSnapshot: () => T
+}
+
+type Options<T> = {
+  key: string
+  fallback: T
+  decode: (raw: string | null) => T
+  /** `null` removes the key */
+  encode: (value: T) => string | null
+}
+
+export const createStorageStore = <T>({
+  key,
+  fallback,
+  decode,
+  encode
+}: Options<T>): StorageStore<T> => {
+  let current = isBrowser ? decode(localStorage.getItem(key)) : fallback
+  const listeners = new Set<() => void>()
+  const notify = () => listeners.forEach(listener => listener())
+
+  if (isBrowser) {
+    window.addEventListener('storage', event => {
+      if (event.key !== key) return
+      current = decode(event.newValue)
+      notify()
+    })
+  }
+
+  return {
+    get: () => current,
+    set: next => {
+      if (!isBrowser) throw new Error(`"${key}" can only change in the browser`)
+      current = next
+      const raw = encode(next)
+      if (raw === null) localStorage.removeItem(key)
+      else localStorage.setItem(key, raw)
+      notify()
+    },
+    subscribe: listener => {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    getServerSnapshot: () => fallback
+  }
+}
+
+export const useStorageStore = <T>(store: StorageStore<T>) =>
+  useSyncExternalStore(store.subscribe, store.get, store.getServerSnapshot)

package/templates/template-start/src/providers/theme.test.tsx

@@ -1,13 +1,25 @@
-import { render, screen } from '@testing-library/react'
+import { fireEvent, render, screen } from '@testing-library/react'
 import { act } from 'react'
-import { beforeEach, expect, it } from 'vitest'
+import { beforeEach, expect, it, vi } from 'vitest'
 
-import { ThemeProvider, useTheme } from '@/providers/theme'
-
-const Probe = () => <span data-testid='theme'>{useTheme().theme}</span>
+// the store reads localStorage at load, so each case needs a fresh import
+const load = async () => {
+  vi.resetModules()
+  return await import('@/providers/theme')
+}
 
 const theme = () => screen.getByTestId('theme').textContent
 
+const renderProbe = async () => {
+  const { ThemeProvider, useTheme } = await load()
+  const Probe = () => <span data-testid='theme'>{useTheme().theme}</span>
+  render(
+    <ThemeProvider>
+      <Probe />
+    </ThemeProvider>
+  )
+}
+
 const writeFromAnotherTab = (value: string | null) =>
   act(() => {
     if (value === null) localStorage.removeItem('ui-theme')
@@ -20,33 +32,23 @@ beforeEach(() => {
   document.documentElement.classList.remove('dark')
 })
 
-it('adopts the stored theme on mount', () => {
+it('adopts the stored theme on mount', async () => {
   localStorage.setItem('ui-theme', 'dark')
-  render(
-    <ThemeProvider>
-      <Probe />
-    </ThemeProvider>
-  )
+  await renderProbe()
+
   expect(theme()).toBe('dark')
   expect(document.documentElement.classList.contains('dark')).toBe(true)
 })
 
-it('falls back to system for a value it does not recognise', () => {
+it('falls back to system for a value it does not recognise', async () => {
   localStorage.setItem('ui-theme', 'neon')
-  render(
-    <ThemeProvider>
-      <Probe />
-    </ThemeProvider>
-  )
+  await renderProbe()
+
   expect(theme()).toBe('system')
 })
 
-it('follows a theme change made in another tab', () => {
-  render(
-    <ThemeProvider>
-      <Probe />
-    </ThemeProvider>
-  )
+it('follows a theme change made in another tab', async () => {
+  await renderProbe()
   expect(theme()).toBe('system')
 
   writeFromAnotherTab('dark')
@@ -55,17 +57,24 @@ it('follows a theme change made in another tab', () => {
   expect(document.documentElement.classList.contains('dark')).toBe(true)
 })
 
-it('ignores cross-tab writes to unrelated keys', () => {
-  localStorage.setItem('ui-theme', 'dark')
+it('applies a theme picked in this tab', async () => {
+  const { ThemeProvider, useTheme } = await load()
+  const Toggle = () => {
+    const { theme, setTheme } = useTheme()
+    return (
+      <button type='button' onClick={() => setTheme('dark')}>
+        {theme}
+      </button>
+    )
+  }
   render(
     <ThemeProvider>
-      <Probe />
+      <Toggle />
     </ThemeProvider>
   )
 
-  act(() => {
-    window.dispatchEvent(new StorageEvent('storage', { key: 'session', newValue: null }))
-  })
+  fireEvent.click(screen.getByRole('button'))
 
-  expect(theme()).toBe('dark')
+  expect(screen.getByRole('button')).toHaveTextContent('dark')
+  expect(document.documentElement.classList.contains('dark')).toBe(true)
 })