# domain_map.yaml # Generated by skill-domain-discovery # Library: TanStack Start # Version: 1.166.2 # Date: 2026-03-07 # Status: reviewed library: name: '@tanstack/react-start' version: '1.166.2' repository: 'https://github.com/TanStack/router' description: >- Full-stack React framework built on TanStack Router and Vite. Adds SSR, streaming, server functions (type-safe RPCs), middleware, server routes, and universal deployment. Isomorphic by default — all code runs in both environments unless explicitly constrained. primary_framework: 'React' domains: - name: 'Project Setup' slug: 'project-setup' description: >- Scaffolding a Start project, configuring Vite plugin, router setup with getRouter(), root route with document shell, client and server entry points. - name: 'Server Functions' slug: 'server-functions' description: >- Creating type-safe RPCs with createServerFn, input validation, calling from loaders/components/other server functions, error handling, streaming responses. - name: 'Middleware and Context' slug: 'middleware-and-context' description: >- Request middleware, server function middleware, context passing with sendContext, global middleware via createStart, middleware factories, fetch override precedence. - name: 'Execution Model' slug: 'execution-model' description: >- Isomorphic code execution, environment functions (createServerFn, createServerOnlyFn, createClientOnlyFn, createIsomorphicFn), import protection, dead code elimination, environment variable safety. - name: 'Server Routes' slug: 'server-routes' description: >- Server-side API endpoints defined in routes, HTTP method handlers, handler middleware, request/response patterns. - name: 'Deployment and Rendering' slug: 'deployment-and-rendering' description: >- Hosting providers (Cloudflare, Netlify, Vercel, Node/Docker), selective SSR, SPA mode, static prerendering, ISR with Cache-Control headers, SEO and head management. skills: # ── Project Setup ──────────────────────────────────────────────── - name: 'Start Setup' slug: 'start-setup' domain: 'project-setup' description: >- Scaffold a TanStack Start project, configure Vite plugin with tanstackStart(), set up router with getRouter(), create root route with document shell (HeadContent, Scripts, Outlet), configure client and server entry points. type: core packages: - '@tanstack/react-start' - '@tanstack/start-plugin-core' covers: - tanstackStart Vite plugin - getRouter() factory pattern - Root route document shell - HeadContent / Scripts / Outlet - Client entry point (optional) - Server entry point (optional) - routeTree.gen.ts - tsconfig configuration tasks: - 'Scaffold a new TanStack Start project' - 'Configure the Vite plugin' - 'Set up the router factory' - 'Customize client/server entry points' failure_modes: - mistake: 'React plugin before Start plugin in Vite config' mechanism: >- Start's Vite plugin must come before React's plugin. Wrong order causes route generation and server function compilation to fail. wrong_pattern: | plugins: [react(), tanstackStart()] correct_pattern: | plugins: [tanstackStart(), react()] source: 'docs/start/framework/react/build-from-scratch.md' priority: CRITICAL status: active - mistake: 'Enabling verbatimModuleSyntax in tsconfig' mechanism: >- verbatimModuleSyntax causes server bundles to leak into client bundles. Must be disabled. source: 'docs/start/framework/react/build-from-scratch.md' priority: HIGH status: active - mistake: 'Missing Scripts component in root route' mechanism: >- The Scripts component must be rendered in the body of the root route for proper hydration and functionality. Without it, client-side JavaScript does not load. source: 'docs/start/framework/react/guide/routing.md' priority: HIGH status: active # ── Server Functions ───────────────────────────────────────────── - name: 'Server Functions' slug: 'server-functions' domain: 'server-functions' description: >- Create type-safe RPCs with createServerFn, validate inputs with Zod or plain functions, call from loaders/components/ event handlers, handle errors/redirects/notFound, stream responses with ReadableStream or async generators. type: core packages: - '@tanstack/react-start' - '@tanstack/start-client-core' - '@tanstack/start-server-core' covers: - createServerFn (GET/POST) - inputValidator (Zod or function) - useServerFn hook - Server context utilities (getRequest, getRequestHeader, setResponseHeader, setResponseStatus) - Error handling (throw errors, redirect, notFound) - Streaming (ReadableStream, async generators) - File organization (.functions.ts, .server.ts) - FormData handling tasks: - 'Create a server function for data fetching' - 'Validate server function inputs' - 'Call server functions from components' - 'Stream data from server functions' - 'Handle errors in server functions' failure_modes: - mistake: 'Putting server-only code in loaders instead of server functions' mechanism: >- Loaders are ISOMORPHIC — they run on both client and server. Database queries, file system access, and secret API keys in loaders will either fail on the client or leak to the client bundle. Use createServerFn for server-only logic. wrong_pattern: | export const Route = createFileRoute('/posts')({ loader: async () => { const posts = await db.query('SELECT * FROM posts') return { posts } }, }) correct_pattern: | const getPosts = createServerFn({ method: 'GET' }) .handler(async () => { const posts = await db.query('SELECT * FROM posts') return { posts } }) export const Route = createFileRoute('/posts')({ loader: () => getPosts(), }) source: 'maintainer interview' priority: CRITICAL status: active skills: ['server-functions', 'execution-model'] - mistake: 'Using dynamic imports for server functions' mechanism: >- Dynamic imports of server functions can cause bundler issues. Static imports are safe — the build process replaces server implementations with RPC stubs. wrong_pattern: | const { getUser } = await import('~/utils/users.functions') correct_pattern: | import { getUser } from '~/utils/users.functions' source: 'docs/start/framework/react/guide/server-functions.md' priority: HIGH status: active - mistake: 'Generating Next.js or Remix server patterns' mechanism: >- Agents generate getServerSideProps, "use server" directives, or Remix-style loader exports. TanStack Start uses createServerFn for server-only code. wrong_pattern: | 'use server' export async function getUser() { ... } correct_pattern: | const getUser = createServerFn({ method: 'GET' }) .handler(async () => { ... }) source: 'maintainer interview' priority: CRITICAL status: active # ── Middleware and Context ─────────────────────────────────────── - name: 'Middleware' slug: 'middleware' domain: 'middleware-and-context' description: >- Request middleware and server function middleware with createMiddleware, context passing via next(), sendContext for client-server transfer, global middleware via createStart in src/start.ts, middleware factories, fetch override precedence, header merging. type: core packages: - '@tanstack/react-start' - '@tanstack/start-client-core' - '@tanstack/start-server-core' covers: - createMiddleware - Request middleware (.server only) - Server function middleware (.client + .server) - Context passing via next({ context }) - sendContext for client-server transfer - Global middleware (createStart in src/start.ts) - Middleware factories - Fetch override precedence - Header merging - Method order enforcement (middleware → inputValidator → client → server) tasks: - 'Add authentication middleware' - 'Pass context through middleware chain' - 'Configure global request middleware' - 'Create reusable middleware factories' failure_modes: - mistake: 'Trusting client context without server validation' mechanism: >- Client context via sendContext is NOT validated by default. Dynamic user-generated data must be validated in server-side middleware before use. source: 'docs/start/framework/react/guide/middleware.md' priority: HIGH status: active - mistake: 'Wrong middleware method order' mechanism: >- TypeScript enforces method order: middleware → inputValidator → client → server. Wrong order causes type errors and runtime failures. source: 'docs/start/framework/react/guide/middleware.md' priority: MEDIUM status: active - mistake: 'Confusing request vs server function middleware' mechanism: >- Request middleware runs on ALL server requests (SSR, server routes, server functions). Server function middleware runs only for server functions and has .client() method. Using the wrong type causes unexpected scope. source: 'docs/start/framework/react/guide/middleware.md' priority: MEDIUM status: active # ── Execution Model ────────────────────────────────────────────── - name: 'Execution Model' slug: 'execution-model' domain: 'execution-model' description: >- Isomorphic code execution model, environment boundary functions (createServerFn, createServerOnlyFn, createClientOnlyFn, createIsomorphicFn), import protection, dead code elimination, environment variable safety (VITE_ prefix), useHydrated hook. type: core packages: - '@tanstack/react-start' - '@tanstack/start-client-core' - '@tanstack/start-server-core' covers: - Isomorphic-by-default principle - createServerFn (RPC boundary) - createServerOnlyFn (throws on client) - createClientOnlyFn (throws on server) - createIsomorphicFn (different impl per env) - ClientOnly component - useHydrated hook - Import protection (experimental) - Environment variables (VITE_ prefix, process.env) - Dead code elimination / tree shaking tasks: - 'Protect server-only code from client bundles' - 'Use environment-specific implementations' - 'Handle environment variables safely' - 'Debug import protection violations' failure_modes: - mistake: 'Assuming loaders are server-only' mechanism: >- ALL code in TanStack Start is isomorphic by default. Loaders run on BOTH server and client. Server-only operations must use createServerFn, createServerOnlyFn, or server routes. wrong_pattern: | export const Route = createFileRoute('/dashboard')({ loader: async () => { const secret = process.env.API_SECRET return fetch(`https://api.example.com/data`, { headers: { Authorization: secret } }) }, }) correct_pattern: | 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(), }) source: 'docs/start/framework/react/guide/execution-model.md' priority: CRITICAL status: active skills: ['execution-model', 'server-functions'] - mistake: 'Exposing secrets via module-level process.env' mechanism: >- Module-level process.env access runs in both environments. The variable value leaks into the client bundle. Access secrets only inside createServerFn or createServerOnlyFn. wrong_pattern: | const apiKey = process.env.SECRET_KEY export function fetchData() { ... } correct_pattern: | const fetchData = createServerFn({ method: 'GET' }) .handler(async () => { const apiKey = process.env.SECRET_KEY return fetch(url, { headers: { Authorization: apiKey } }) }) source: 'docs/start/framework/react/guide/execution-model.md' priority: CRITICAL status: active - mistake: 'Using VITE_ prefix for server secrets' mechanism: >- VITE_ prefixed variables are exposed to the client bundle. Server secrets must NOT have the VITE_ prefix. Access them via process.env inside server functions only. source: 'docs/start/framework/react/guide/environment-variables.md' priority: CRITICAL status: active # ── Server Routes ──────────────────────────────────────────────── - name: 'Server Routes' slug: 'server-routes' domain: 'server-routes' description: >- Define server-side API endpoints alongside app routes using the server property with HTTP method handlers, per-handler middleware via createHandlers, request/response patterns. type: core packages: - '@tanstack/react-start' - '@tanstack/start-server-core' covers: - server property on createFileRoute - handlers object (GET, POST, PUT, DELETE) - createHandlers for per-handler middleware - Handler context (request, params, context) - Request body parsing (json, text, formData) - Response helpers (Response.json) - File naming for API routes tasks: - 'Create a REST API endpoint' - 'Add middleware to server route handlers' - 'Handle different HTTP methods' failure_modes: - mistake: 'Duplicate path resolution for server routes' mechanism: >- Each route can only have a single handler file. Having both users.ts and users/index.ts causes errors. source: 'docs/start/framework/react/guide/server-routes.md' priority: MEDIUM status: active # ── Deployment and Rendering ───────────────────────────────────── - name: 'Deployment' slug: 'deployment' domain: 'deployment-and-rendering' description: >- Deploy TanStack Start to Cloudflare Workers, Netlify, Vercel, Node.js/Docker, Bun, Railway. Configure selective SSR, SPA mode, static prerendering, ISR with Cache-Control headers. type: core packages: - '@tanstack/react-start' - '@tanstack/start-plugin-core' covers: - Cloudflare Workers deployment - Netlify deployment - Vercel / Railway deployment - Node.js / Docker deployment - Bun deployment - Selective SSR (ssr option per route) - SPA mode configuration - Static prerendering (prerender option) - ISR with Cache-Control headers - SEO (head property, structured data) tasks: - 'Deploy to Cloudflare Workers' - 'Deploy to Netlify' - 'Configure selective SSR per route' - 'Enable SPA mode' - 'Set up static prerendering' - 'Configure ISR with cache headers' failure_modes: - mistake: 'Bun deployment with React 18' mechanism: >- Bun-specific deployment only works with React 19. For React 18, use Node.js deployment guidelines. source: 'docs/start/framework/react/guide/hosting.md' priority: MEDIUM status: active - mistake: 'Missing nodejs_compat flag for Cloudflare Workers' mechanism: >- Cloudflare Workers requires compatibility_flags: ["nodejs_compat"] in wrangler config. Without it, Node.js APIs used by Start fail at runtime. source: 'docs/start/framework/react/guide/hosting.md' priority: HIGH status: active - mistake: 'Child route loosening parent SSR config' mechanism: >- SSR config inherits from parent and can only become MORE restrictive (true → data-only → false). A child cannot set ssr: true if parent has ssr: false. source: 'docs/start/framework/react/guide/selective-ssr.md' priority: MEDIUM status: active tensions: - name: 'Isomorphic defaults vs server-only expectations' skills: ['execution-model', 'server-functions'] description: >- All code runs everywhere by default. Agents trained on Next.js/Remix assume loaders and route code are server-only. implication: >- Agents put secrets, DB queries, and file system access in loaders instead of server functions, causing client-side failures or security leaks. - name: 'Simplicity of isomorphic code vs security boundaries' skills: ['execution-model', 'middleware'] description: >- The isomorphic model makes code easy to write but requires explicit boundaries for security. Agents don't realize they need to actively constrain execution environment. implication: >- Agents expose secrets via module-level process.env or forget to validate sendContext data in middleware. cross_references: - from: 'server-functions' to: 'execution-model' reason: 'Server functions ARE the isomorphic boundary — understanding the execution model is prerequisite' - from: 'server-functions' to: 'middleware' reason: 'Server function middleware chains compose with server functions' - from: 'middleware' to: 'server-routes' reason: 'Server routes use the same middleware system' - from: 'deployment' to: 'execution-model' reason: 'Deployment target affects which environment code runs in' gaps: []