create-top-secret-starter 0.0.1

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

@@ -0,0 +1,20 @@
+import * as z from 'zod/mini'
+
+export const TokensSchema = z.object({
+  accessToken: z.string(),
+  refreshToken: z.string()
+})
+export type Tokens = z.infer<typeof TokensSchema>
+
+// TODO: match your backend's user shape
+export const UserSchema = z.object({
+  id: z.string(),
+  email: z.email()
+})
+export type User = z.infer<typeof UserSchema>
+
+export const SessionSchema = z.object({
+  ...TokensSchema.shape,
+  user: UserSchema
+})
+export type Session = z.infer<typeof SessionSchema>

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

@@ -0,0 +1,101 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { Session } from '@/api/auth/schema'
+
+// session-store reads localStorage once at module load, so every case needs a
+// fresh module instance seeded before the import.
+const load = async () => {
+  vi.resetModules()
+  return (await import('@/api/auth/session-store')).sessionStore
+}
+
+const session: Session = {
+  user: { id: 'u_1', email: 'a@b.com' },
+  accessToken: 'access',
+  refreshToken: 'refresh'
+}
+
+beforeEach(() => localStorage.clear())
+
+describe('reading persisted state', () => {
+  it('returns null for unparsable JSON instead of throwing at boot', async () => {
+    localStorage.setItem('session:v1', 'not json at all')
+    const store = await load()
+    expect(store.get()).toBeNull()
+  })
+
+  it('returns null when the shape no longer matches the schema', async () => {
+    // the shape a previous release wrote, or a renamed field
+    localStorage.setItem('session:v1', JSON.stringify({ token: 'access', user: { id: 'u_1' } }))
+    const store = await load()
+    expect(store.get()).toBeNull()
+  })
+})
+
+describe('cross-tab sync', () => {
+  it('adopts a session written by another tab', async () => {
+    const store = await load()
+    const listener = vi.fn()
+    store.subscribe(listener)
+
+    window.dispatchEvent(
+      new StorageEvent('storage', { key: 'session:v1', newValue: JSON.stringify(session) })
+    )
+
+    expect(store.get()?.user.id).toBe('u_1')
+    expect(listener).toHaveBeenCalledWith(expect.objectContaining({ accessToken: 'access' }))
+  })
+
+  it('drops the session when another tab signs out', async () => {
+    localStorage.setItem('session:v1', JSON.stringify(session))
+    const store = await load()
+
+    window.dispatchEvent(new StorageEvent('storage', { key: 'session:v1', newValue: null }))
+
+    expect(store.get()).toBeNull()
+  })
+
+  it('treats a corrupt cross-tab write as a sign-out, not a crash', async () => {
+    localStorage.setItem('session:v1', JSON.stringify(session))
+    const store = await load()
+
+    window.dispatchEvent(new StorageEvent('storage', { key: 'session:v1', newValue: '{{{' }))
+
+    expect(store.get()).toBeNull()
+  })
+
+  it('ignores writes to unrelated keys', async () => {
+    localStorage.setItem('session:v1', JSON.stringify(session))
+    const store = await load()
+
+    window.dispatchEvent(new StorageEvent('storage', { key: 'theme', newValue: 'dark' }))
+
+    expect(store.get()?.user.id).toBe('u_1')
+  })
+})
+
+describe('writing', () => {
+  it('refuses to update tokens with no active session', async () => {
+    const store = await load()
+    expect(() => store.updateTokens({ accessToken: 'a', refreshToken: 'r' })).toThrow(
+      /no active session/i
+    )
+  })
+
+  it('keeps the user when rotating tokens', async () => {
+    const store = await load()
+    store.set(session)
+    store.updateTokens({ accessToken: 'a2', refreshToken: 'r2' })
+
+    expect(store.get()).toEqual({ ...session, accessToken: 'a2', refreshToken: 'r2' })
+    expect(JSON.parse(localStorage.getItem('session:v1')!).accessToken).toBe('a2')
+  })
+
+  it('removes the key on clear so a reload starts signed out', async () => {
+    const store = await load()
+    store.set(session)
+    store.clear()
+
+    expect(localStorage.getItem('session:v1')).toBeNull()
+  })
+})

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

@@ -0,0 +1,56 @@
+import { useSyncExternalStore } from 'react'
+
+import { SessionSchema, type Session, type Tokens } from '@/api/auth/schema'
+
+// Versioned: bumping the suffix discards every persisted session at once, which is
+// what you want after changing the shape or revoking tokens. Reading is already
+// shape-safe via zod, so this is about deliberate invalidation, not crash safety.
+const KEY = 'session:v1'
+
+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()
+})
+
+export const sessionStore = {
+  get: () => current,
+  set: (next: Session) => commit(next),
+  clear: () => commit(null),
+  updateTokens: (tokens: Tokens) => {
+    if (!current) throw new Error('Cannot update tokens: no active session')
+    commit({ ...current, ...tokens })
+  },
+  subscribe: (listener: Listener) => {
+    listeners.add(listener)
+    return () => {
+      listeners.delete(listener)
+    }
+  }
+}
+
+// The React binding of the store's subscribe contract lives with the store: one
+// concept, one file. Components use this; route guards use @/api/auth/guards.
+export const useSession = () => useSyncExternalStore(sessionStore.subscribe, sessionStore.get)

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

@@ -0,0 +1,51 @@
+import ky from 'ky'
+
+import { TokensSchema } from '@/api/auth/schema'
+import { sessionStore } from '@/api/auth/session-store'
+import { env } from '@/env'
+import { singleFlight } from '@/lib/single-flight'
+
+const baseUrl = env.VITE_API_URL
+
+const authClient = ky.create({ baseUrl })
+
+const refreshTokens = singleFlight(async () => {
+  const session = sessionStore.get()
+  if (!session) throw new Error('No session to refresh')
+
+  try {
+    const tokens = await authClient
+      .post('auth/refresh', { json: { refreshToken: session.refreshToken } })
+      .json()
+      .then(data => TokensSchema.parse(data))
+    sessionStore.updateTokens(tokens)
+    return tokens
+  } catch (error) {
+    sessionStore.clear()
+    throw error
+  }
+})
+
+export const api = ky.create({
+  baseUrl,
+  hooks: {
+    beforeRequest: [
+      ({ request }) => {
+        const token = sessionStore.get()?.accessToken
+        if (token) request.headers.set('Authorization', `Bearer ${token}`)
+      }
+    ],
+    afterResponse: [
+      async ({ request, response, retryCount }) => {
+        if (response.status !== 401 || retryCount > 0) return
+
+        try {
+          const tokens = await refreshTokens()
+          const headers = new Headers(request.headers)
+          headers.set('Authorization', `Bearer ${tokens.accessToken}`)
+          return ky.retry({ request: new Request(request, { headers }), code: 'TOKEN_REFRESHED' })
+        } catch {}
+      }
+    ]
+  }
+})

package/templates/template-router/src/components/status-page.tsx

@@ -0,0 +1,68 @@
+import type { ReactNode } from 'react'
+import type { VariantProps } from 'class-variance-authority'
+import { Link } from '@tanstack/react-router'
+import { House } from 'lucide-react'
+
+import { buttonVariants } from '@/components/ui/button'
+import {
+  Empty,
+  EmptyContent,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle
+} from '@/components/ui/empty'
+
+type StatusPageProps = {
+  code: string
+  icon: ReactNode
+  mediaClassName?: string
+  title: string
+  description: string
+  actions: ReactNode
+  children?: ReactNode
+}
+
+export const StatusPage = ({
+  code,
+  icon,
+  mediaClassName,
+  title,
+  description,
+  actions,
+  children
+}: StatusPageProps) => (
+  <main className='flex min-h-svh items-center justify-center p-6'>
+    <Empty className='max-w-md border-none'>
+      <EmptyHeader>
+        <EmptyMedia variant='icon' className={mediaClassName}>
+          {icon}
+        </EmptyMedia>
+        <span className='text-muted-foreground font-mono text-xs tracking-widest tabular-nums'>
+          {code}
+        </span>
+        <EmptyTitle>{title}</EmptyTitle>
+        <EmptyDescription>{description}</EmptyDescription>
+      </EmptyHeader>
+      <EmptyContent>
+        <div className='grid grid-cols-2 gap-2'>{actions}</div>
+        {children}
+      </EmptyContent>
+    </Empty>
+  </main>
+)
+
+// A styled Link, not a Button rendering a Link: Base UI's Button applies
+// role="button", which overrides the anchor's link semantics. Assistive tech then
+// announces an action where a navigation happens, and link affordances (open in a
+// new tab, copy address, the screen reader's list of links) disappear.
+export const BackHomeButton = ({
+  variant = 'default'
+}: {
+  variant?: VariantProps<typeof buttonVariants>['variant']
+}) => (
+  <Link to='/' className={buttonVariants({ variant, size: 'default' })}>
+    <House data-icon='inline-start' />
+    Back home
+  </Link>
+)

package/templates/template-router/src/components/ui/button.tsx

@@ -0,0 +1,58 @@
+import { Button as ButtonPrimitive } from '@base-ui/react/button'
+import { cva, type VariantProps } from 'class-variance-authority'
+
+import { cn } from '@/lib/utils'
+
+const buttonVariants = cva(
+  "group/button focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 inline-flex shrink-0 items-center justify-center rounded-lg border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-all outline-none select-none focus-visible:ring-3 active:not-aria-[haspopup]:translate-y-px disabled:pointer-events-none disabled:opacity-50 aria-invalid:ring-3 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary text-primary-foreground hover:bg-primary/80',
+        outline:
+          'border-border bg-background hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50',
+        secondary:
+          'bg-secondary text-secondary-foreground aria-expanded:bg-secondary aria-expanded:text-secondary-foreground hover:bg-[color-mix(in_oklch,var(--secondary),var(--foreground)_5%)]',
+        ghost:
+          'hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50',
+        destructive:
+          'bg-destructive/10 text-destructive hover:bg-destructive/20 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:hover:bg-destructive/30 dark:focus-visible:ring-destructive/40',
+        link: 'text-primary underline-offset-4 hover:underline'
+      },
+      size: {
+        default:
+          'h-8 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2',
+        xs: "h-6 gap-1 rounded-[min(var(--radius-md),10px)] px-2 text-xs in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3",
+        sm: "h-7 gap-1 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
+        lg: 'h-9 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2',
+        icon: 'size-8',
+        'icon-xs':
+          "size-6 rounded-[min(var(--radius-md),10px)] in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3",
+        'icon-sm':
+          'size-7 rounded-[min(var(--radius-md),12px)] in-data-[slot=button-group]:rounded-lg',
+        'icon-lg': 'size-9'
+      }
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default'
+    }
+  }
+)
+
+const Button = ({
+  className,
+  variant = 'default',
+  size = 'default',
+  ...props
+}: ButtonPrimitive.Props & VariantProps<typeof buttonVariants>) => {
+  return (
+    <ButtonPrimitive
+      data-slot='button'
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  )
+}
+
+export { Button, buttonVariants }

package/templates/template-router/src/components/ui/dialog.tsx

@@ -0,0 +1,136 @@
+import { Dialog as DialogPrimitive } from '@base-ui/react/dialog'
+import * as React from 'react'
+
+import { Button } from '@/components/ui/button'
+import { cn } from '@/lib/utils'
+import { XIcon } from 'lucide-react'
+
+const Dialog = ({ ...props }: DialogPrimitive.Root.Props) => {
+  return <DialogPrimitive.Root data-slot='dialog' {...props} />
+}
+
+const DialogTrigger = ({ ...props }: DialogPrimitive.Trigger.Props) => {
+  return <DialogPrimitive.Trigger data-slot='dialog-trigger' {...props} />
+}
+
+const DialogPortal = ({ ...props }: DialogPrimitive.Portal.Props) => {
+  return <DialogPrimitive.Portal data-slot='dialog-portal' {...props} />
+}
+
+const DialogClose = ({ ...props }: DialogPrimitive.Close.Props) => {
+  return <DialogPrimitive.Close data-slot='dialog-close' {...props} />
+}
+
+const DialogOverlay = ({ className, ...props }: DialogPrimitive.Backdrop.Props) => {
+  return (
+    <DialogPrimitive.Backdrop
+      data-slot='dialog-overlay'
+      className={cn(
+        'data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0 fixed inset-0 isolate z-50 bg-black/10 duration-100 supports-backdrop-filter:backdrop-blur-xs',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+const DialogContent = ({
+  className,
+  children,
+  showCloseButton = true,
+  ...props
+}: DialogPrimitive.Popup.Props & {
+  showCloseButton?: boolean
+}) => {
+  return (
+    <DialogPortal>
+      <DialogOverlay />
+      <DialogPrimitive.Popup
+        data-slot='dialog-content'
+        className={cn(
+          'bg-popover text-popover-foreground ring-foreground/10 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95 fixed top-1/2 left-1/2 z-50 grid w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 gap-4 rounded-xl p-4 text-sm ring-1 duration-100 outline-none sm:max-w-sm',
+          className
+        )}
+        {...props}
+      >
+        {children}
+        {showCloseButton && (
+          <DialogPrimitive.Close
+            data-slot='dialog-close'
+            render={<Button variant='ghost' className='absolute top-2 right-2' size='icon-sm' />}
+          >
+            <XIcon />
+            <span className='sr-only'>Close</span>
+          </DialogPrimitive.Close>
+        )}
+      </DialogPrimitive.Popup>
+    </DialogPortal>
+  )
+}
+
+const DialogHeader = ({ className, ...props }: React.ComponentProps<'div'>) => {
+  return (
+    <div data-slot='dialog-header' className={cn('flex flex-col gap-2', className)} {...props} />
+  )
+}
+
+const DialogFooter = ({
+  className,
+  showCloseButton = false,
+  children,
+  ...props
+}: React.ComponentProps<'div'> & {
+  showCloseButton?: boolean
+}) => {
+  return (
+    <div
+      data-slot='dialog-footer'
+      className={cn(
+        'bg-muted/50 -mx-4 -mb-4 flex flex-col-reverse gap-2 rounded-b-xl border-t p-4 sm:flex-row sm:justify-end',
+        className
+      )}
+      {...props}
+    >
+      {children}
+      {showCloseButton && (
+        <DialogPrimitive.Close render={<Button variant='outline' />}>Close</DialogPrimitive.Close>
+      )}
+    </div>
+  )
+}
+
+const DialogTitle = ({ className, ...props }: DialogPrimitive.Title.Props) => {
+  return (
+    <DialogPrimitive.Title
+      data-slot='dialog-title'
+      className={cn('font-heading text-base leading-none font-medium', className)}
+      {...props}
+    />
+  )
+}
+
+const DialogDescription = ({ className, ...props }: DialogPrimitive.Description.Props) => {
+  return (
+    <DialogPrimitive.Description
+      data-slot='dialog-description'
+      className={cn(
+        'text-muted-foreground *:[a]:hover:text-foreground text-sm *:[a]:underline *:[a]:underline-offset-3',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogPortal,
+  DialogTitle,
+  DialogTrigger
+}

package/templates/template-router/src/components/ui/empty.tsx

@@ -0,0 +1,94 @@
+import { cva, type VariantProps } from 'class-variance-authority'
+
+import { cn } from '@/lib/utils'
+
+function Empty({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot='empty'
+      className={cn(
+        'flex w-full min-w-0 flex-1 flex-col items-center justify-center gap-4 rounded-xl border-dashed p-6 text-center text-balance',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function EmptyHeader({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot='empty-header'
+      className={cn('flex max-w-sm flex-col items-center gap-2', className)}
+      {...props}
+    />
+  )
+}
+
+const emptyMediaVariants = cva(
+  'mb-2 flex shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg]:shrink-0',
+  {
+    variants: {
+      variant: {
+        default: 'bg-transparent',
+        icon: "bg-muted text-foreground flex size-8 shrink-0 items-center justify-center rounded-lg [&_svg:not([class*='size-'])]:size-4"
+      }
+    },
+    defaultVariants: {
+      variant: 'default'
+    }
+  }
+)
+
+function EmptyMedia({
+  className,
+  variant = 'default',
+  ...props
+}: React.ComponentProps<'div'> & VariantProps<typeof emptyMediaVariants>) {
+  return (
+    <div
+      data-slot='empty-icon'
+      data-variant={variant}
+      className={cn(emptyMediaVariants({ variant, className }))}
+      {...props}
+    />
+  )
+}
+
+function EmptyTitle({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot='empty-title'
+      className={cn('font-heading text-sm font-medium tracking-tight', className)}
+      {...props}
+    />
+  )
+}
+
+function EmptyDescription({ className, ...props }: React.ComponentProps<'p'>) {
+  return (
+    <div
+      data-slot='empty-description'
+      className={cn(
+        'text-muted-foreground [&>a:hover]:text-primary text-sm/relaxed [&>a]:underline [&>a]:underline-offset-4',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function EmptyContent({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot='empty-content'
+      className={cn(
+        'flex w-full max-w-sm min-w-0 flex-col items-center gap-2.5 text-sm text-balance',
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Empty, EmptyHeader, EmptyTitle, EmptyDescription, EmptyContent, EmptyMedia }