@tanstack/start-client-core 1.166.10 → 1.166.12

package/skills/start-core/execution-model/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: start-core/execution-model
+description: >-
+  Isomorphic-by-default principle, environment boundary functions
+  (createServerFn, createServerOnlyFn, createClientOnlyFn,
+  createIsomorphicFn), ClientOnly component, useHydrated hook,
+  import protection, dead code elimination, environment variable
+  safety (VITE_ prefix, process.env).
+type: sub-skill
+library: tanstack-start
+library_version: '1.166.2'
+requires:
+  - start-core
+sources:
+  - TanStack/router:docs/start/framework/react/guide/execution-model.md
+  - TanStack/router:docs/start/framework/react/guide/environment-variables.md
+---
+
+# Execution Model
+
+Understanding where code runs is fundamental to TanStack Start. This skill covers the isomorphic execution model and how to control environment boundaries.
+
+> **CRITICAL**: ALL code in TanStack Start is isomorphic by default — it runs in BOTH server and client bundles. Route loaders run on BOTH server (during SSR) AND client (during navigation). Server-only operations MUST use `createServerFn`.
+> **CRITICAL**: Module-level `process.env` access runs in both environments. Secret values leak into the client bundle. Access secrets ONLY inside `createServerFn` or `createServerOnlyFn`.
+> **CRITICAL**: `VITE_` prefixed environment variables are exposed to the client bundle. Server secrets must NOT have the `VITE_` prefix.
+
+## Execution Control APIs
+
+| API                      | Use Case                  | Client Behavior           | Server Behavior       |
+| ------------------------ | ------------------------- | ------------------------- | --------------------- |
+| `createServerFn()`       | RPC calls, data mutations | Network request to server | Direct execution      |
+| `createServerOnlyFn(fn)` | Utility functions         | Throws error              | Direct execution      |
+| `createClientOnlyFn(fn)` | Browser utilities         | Direct execution          | Throws error          |
+| `createIsomorphicFn()`   | Different impl per env    | Uses `.client()` impl     | Uses `.server()` impl |
+| `<ClientOnly>`           | Browser-only components   | Renders children          | Renders fallback      |
+| `useHydrated()`          | Hydration-dependent logic | `true` after hydration    | `false`               |
+
+## Server-Only Execution
+
+### createServerFn (RPC pattern)
+
+The primary way to run server-only code. On the client, calls become fetch requests:
+
+```tsx
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import { createServerFn } from '@tanstack/react-start'
+
+const fetchUser = createServerFn().handler(async () => {
+  const secret = process.env.API_SECRET // safe — server only
+  return await db.users.find()
+})
+
+// Client calls this via network request
+const user = await fetchUser()
+```
+
+### createServerOnlyFn (throws on client)
+
+For utility functions that must never run on client:
+
+```tsx
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import { createServerOnlyFn } from '@tanstack/react-start'
+
+const getSecret = createServerOnlyFn(() => process.env.DATABASE_URL)
+
+// Server: returns the value
+// Client: THROWS an error
+```
+
+## Client-Only Execution
+
+### createClientOnlyFn
+
+```tsx
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import { createClientOnlyFn } from '@tanstack/react-start'
+
+const saveToStorage = createClientOnlyFn((key: string, value: string) => {
+  localStorage.setItem(key, value)
+})
+```
+
+### ClientOnly Component
+
+```tsx
+// Use @tanstack/<framework>-router for your framework (react, solid, vue)
+import { ClientOnly } from '@tanstack/react-router'
+
+function Analytics() {
+  return (
+    <ClientOnly fallback={null}>
+      <GoogleAnalyticsScript />
+    </ClientOnly>
+  )
+}
+```
+
+### useHydrated Hook
+
+```tsx
+// Use @tanstack/<framework>-router for your framework (react, solid, vue)
+import { useHydrated } from '@tanstack/react-router'
+
+function TimeZoneDisplay() {
+  const hydrated = useHydrated()
+  const timeZone = hydrated
+    ? Intl.DateTimeFormat().resolvedOptions().timeZone
+    : 'UTC'
+
+  return <div>Your timezone: {timeZone}</div>
+}
+```
+
+Behavior: SSR → `false`, first client render → `false`, after hydration → `true` (stays `true`).
+
+## Environment-Specific Implementations
+
+```tsx
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import { createIsomorphicFn } from '@tanstack/react-start'
+
+const getDeviceInfo = createIsomorphicFn()
+  .server(() => ({ type: 'server', platform: process.platform }))
+  .client(() => ({ type: 'client', userAgent: navigator.userAgent }))
+```
+
+## Environment Variables
+
+### Server-Side (inside createServerFn)
+
+Access any variable via `process.env`:
+
+```tsx
+const connectDb = createServerFn().handler(async () => {
+  const url = process.env.DATABASE_URL // no prefix needed
+  return createConnection(url)
+})
+```
+
+### Client-Side (components)
+
+Only `VITE_` prefixed variables are available:
+
+```tsx
+// Framework-specific component type (React.ReactNode, JSX.Element, etc.)
+function ApiProvider({ children }: { children: React.ReactNode }) {
+  const apiUrl = import.meta.env.VITE_API_URL // available
+  // import.meta.env.DATABASE_URL → undefined (security)
+  return (
+    <ApiContext.Provider value={{ apiUrl }}>{children}</ApiContext.Provider>
+  )
+}
+```
+
+### Runtime Client Variables
+
+If you need server-side variables on the client without `VITE_` prefix, pass them through a server function:
+
+```tsx
+const getRuntimeVar = createServerFn({ method: 'GET' }).handler(() => {
+  return process.env.MY_RUNTIME_VAR
+})
+
+export const Route = createFileRoute('/')({
+  loader: async () => {
+    const foo = await getRuntimeVar()
+    return { foo }
+  },
+  component: () => {
+    const { foo } = Route.useLoaderData()
+    return <div>{foo}</div>
+  },
+})
+```
+
+### Type Safety for Environment Variables
+
+```tsx
+// src/env.d.ts
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_APP_NAME: string
+  readonly VITE_API_URL: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}
+
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv {
+      readonly DATABASE_URL: string
+      readonly JWT_SECRET: string
+    }
+  }
+}
+
+export {}
+```
+
+## Common Mistakes
+
+### 1. CRITICAL: Assuming loaders are server-only
+
+```tsx
+// WRONG — loader runs on BOTH server and client
+export const Route = createFileRoute('/dashboard')({
+  loader: async () => {
+    const secret = process.env.API_SECRET // LEAKED to client
+    return fetch(`https://api.example.com/data`, {
+      headers: { Authorization: secret },
+    })
+  },
+})
+
+// CORRECT — use createServerFn
+const getData = createServerFn({ method: 'GET' }).handler(async () => {
+  const secret = process.env.API_SECRET
+  return fetch(`https://api.example.com/data`, {
+    headers: { Authorization: secret },
+  })
+})
+
+export const Route = createFileRoute('/dashboard')({
+  loader: () => getData(),
+})
+```
+
+### 2. CRITICAL: Exposing secrets via module-level process.env
+
+```tsx
+// WRONG — runs in both environments, value in client bundle
+const apiKey = process.env.SECRET_KEY
+export function fetchData() {
+  /* uses apiKey */
+}
+
+// CORRECT — access inside server function only
+const fetchData = createServerFn({ method: 'GET' }).handler(async () => {
+  const apiKey = process.env.SECRET_KEY
+  return fetch(url, { headers: { Authorization: apiKey } })
+})
+```
+
+### 3. CRITICAL: Using VITE\_ prefix for server secrets
+
+```bash
+# WRONG — exposed to client bundle
+VITE_SECRET_API_KEY=sk_live_xxx
+
+# CORRECT — no prefix for server secrets
+SECRET_API_KEY=sk_live_xxx
+
+# CORRECT — VITE_ only for public client values
+VITE_APP_NAME=My App
+```
+
+### 4. HIGH: Hydration mismatches
+
+```tsx
+// WRONG — different content server vs client
+function CurrentTime() {
+  return <div>{new Date().toLocaleString()}</div>
+}
+
+// CORRECT — consistent rendering
+function CurrentTime() {
+  const [time, setTime] = useState<string>()
+  useEffect(() => {
+    setTime(new Date().toLocaleString())
+  }, [])
+  return <div>{time || 'Loading...'}</div>
+}
+```
+
+## Architecture Decision Framework
+
+**Server-Only** (`createServerFn` / `createServerOnlyFn`):
+
+- Sensitive data (env vars, secrets)
+- Database connections, file system
+- External API keys
+
+**Client-Only** (`createClientOnlyFn` / `<ClientOnly>`):
+
+- DOM manipulation, browser APIs
+- localStorage, geolocation
+- Analytics/tracking
+
+**Isomorphic** (default / `createIsomorphicFn`):
+
+- Data formatting, business logic
+- Shared utilities
+- Route loaders (they're isomorphic by nature)
+
+## Cross-References
+
+- [start-core/server-functions](../server-functions/SKILL.md) — the primary server boundary
+- [start-core/deployment](../deployment/SKILL.md) — deployment target affects execution

package/skills/start-core/middleware/SKILL.md

@@ -0,0 +1,365 @@
+---
+name: start-core/middleware
+description: >-
+  createMiddleware, request middleware (.server only), server function
+  middleware (.client + .server), context passing via next({ context }),
+  sendContext for client-server transfer, global middleware via
+  createStart in src/start.ts, middleware factories, method order
+  enforcement, fetch override precedence.
+type: sub-skill
+library: tanstack-start
+library_version: '1.166.2'
+requires:
+  - start-core
+  - start-core/server-functions
+sources:
+  - TanStack/router:docs/start/framework/react/guide/middleware.md
+---
+
+# Middleware
+
+Middleware customizes the behavior of server functions and server routes. It is composable — middleware can depend on other middleware to form a chain.
+
+> **CRITICAL**: TypeScript enforces method order: `middleware()` → `inputValidator()` → `client()` → `server()`. Wrong order causes type errors.
+> **CRITICAL**: Client context sent via `sendContext` is NOT validated by default. If you send dynamic user-generated data, validate it in server-side middleware before use.
+
+## Two Types of Middleware
+
+| Feature           | Request Middleware                           | Server Function Middleware               |
+| ----------------- | -------------------------------------------- | ---------------------------------------- |
+| Scope             | All server requests (SSR, routes, functions) | Server functions only                    |
+| Methods           | `.server()`                                  | `.client()`, `.server()`                 |
+| Input validation  | No                                           | Yes (`.inputValidator()`)                |
+| Client-side logic | No                                           | Yes                                      |
+| Created with      | `createMiddleware()`                         | `createMiddleware({ type: 'function' })` |
+
+Request middleware cannot depend on server function middleware. Server function middleware can depend on both types.
+
+## Request Middleware
+
+Runs on ALL server requests (SSR, server routes, server functions):
+
+```tsx
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import { createMiddleware } from '@tanstack/react-start'
+
+const loggingMiddleware = createMiddleware().server(
+  async ({ next, context, request }) => {
+    console.log('Request:', request.url)
+    const result = await next()
+    return result
+  },
+)
+```
+
+## Server Function Middleware
+
+Has both client and server phases:
+
+```tsx
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import { createMiddleware } from '@tanstack/react-start'
+
+const authMiddleware = createMiddleware({ type: 'function' })
+  .client(async ({ next }) => {
+    // Runs on client BEFORE the RPC call
+    const result = await next()
+    // Runs on client AFTER the RPC response
+    return result
+  })
+  .server(async ({ next, context }) => {
+    // Runs on server BEFORE the handler
+    const result = await next()
+    // Runs on server AFTER the handler
+    return result
+  })
+```
+
+## Attaching Middleware to Server Functions
+
+```tsx
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import { createServerFn } from '@tanstack/react-start'
+
+const fn = createServerFn()
+  .middleware([authMiddleware])
+  .handler(async ({ context }) => {
+    // context contains data from middleware
+    return { user: context.user }
+  })
+```
+
+## Context Passing via next()
+
+Pass context down the middleware chain:
+
+```tsx
+const authMiddleware = createMiddleware().server(async ({ next, request }) => {
+  const session = await getSession(request.headers)
+  if (!session) throw new Error('Unauthorized')
+
+  return next({
+    context: { session },
+  })
+})
+
+const roleMiddleware = createMiddleware()
+  .middleware([authMiddleware])
+  .server(async ({ next, context }) => {
+    console.log('Session:', context.session) // typed!
+    return next()
+  })
+```
+
+## Sending Context Between Client and Server
+
+### Client → Server (sendContext)
+
+```tsx
+const workspaceMiddleware = createMiddleware({ type: 'function' })
+  .client(async ({ next, context }) => {
+    return next({
+      sendContext: {
+        workspaceId: context.workspaceId,
+      },
+    })
+  })
+  .server(async ({ next, context }) => {
+    // workspaceId available here, but VALIDATE IT
+    console.log('Workspace:', context.workspaceId)
+    return next()
+  })
+```
+
+### Server → Client (sendContext in server)
+
+```tsx
+const serverTimer = createMiddleware({ type: 'function' }).server(
+  async ({ next }) => {
+    return next({
+      sendContext: {
+        timeFromServer: new Date(),
+      },
+    })
+  },
+)
+
+const clientLogger = createMiddleware({ type: 'function' })
+  .middleware([serverTimer])
+  .client(async ({ next }) => {
+    const result = await next()
+    console.log('Server time:', result.context.timeFromServer)
+    return result
+  })
+```
+
+## Input Validation in Middleware
+
+```tsx
+import { z } from 'zod'
+import { zodValidator } from '@tanstack/zod-adapter'
+
+const workspaceMiddleware = createMiddleware({ type: 'function' })
+  .inputValidator(zodValidator(z.object({ workspaceId: z.string() })))
+  .server(async ({ next, data }) => {
+    console.log('Workspace:', data.workspaceId)
+    return next()
+  })
+```
+
+## Global Middleware
+
+Create `src/start.ts` to configure global middleware:
+
+```tsx
+// src/start.ts
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import { createStart, createMiddleware } from '@tanstack/react-start'
+
+const requestLogger = createMiddleware().server(async ({ next, request }) => {
+  console.log(`${request.method} ${request.url}`)
+  return next()
+})
+
+const functionAuth = createMiddleware({ type: 'function' }).server(
+  async ({ next }) => {
+    // runs for every server function
+    return next()
+  },
+)
+
+export const startInstance = createStart(() => ({
+  requestMiddleware: [requestLogger],
+  functionMiddleware: [functionAuth],
+}))
+```
+
+## Using Middleware with Server Routes
+
+### All handlers in a route
+
+```tsx
+export const Route = createFileRoute('/api/users')({
+  server: {
+    middleware: [authMiddleware],
+    handlers: {
+      GET: async ({ context }) => Response.json(context.user),
+      POST: async ({ request }) => {
+        /* ... */
+      },
+    },
+  },
+})
+```
+
+### Specific handlers only
+
+```tsx
+export const Route = createFileRoute('/api/users')({
+  server: {
+    handlers: ({ createHandlers }) =>
+      createHandlers({
+        GET: async () => Response.json({ public: true }),
+        POST: {
+          middleware: [authMiddleware],
+          handler: async ({ context }) => {
+            return Response.json({ user: context.session.user })
+          },
+        },
+      }),
+  },
+})
+```
+
+## Middleware Factories
+
+Create parameterized middleware for reusable patterns like authorization:
+
+```tsx
+const authMiddleware = createMiddleware().server(async ({ next, request }) => {
+  const session = await auth.getSession({ headers: request.headers })
+  if (!session) throw new Error('Unauthorized')
+  return next({ context: { session } })
+})
+
+type Permissions = Record<string, string[]>
+
+function authorizationMiddleware(permissions: Permissions) {
+  return createMiddleware({ type: 'function' })
+    .middleware([authMiddleware])
+    .server(async ({ next, context }) => {
+      const granted = await auth.hasPermission(context.session, permissions)
+      if (!granted) throw new Error('Forbidden')
+      return next()
+    })
+}
+
+// Usage
+const getClients = createServerFn()
+  .middleware([authorizationMiddleware({ client: ['read'] })])
+  .handler(async () => {
+    return { message: 'The user can read clients.' }
+  })
+```
+
+## Custom Headers and Fetch
+
+### Setting headers from client middleware
+
+```tsx
+const authMiddleware = createMiddleware({ type: 'function' }).client(
+  async ({ next }) => {
+    return next({
+      headers: { Authorization: `Bearer ${getToken()}` },
+    })
+  },
+)
+```
+
+Headers merge across middleware. Later middleware overrides earlier. Call-site headers override all middleware headers.
+
+### Custom fetch
+
+```tsx
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import type { CustomFetch } from '@tanstack/react-start'
+
+const loggingMiddleware = createMiddleware({ type: 'function' }).client(
+  async ({ next }) => {
+    const customFetch: CustomFetch = async (url, init) => {
+      console.log('Request:', url)
+      return fetch(url, init)
+    }
+    return next({ fetch: customFetch })
+  },
+)
+```
+
+Fetch precedence (highest to lowest): call site → later middleware → earlier middleware → createStart global → default fetch.
+
+## Common Mistakes
+
+### 1. HIGH: Trusting client sendContext without validation
+
+```tsx
+// WRONG — client can send arbitrary data
+.server(async ({ next, context }) => {
+  await db.query(`SELECT * FROM workspace_${context.workspaceId}`)
+  return next()
+})
+
+// CORRECT — validate before use
+.server(async ({ next, context }) => {
+  const workspaceId = z.string().uuid().parse(context.workspaceId)
+  await db.query('SELECT * FROM workspaces WHERE id = $1', [workspaceId])
+  return next()
+})
+```
+
+### 2. MEDIUM: Confusing request vs server function middleware
+
+Request middleware runs on ALL requests (SSR, routes, functions). Server function middleware runs only for `createServerFn` calls and has `.client()` method.
+
+### 3. HIGH: Browser APIs in .client() crash during SSR
+
+During SSR, `.client()` callbacks run on the server. Browser-only APIs like `localStorage` or `window` will throw `ReferenceError`:
+
+```tsx
+// WRONG — localStorage doesn't exist on the server during SSR
+const middleware = createMiddleware({ type: 'function' }).client(
+  async ({ next }) => {
+    const token = localStorage.getItem('token')
+    return next({ sendContext: { token } })
+  },
+)
+
+// CORRECT — use cookies/headers or guard with typeof window check
+const middleware = createMiddleware({ type: 'function' }).client(
+  async ({ next }) => {
+    const token =
+      typeof window !== 'undefined' ? localStorage.getItem('token') : null
+    return next({ sendContext: { token } })
+  },
+)
+```
+
+### 4. MEDIUM: Wrong method order
+
+```tsx
+// WRONG — type error
+createMiddleware({ type: 'function' })
+  .server(() => { ... })
+  .client(() => { ... })
+
+// CORRECT — middleware → inputValidator → client → server
+createMiddleware({ type: 'function' })
+  .middleware([dep])
+  .inputValidator(schema)
+  .client(({ next }) => next())
+  .server(({ next }) => next())
+```
+
+## Cross-References
+
+- [start-core/server-functions](../server-functions/SKILL.md) — what middleware wraps
+- [start-core/server-routes](../server-routes/SKILL.md) — middleware on API endpoints