create-top-secret-starter 0.1.0 → 0.1.1

package/package.json

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

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

@@ -7,12 +7,19 @@ import { sessionStore } from '@/api/auth/session-store'
 // never mirrors the session. Guards get these helpers so the redirect contract
 // (`search.redirect` carries where to return after sign-in) lives in one module.
 
+// 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.
+const isServer = typeof document === 'undefined'
+
 export const requireSession = (location: { href: string }) => {
+  if (isServer) return
   if (!sessionStore.get()) {
     throw redirect({ to: '/sign-in', search: { redirect: location.href } })
   }
 }
 
 export const redirectIfAuthenticated = (search: { redirect?: string }) => {
+  if (isServer) return
   if (sessionStore.get()) throw redirect({ to: search.redirect ?? '/' })
 }

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

@@ -17,23 +17,31 @@ const parseRaw = (raw: string | null): Session | null => {
   }
 }
 
-let current = parseRaw(localStorage.getItem(KEY))
+// 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()
 }
 
-window.addEventListener('storage', e => {
-  if (e.key !== KEY) return
-  current = parseRaw(e.newValue)
-  notify()
-})
+if (isBrowser) {
+  window.addEventListener('storage', e => {
+    if (e.key !== KEY) return
+    current = parseRaw(e.newValue)
+    notify()
+  })
+}
 
 export const sessionStore = {
   get: () => current,
@@ -53,4 +61,6 @@ export const sessionStore = {
 
 // 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)
+// The server snapshot is always null: the session lives in localStorage (see above).
+export const useSession = () =>
+  useSyncExternalStore(sessionStore.subscribe, sessionStore.get, () => null)

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

@@ -36,6 +36,8 @@ const applyTheme = (theme: Theme) => {
 
 export const ThemeProvider = ({ children }: PropsWithChildren) => {
   const [theme, setThemeState] = useState<Theme>(() => {
+    // the initializer also runs during SSR, where localStorage doesn't exist
+    if (typeof window === 'undefined') return DEFAULT_THEME
     const stored = localStorage.getItem(STORAGE_KEY)
     return isTheme(stored) ? stored : DEFAULT_THEME
   })

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

@@ -7,12 +7,19 @@ import { sessionStore } from '@/api/auth/session-store'
 // never mirrors the session. Guards get these helpers so the redirect contract
 // (`search.redirect` carries where to return after sign-in) lives in one module.
 
+// 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.
+const isServer = typeof document === 'undefined'
+
 export const requireSession = (location: { href: string }) => {
+  if (isServer) return
   if (!sessionStore.get()) {
     throw redirect({ to: '/sign-in', search: { redirect: location.href } })
   }
 }
 
 export const redirectIfAuthenticated = (search: { redirect?: string }) => {
+  if (isServer) return
   if (sessionStore.get()) throw redirect({ to: search.redirect ?? '/' })
 }

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

@@ -17,23 +17,31 @@ const parseRaw = (raw: string | null): Session | null => {
   }
 }
 
-let current = parseRaw(localStorage.getItem(KEY))
+// 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()
 }
 
-window.addEventListener('storage', e => {
-  if (e.key !== KEY) return
-  current = parseRaw(e.newValue)
-  notify()
-})
+if (isBrowser) {
+  window.addEventListener('storage', e => {
+    if (e.key !== KEY) return
+    current = parseRaw(e.newValue)
+    notify()
+  })
+}
 
 export const sessionStore = {
   get: () => current,
@@ -53,4 +61,6 @@ export const sessionStore = {
 
 // 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)
+// The server snapshot is always null: the session lives in localStorage (see above).
+export const useSession = () =>
+  useSyncExternalStore(sessionStore.subscribe, sessionStore.get, () => null)

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

@@ -36,6 +36,8 @@ const applyTheme = (theme: Theme) => {
 
 export const ThemeProvider = ({ children }: PropsWithChildren) => {
   const [theme, setThemeState] = useState<Theme>(() => {
+    // the initializer also runs during SSR, where localStorage doesn't exist
+    if (typeof window === 'undefined') return DEFAULT_THEME
     const stored = localStorage.getItem(STORAGE_KEY)
     return isTheme(stored) ? stored : DEFAULT_THEME
   })