create-top-secret-starter 0.2.1 → 0.4.0

package/index.js

@@ -84,7 +84,7 @@ if (router && !ROUTERS.includes(router)) {
 }
 router ??= must(
   await select({
-    message: 'Routing?',
+    message: 'Router?',
     options: [
       { value: 'router', label: ROUTER_LABELS.router, hint: 'SPA' },
       { value: 'start', label: ROUTER_LABELS.start, hint: 'SSR, full-stack' }
@@ -158,7 +158,7 @@ const restoreGitignore = dir => {
   const src = path.join(dir, '_gitignore')
   if (fs.existsSync(src)) fs.renameSync(src, path.join(dir, '.gitignore'))
 }
-const patchFile = (file, fn) => fs.writeFileSync(file, fn(fs.readFileSync(file, 'utf8')))
+const editFile = (file, fn) => fs.writeFileSync(file, fn(fs.readFileSync(file, 'utf8')))
 // The api source keeps Redis-only code between `redis:start` / `redis:end` marker
 // comments, so one source tree serves both answers to the Redis prompt.
 const REDIS_MARKER = /^[ \t]*(\/\/|#|<!--) redis:(start|end)( -->)?\n/gm
@@ -168,7 +168,7 @@ const REDIS_BLOCK =
 const HOLE = '__REDIS_HOLE__'
 
 const applyRedisMarkers = (file, keep) =>
-  patchFile(file, source =>
+  editFile(file, source =>
     source
       .replace(keep ? REDIS_MARKER : REDIS_BLOCK, HOLE)
       // dropping the last entry of an object or call leaves a dangling comma
@@ -209,7 +209,7 @@ const applyBackendOverlay = () => {
   fs.rmSync(path.join(webDir, '_gitignore'), { force: true })
 
   // dev proxy: same origin for the session cookie
-  patchFile(path.join(webDir, 'vite.config.ts'), source =>
+  editFile(path.join(webDir, 'vite.config.ts'), source =>
     source.replace(
       'export default defineConfig({\n',
       "export default defineConfig({\n  server: { proxy: { '/api': 'http://localhost:3000' } },\n"
@@ -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
   })
 
@@ -252,7 +253,7 @@ const applyBackendOverlay = () => {
   for (const file of ['.claude', '.mcp.json', 'CLAUDE.md']) {
     fs.renameSync(path.join(webDir, file), path.join(targetDir, file))
   }
-  patchFile(
+  editFile(
     path.join(targetDir, 'CLAUDE.md'),
     source =>
       source
@@ -265,7 +266,7 @@ const applyBackendOverlay = () => {
     const dest = path.join(targetDir, file)
     fs.renameSync(path.join(webDir, file), dest)
     // textual edit: re-serialising would break the oxfmt style the file itself enforces
-    patchFile(dest, source => source.replaceAll('"src/', '"apps/web/src/'))
+    editFile(dest, source => source.replaceAll('"src/', '"apps/web/src/'))
   }
   editJson(path.join(targetDir, 'package.json'), pkg => {
     pkg.name = name
@@ -277,7 +278,7 @@ const applyBackendOverlay = () => {
     'README.md',
     path.join('apps', 'web', 'src', 'routes', '_authenticated', 'index.tsx')
   ]) {
-    patchFile(path.join(targetDir, file), source => source.replaceAll('PLACEHOLDER', name))
+    editFile(path.join(targetDir, file), source => source.replaceAll('PLACEHOLDER', name))
   }
 }
 
@@ -287,14 +288,15 @@ 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') {
-    patchFile(path.join(targetDir, '.claude', 'launch.json'), source =>
+    editFile(path.join(targetDir, '.claude', 'launch.json'), source =>
       source.replace('"runtimeExecutable": "bun"', `"runtimeExecutable": "${pm}"`)
     )
     // MCP servers start through the pm's package runner
-    patchFile(path.join(targetDir, '.mcp.json'), source =>
+    editFile(path.join(targetDir, '.mcp.json'), source =>
       pm === 'pnpm'
         ? source
             .replaceAll('"command": "bunx"', '"command": "pnpm"')

package/package.json

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

package/templates/template-api/CLAUDE.md

@@ -5,7 +5,7 @@ root `verify` covers it. Tests run on PGlite with the committed migrations — n
 server needed.
 
 - Feature layout per [Elysia best practices](https://elysiajs.com/essential/best-practice):
-  `src/modules/<feature>/{index,service,model}.ts` — controller / plain static-class
+  `src/modules/<feature>/{index,service,model}.ts` — controller / plain factory
   service / `t` schemas. Services never touch `Context`; one Elysia instance is one
   controller.
 - `src/app.ts` is the Eden boundary: no Bun globals, no `process.env`, deps injected

package/templates/template-api/drizzle/0000_damp_taskmaster.sql

@@ -57,7 +57,7 @@ CREATE TABLE "verification" (
 ALTER TABLE "note" ADD CONSTRAINT "note_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "account" ADD CONSTRAINT "account_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "session" ADD CONSTRAINT "session_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-CREATE INDEX "note_userId_idx" ON "note" USING btree ("user_id");--> statement-breakpoint
+CREATE INDEX "note_user_id_idx" ON "note" USING btree ("user_id");--> statement-breakpoint
 CREATE UNIQUE INDEX "account_issuer_accountId_uidx" ON "account" USING btree ("issuer","account_id");--> statement-breakpoint
 CREATE INDEX "account_userId_idx" ON "account" USING btree ("user_id");--> statement-breakpoint
 CREATE INDEX "session_userId_idx" ON "session" USING btree ("user_id");--> statement-breakpoint

package/templates/template-api/drizzle/meta/0000_snapshot.json

@@ -35,8 +35,8 @@
         }
       },
       "indexes": {
-        "note_userId_idx": {
-          "name": "note_userId_idx",
+        "note_user_id_idx": {
+          "name": "note_user_id_idx",
           "columns": [
             {
               "expression": "user_id",

package/templates/template-api/package.json

@@ -32,6 +32,6 @@
     "@types/bun": "^1.4.0",
     "drizzle-kit": "^0.31.10",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
   }
 }

package/templates/template-api/src/app.test.ts

@@ -111,7 +111,7 @@ describe('notes', () => {
     expect(own.status).toBe(204)
   })
 
-  it('validates the body', async () => {
+  it('rejects a note without a title', async () => {
     const cookie = await signUp('carol@example.com')
     const res = await json('/api/notes', { method: 'POST', cookie, body: JSON.stringify({}) })
     expect(res.status).toBe(422)

package/templates/template-api/src/db/schema.ts

@@ -17,5 +17,5 @@ export const note = pgTable(
       .references(() => user.id, { onDelete: 'cascade' }),
     createdAt: timestamp('created_at').defaultNow().notNull()
   },
-  table => [index('note_userId_idx').on(table.userId)]
+  table => [index('note_user_id_idx').on(table.userId)]
 )

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

@@ -3,12 +3,12 @@ import { createDb } from './db'
 import { env } from './env'
 import { createAuth } from './modules/auth/service'
 // redis:start
-import { createRedisStorage } from './redis'
+import { createRedis } from './redis'
 // redis:end
 
 const db = createDb(env.DATABASE_URL)
 // redis:start
-const redis = env.REDIS_URL ? createRedisStorage(env.REDIS_URL) : undefined
+const redis = env.REDIS_URL ? createRedis(env.REDIS_URL) : undefined
 // redis:end
 const auth = createAuth({
   db,

package/templates/template-api/src/modules/auth/service.ts

@@ -6,7 +6,7 @@ import { Elysia } from 'elysia'
 import type { Db } from '../../db'
 import * as schema from '../../db/schema'
 
-export type AuthOptions = {
+export type AuthDeps = {
   db: Db
   secret: string
   baseURL: string
@@ -20,7 +20,7 @@ export const createAuth = ({
   baseURL,
   trustedOrigins = [],
   secondaryStorage
-}: AuthOptions) =>
+}: AuthDeps) =>
   betterAuth({
     secret,
     baseURL,

package/templates/template-api/src/modules/notes/index.ts

@@ -3,18 +3,21 @@ import { Elysia, t } from 'elysia'
 import type { Db } from '../../db'
 import { authService, type Auth } from '../auth/service'
 import { NoteModel } from './model'
-import { Notes } from './service'
+import { createNotes } from './service'
 
 export const notesController = ({ db, auth }: { db: Db; auth: Auth }) =>
   new Elysia({ prefix: '/notes' })
     .use(authService(auth))
-    .get('/', ({ user }) => Notes.list(db, user.id), {
+    .get('/', ({ user }) => createNotes({ db, userId: user.id }).list(), {
       auth: true,
       response: { 200: t.Array(NoteModel.note), 401: NoteModel.error }
     })
     .post(
       '/',
-      ({ user, body, status }) => Notes.create(db, user.id, body).then(n => status(201, n)),
+      ({ user, body, status }) =>
+        createNotes({ db, userId: user.id })
+          .create(body)
+          .then(n => status(201, n)),
       {
         auth: true,
         body: NoteModel.createBody,
@@ -25,7 +28,7 @@ export const notesController = ({ db, auth }: { db: Db; auth: Auth }) =>
       '/:id',
       async ({ user, params, status }) => {
         // a foreign id must look identical to a missing one
-        if (!(await Notes.remove(db, user.id, params.id)))
+        if (!(await createNotes({ db, userId: user.id }).delete(params.id)))
           return status(404, { message: 'Not found' })
         // explicit Response: Elysia's status(204) 500s under vitest's Node runtime
         return new Response(null, { status: 204 })

package/templates/template-api/src/modules/notes/service.ts

@@ -10,27 +10,28 @@ const toDto = (row: typeof note.$inferSelect): NoteModel['note'] => ({
   createdAt: row.createdAt.toISOString()
 })
 
-// no Elysia Context: db and user id are passed in, which the PGlite tests need
-export abstract class Notes {
-  static async list(db: Db, userId: string) {
+// no Elysia Context: the db and the owner are bound up front, so every query is
+// already scoped to one user and the PGlite tests can build one directly
+export const createNotes = ({ db, userId }: { db: Db; userId: string }) => ({
+  list: async () => {
     const rows = await db
       .select()
       .from(note)
       .where(eq(note.userId, userId))
       .orderBy(desc(note.createdAt))
     return rows.map(toDto)
-  }
+  },
 
-  static async create(db: Db, userId: string, { title }: NoteModel['createBody']) {
+  create: async ({ title }: NoteModel['createBody']) => {
     const [created] = await db.insert(note).values({ title, userId }).returning()
     return toDto(created!)
-  }
+  },
 
-  static async remove(db: Db, userId: string, id: string) {
+  delete: async (id: string) => {
     const deleted = await db
       .delete(note)
       .where(and(eq(note.id, id), eq(note.userId, userId)))
       .returning({ id: note.id })
     return deleted.length > 0
   }
-}
+})

package/templates/template-api/src/redis.ts

@@ -2,7 +2,7 @@ import { RedisClient } from 'bun'
 import type { SecondaryStorage } from '@better-auth/core/db'
 
 // Bun's built-in client; a shared store survives restarts and extra instances
-export const createRedisStorage = (url: string) => {
+export const createRedis = (url: string) => {
   const redis = new RedisClient(url)
   const storage: SecondaryStorage = {
     get: key => redis.get(key),

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/skills/project-conventions/SKILL.md

@@ -33,11 +33,11 @@ Refresh is wrapped in `singleFlight` (`src/lib/single-flight.ts`) so concurrent
 `src/api/auth/session-store.ts` is the single source of truth: a localStorage-backed
 external store with cross-tab sync (`storage` event) and zod validation on read.
 
-| Context     | How to read it                                                                            |
-| ----------- | ----------------------------------------------------------------------------------------- |
-| Component   | `useSession()` (from `session-store.ts`, `useSyncExternalStore`)                          |
-| Route guard | `requireSession()` / `redirectIfAuthenticated()` from `@/api/auth/guards` in `beforeLoad` |
-| Query cache | **Never.** Do not mirror session into React Query                                         |
+| Context     | How to read it                                                                     |
+| ----------- | ---------------------------------------------------------------------------------- |
+| Component   | `useSession()` (from `session-store.ts`, `useSyncExternalStore`)                   |
+| Route guard | `requireSession()` / `requireNoSession()` from `@/api/auth/guards` in `beforeLoad` |
+| Query cache | **Never.** Do not mirror session into React Query                                  |
 
 The guard helpers own the redirect contract (`search.redirect` carries the return
 URL). Don't read `sessionStore.get()` in route files directly.
@@ -47,7 +47,7 @@ independently; a bug in a guard is a broken experience, not an access hole.
 
 `beforeLoad` only runs on navigation. Session presence can change without one — a
 sign-in or sign-out in another tab, or a failed token refresh — so
-`src/api/auth/router-bridge.ts` (`bindSessionToRouter`, called once from
+`src/api/auth/router-bridge.ts` (`invalidateOnAuthChange`, called once from
 `src/router.tsx`) subscribes to the store and calls `router.invalidate()` on
 presence transitions.
 **Any new check that reads live state needs the same treatment**: ask "when this
@@ -135,6 +135,6 @@ The rules above describe the SPA-only variant. When the backend is on:
 
 ## Mock backend
 
-`src/mocks/mock-server.ts` patches global `fetch` for `/api/*`, dev-only under
-`VITE_ENABLE_MOCKS`. Seed login `demo@example.com` / `demo1234`. `bun run graduate <name>`
+`src/mocks/server.ts` patches global `fetch` for `/api/*`, dev-only under
+`VITE_ENABLE_MOCKS`. Seed sign-in `demo@example.com` / `demo1234`. `bun run graduate <name>`
 removes it along with the demo account (see root `CLAUDE.md`, Starter state).

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.
 
@@ -54,6 +58,6 @@ Dev-only code must put `import.meta.env.DEV` **first** in the condition so Vite
 
 `dependencies` holds only what is imported from `src/`; CLIs and build plugins are dev deps so `bun audit --prod` stays readable. `trustedDependencies: []` — don't add entries without checking what the script does.
 
-`vite` is **pinned to 8.1.x** (8.1.5). Every 8.2.x and 8.3.0-beta.0 collapse router `autoCodeSplitting` from 12 chunks to 9 and grow the entry from 83 to 117 kB gzip. Re-test before unpinning.
+`vite` is **pinned to 8.1.x** (8.1.5). Every 8.2.x and 8.3.0-beta.0 collapse router `autoCodeSplitting` from 13 chunks to 10 and grow the entry from 81 to 115 kB gzip (measured on 8.2.2). Re-test before unpinning.
 
 </important>

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,21 +9,23 @@
     "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",
+    "@base-ui/react": "^1.8.0",
     "@fontsource-variable/inter": "^5.3.0",
     "@hookform/resolvers": "^5.9.1",
     "@tanstack/react-query": "^5.102.8",
     "@tanstack/react-router": "^1.170.32",
     "class-variance-authority": "^0.7.1",
-    "cn": "^0.2.4",
+    "cn": "^0.2.5",
     "ky": "^2.1.0",
-    "lucide-react": "^1.39.0",
+    "lucide-react": "^1.41.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "react-hook-form": "^7.87.0",
@@ -34,23 +36,25 @@
   "devDependencies": {
     "@babel/core": "^8.0.1",
     "@rolldown/plugin-babel": "^0.2.3",
+    "@standard-schema/spec": "^1.1.0",
     "@tailwindcss/vite": "^4.3.3",
     "@tanstack/router-plugin": "^1.168.35",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.3.3",
     "@types/node": "^26.4.1",
     "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.5",
+    "@types/react-dom": "^19.2.7",
     "@vitejs/plugin-react": "^6.1.1",
     "babel-plugin-react-compiler": "^1.0.0",
-    "happy-dom": "^20.13.2",
+    "happy-dom": "^20.14.0",
     "oxfmt": "0.66.0",
     "oxlint": "^1.81.0",
-    "shadcn": "^4.20.1",
+    "react-doctor": "^0.9.13",
+    "shadcn": "^4.21.0",
     "tailwindcss": "^4.3.3",
     "typescript": "^7.0.2",
     "vite": "8.1.5",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
   },
   "trustedDependencies": []
 }

package/templates/template-router/src/api/auth/auth.test.ts

@@ -1,46 +1,22 @@
-import { afterAll, afterEach, beforeAll } from 'vitest'
-
-import { fetchMe, login, logout } from '@/api/auth'
+import { signIn, signOut } from '@/api/auth'
 import { sessionStore } from '@/api/auth/session-store'
-import { installMockServer } from '@/mocks/mock-server'
-
-const creds = { email: 'demo@example.com', password: 'demo1234' }
-
-let uninstall: () => void
+import { demoCredentials, setupMockBackend } from '@/test/mock-backend'
 
-beforeAll(() => {
-  uninstall = installMockServer()
-})
-afterAll(() => uninstall())
-afterEach(() => {
-  sessionStore.clear()
-  localStorage.clear()
-})
+setupMockBackend()
 
-it('logs in and persists the session', async () => {
-  const session = await login(creds)
-  expect(session.user.email).toBe(creds.email)
-  expect(sessionStore.get()?.user.email).toBe(creds.email)
+it('keeps the session after a successful sign-in', async () => {
+  const session = await signIn(demoCredentials)
+  expect(session.user.email).toBe(demoCredentials.email)
+  expect(sessionStore.get()?.user.email).toBe(demoCredentials.email)
 })
 
 it('rejects bad credentials without touching the session', async () => {
-  await expect(login({ ...creds, password: 'wrong' })).rejects.toThrow()
+  await expect(signIn({ ...demoCredentials, password: 'wrong' })).rejects.toThrow()
   expect(sessionStore.get()).toBeNull()
 })
 
-it('transparently refreshes when the access token is rejected', async () => {
-  await login(creds)
-  const session = sessionStore.get()!
-  sessionStore.set({ ...session, accessToken: 'expired' })
-
-  const me = await fetchMe()
-
-  expect(me.email).toBe(creds.email)
-  expect(sessionStore.get()?.accessToken).not.toBe('expired')
-})
-
-it('clears the session on logout', async () => {
-  await login(creds)
-  await logout()
+it('leaves no session behind after signing out', async () => {
+  await signIn(demoCredentials)
+  await signOut()
   expect(sessionStore.get()).toBeNull()
 })

package/templates/template-router/src/api/auth/create-guards.ts

@@ -0,0 +1,20 @@
+import { redirect } from '@tanstack/react-router'
+
+type Options<S> = {
+  getSession: () => S | Promise<S>
+  /** SSR cannot see the session, so guards defer to the client and run again on hydration. */
+  isServer?: boolean
+}
+
+export const createGuards = <S>({ getSession, isServer = false }: Options<S>) => ({
+  requireSession: async (location: { href: string }) => {
+    if (isServer) return
+    if (!(await getSession())) {
+      throw redirect({ to: '/sign-in', search: { redirect: location.href } })
+    }
+  },
+  requireNoSession: async (search: { redirect?: string }) => {
+    if (isServer) return
+    if (await getSession()) throw redirect({ to: search.redirect ?? '/' })
+  }
+})

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

@@ -1,15 +1,6 @@
-import { redirect } from '@tanstack/react-router'
-
+import { createGuards } from '@/api/auth/create-guards'
 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 } })
-  }
-}
-
-export const redirectIfAuthenticated = (search: { redirect?: string }) => {
-  if (sessionStore.get()) throw redirect({ to: search.redirect ?? '/' })
-}
+export const { requireSession, requireNoSession } = createGuards({
+  getSession: sessionStore.get
+})

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

@@ -6,27 +6,33 @@ import { sessionStore } from '@/api/auth/session-store'
 
 export type Credentials = { email: string; password: string }
 
-export const login = async (credentials: Credentials) => {
-  const session = await api.post('auth/login', { json: credentials }).json(SessionSchema)
+export const signIn = async (credentials: Credentials) => {
+  const session = await api.post('auth/sign-in', { json: credentials }).json(SessionSchema)
   sessionStore.set(session)
   return session
 }
 
-export const logout = async () => {
+export const signOut = async () => {
   try {
-    await api.post('auth/logout')
+    await api.post('auth/sign-out')
   } catch {}
   sessionStore.clear()
 }
 
-export const fetchMe = () => api.get('auth/me').json(UserSchema)
+export const getCurrentUser = () => api.get('auth/me').json(UserSchema)
 
-export const useLogin = () => useMutation({ mutationFn: login })
+export const useSignIn = () => {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: signIn,
+    onSuccess: () => queryClient.clear()
+  })
+}
 
-export const useLogout = () => {
+export const useSignOut = () => {
   const queryClient = useQueryClient()
   return useMutation({
-    mutationFn: logout,
+    mutationFn: signOut,
     onSuccess: () => queryClient.clear()
   })
 }

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

@@ -1,5 +1,3 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-
 import type { Session } from '@/api/auth/schema'
 
 // the module reads localStorage at load, so each case needs a fresh import
@@ -42,7 +40,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 () => {
@@ -67,7 +65,7 @@ describe('cross-tab sync', () => {
     localStorage.setItem('session', JSON.stringify(session))
     const store = await load()
 
-    window.dispatchEvent(new StorageEvent('storage', { key: 'theme', newValue: 'dark' }))
+    window.dispatchEvent(new StorageEvent('storage', { key: 'unrelated', newValue: 'x' }))
 
     expect(store.get()?.user.id).toBe('u_1')
   })