create-top-secret-starter 0.2.1 → 0.3.0

package/index.js

@@ -230,8 +230,9 @@ const applyBackendOverlay = () => {
     pkg.devDependencies = Object.fromEntries(
       Object.entries(pkg.devDependencies).sort(([a], [b]) => a.localeCompare(b))
     )
-    // lint and format run once, from the workspace root
-    for (const script of ['lint', 'lint:fix', 'format', 'format:check']) delete pkg.scripts[script]
+    // lint, format and verify run once, from the workspace root
+    for (const script of ['lint', 'lint:fix', 'format', 'format:check', 'verify'])
+      delete pkg.scripts[script]
     delete pkg.trustedDependencies
   })
 
@@ -287,6 +288,7 @@ if (backend) {
   restoreGitignore(targetDir)
   editJson(path.join(targetDir, 'package.json'), pkg => {
     pkg.name = name
+    if (pm !== 'bun') pkg.scripts.verify = pkg.scripts.verify.replaceAll('bun run', `${pm} run`)
   })
   // textual edits: re-serialising would break the oxfmt style the project enforces
   if (pm !== 'bun') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-top-secret-starter",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Scaffold a Vite + React 19 + TypeScript + shadcn starter with TanStack Router",
   "keywords": [
     "create",

package/templates/template-router/.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-router/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-router/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-router/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-router/src/api/auth/guards.ts

@@ -2,8 +2,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().
-
 export const requireSession = (location: { href: string }) => {
   if (!sessionStore.get()) {
     throw redirect({ to: '/sign-in', search: { redirect: location.href } })

package/templates/template-router/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-router/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-router/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-router/src/api/auth/session-store.ts

@@ -1,51 +1,29 @@
-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
-  }
-}
-
-let current = parseRaw(localStorage.getItem(KEY))
-const listeners = new Set<Listener>()
-
-const notify = () => listeners.forEach(l => l(current))
-
-const commit = (next: Session | null) => {
-  current = next
-  if (next) localStorage.setItem(KEY, JSON.stringify(next))
-  else localStorage.removeItem(KEY)
-  notify()
-}
-
-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)
+export const useSession = () => useStorageStore(store)

package/templates/template-router/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-router/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-router/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-router/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-router/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)
 })

package/templates/template-router/src/providers/theme.tsx

@@ -1,5 +1,7 @@
 import type { PropsWithChildren } from 'react'
-import { createContext, use, useEffect, useSyncExternalStore } from 'react'
+import { createContext, use, useEffect } from 'react'
+
+import { createStorageStore, useStorageStore } from '@/lib/storage-store'
 
 export type Theme = 'dark' | 'light' | 'system'
 
@@ -16,30 +18,12 @@ const isTheme = (value: unknown): value is Theme =>
 
 const ThemeProviderContext = createContext<ThemeProviderState | null>(null)
 
-const listeners = new Set<() => void>()
-
-const readTheme = (): Theme => {
-  const stored = localStorage.getItem(THEME_STORAGE_KEY)
-  return isTheme(stored) ? stored : DEFAULT_THEME
-}
-
-// `storage` fires only in other tabs; same-tab writes go through `listeners`.
-const subscribe = (listener: () => void) => {
-  listeners.add(listener)
-  const onStorage = (e: StorageEvent) => {
-    if (e.key === THEME_STORAGE_KEY) listener()
-  }
-  window.addEventListener('storage', onStorage)
-  return () => {
-    listeners.delete(listener)
-    window.removeEventListener('storage', onStorage)
-  }
-}
-
-const writeTheme = (next: Theme) => {
-  localStorage.setItem(THEME_STORAGE_KEY, next)
-  listeners.forEach(l => l())
-}
+const themeStore = createStorageStore<Theme>({
+  key: THEME_STORAGE_KEY,
+  fallback: DEFAULT_THEME,
+  decode: raw => (isTheme(raw) ? raw : DEFAULT_THEME),
+  encode: theme => theme
+})
 
 const resolveTheme = (theme: Theme): 'dark' | 'light' => {
   if (theme !== 'system') return theme
@@ -60,7 +44,7 @@ const applyTheme = (theme: Theme) => {
 }
 
 export const ThemeProvider = ({ children }: PropsWithChildren) => {
-  const theme = useSyncExternalStore(subscribe, readTheme, () => DEFAULT_THEME)
+  const theme = useStorageStore(themeStore)
 
   useEffect(() => {
     applyTheme(theme)
@@ -73,7 +57,9 @@ export const ThemeProvider = ({ children }: PropsWithChildren) => {
   }, [theme])
 
   return (
-    <ThemeProviderContext value={{ theme, setTheme: writeTheme }}>{children}</ThemeProviderContext>
+    <ThemeProviderContext value={{ theme, setTheme: themeStore.set }}>
+      {children}
+    </ThemeProviderContext>
   )
 }
 

package/templates/template-router/src/routes/-error.tsx

@@ -1,34 +1,50 @@
 import type { ErrorComponentProps } from '@tanstack/react-router'
 import { RotateCcw, TriangleAlert } 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 ErrorPage = ({ error, reset }: ErrorComponentProps) => {
   const message = error instanceof Error ? error.message : String(error)
 
   return (
-    <StatusPage
-      code='500'
-      icon={<TriangleAlert />}
-      mediaClassName='bg-destructive/10 text-destructive'
-      title='Something went wrong'
-      description='An unexpected error occurred. You can try again, or head back home.'
-      actions={
-        <>
-          <BackHomeButton variant='outline' />
-          <Button onClick={reset}>
-            <RotateCcw data-icon='inline-start' />
-            Try again
-          </Button>
-        </>
-      }
-    >
-      {import.meta.env.DEV && message && (
-        <pre className='text-muted-foreground bg-muted mt-2 max-h-40 w-full overflow-auto rounded-lg border p-3 text-left font-mono text-xs whitespace-pre-wrap'>
-          {message}
-        </pre>
-      )}
-    </StatusPage>
+    <main className='flex min-h-svh items-center justify-center p-6'>
+      <Empty className='max-w-md border-none'>
+        <EmptyHeader>
+          <EmptyMedia variant='icon'>
+            <TriangleAlert className='text-destructive' />
+          </EmptyMedia>
+          <span className='text-muted-foreground font-mono text-xs tracking-widest tabular-nums'>
+            500
+          </span>
+          <EmptyTitle>Something went wrong</EmptyTitle>
+          <EmptyDescription>
+            An unexpected error occurred. You can try again, or head back home.
+          </EmptyDescription>
+        </EmptyHeader>
+        <EmptyContent>
+          <div className='grid w-full grid-cols-2 gap-2'>
+            <BackHomeButton variant='outline' />
+            <Button onClick={reset}>
+              <RotateCcw data-icon='inline-start' />
+              Try again
+            </Button>
+          </div>
+          {import.meta.env.DEV && message && (
+            <pre className='text-muted-foreground bg-muted mt-2 max-h-40 w-full overflow-auto rounded-lg border p-3 text-left font-mono text-xs whitespace-pre-wrap'>
+              {message}
+            </pre>
+          )}
+        </EmptyContent>
+      </Empty>
+    </main>
   )
 }