Skip to content
Source
Sign inSign up
TanStack/router
Open History to see the last commit

start_domain_map.yaml

482 lines18.9 KB

1# domain_map.yaml
2# Generated by skill-domain-discovery
3# Library: TanStack Start
4# Version: 1.166.2
5# Date: 2026-03-07
6# Status: reviewed
7​
8library:
9 name: '@tanstack/react-start'
10 version: '1.166.2'
11 repository: 'https://github.com/TanStack/router'
12 description: >-
13 Full-stack React framework built on TanStack Router and Vite. Adds
14 SSR, streaming, server functions (type-safe RPCs), middleware,
15 server routes, and universal deployment. Isomorphic by default β€”
16 all code runs in both environments unless explicitly constrained.
17 primary_framework: 'React'
18​
19domains:
20 - name: 'Project Setup'
21 slug: 'project-setup'
22 description: >-
23 Scaffolding a Start project, configuring Vite plugin, router
24 setup with getRouter(), root route with document shell, client
25 and server entry points.
26​
27 - name: 'Server Functions'
28 slug: 'server-functions'
29 description: >-
30 Creating type-safe RPCs with createServerFn, input validation,
31 calling from loaders/components/other server functions, error
32 handling, streaming responses.
33​
34 - name: 'Middleware and Context'
35 slug: 'middleware-and-context'
36 description: >-
37 Request middleware, server function middleware, context passing
38 with sendContext, global middleware via createStart, middleware
39 factories, fetch override precedence.
40​
41 - name: 'Execution Model'
42 slug: 'execution-model'
43 description: >-
44 Isomorphic code execution, environment functions
45 (createServerFn, createServerOnlyFn, createClientOnlyFn,
46 createIsomorphicFn), import protection, dead code elimination,
47 environment variable safety.
48​
49 - name: 'Server Routes'
50 slug: 'server-routes'
51 description: >-
52 Server-side API endpoints defined in routes, HTTP method
53 handlers, handler middleware, request/response patterns.
54​
55 - name: 'Deployment and Rendering'
56 slug: 'deployment-and-rendering'
57 description: >-
58 Hosting providers (Cloudflare, Netlify, Vercel, Node/Docker),
59 selective SSR, SPA mode, static prerendering, ISR with
60 Cache-Control headers, SEO and head management.
61​
62skills:
63 # ── Project Setup ────────────────────────────────────────────────
64 - name: 'Start Setup'
65 slug: 'start-setup'
66 domain: 'project-setup'
67 description: >-
68 Scaffold a TanStack Start project, configure Vite plugin with
69 tanstackStart(), set up router with getRouter(), create root
70 route with document shell (HeadContent, Scripts, Outlet),
71 configure client and server entry points.
72 type: core
73 packages:
74 - '@tanstack/react-start'
75 - '@tanstack/start-plugin-core'
76 covers:
77 - tanstackStart Vite plugin
78 - getRouter() factory pattern
79 - Root route document shell
80 - HeadContent / Scripts / Outlet
81 - Client entry point (optional)
82 - Server entry point (optional)
83 - routeTree.gen.ts
84 - tsconfig configuration
85 tasks:
86 - 'Scaffold a new TanStack Start project'
87 - 'Configure the Vite plugin'
88 - 'Set up the router factory'
89 - 'Customize client/server entry points'
90 failure_modes:
91 - mistake: 'React plugin before Start plugin in Vite config'
92 mechanism: >-
93 Start's Vite plugin must come before React's plugin.
94 Wrong order causes route generation and server function
95 compilation to fail.
96 wrong_pattern: |
97 plugins: [react(), tanstackStart()]
98 correct_pattern: |
99 plugins: [tanstackStart(), react()]
100 source: 'docs/start/framework/react/build-from-scratch.md'
101 priority: CRITICAL
102 status: active
103​
104 - mistake: 'Enabling verbatimModuleSyntax in tsconfig'
105 mechanism: >-
106 verbatimModuleSyntax causes server bundles to leak into
107 client bundles. Must be disabled.
108 source: 'docs/start/framework/react/build-from-scratch.md'
109 priority: HIGH
110 status: active
111​
112 - mistake: 'Missing Scripts component in root route'
113 mechanism: >-
114 The Scripts component must be rendered in the body of
115 the root route for proper hydration and functionality.
116 Without it, client-side JavaScript does not load.
117 source: 'docs/start/framework/react/guide/routing.md'
118 priority: HIGH
119 status: active
120​
121 # ── Server Functions ─────────────────────────────────────────────
122 - name: 'Server Functions'
123 slug: 'server-functions'
124 domain: 'server-functions'
125 description: >-
126 Create type-safe RPCs with createServerFn, validate inputs
127 with Zod or plain functions, call from loaders/components/
128 event handlers, handle errors/redirects/notFound, stream
129 responses with ReadableStream or async generators.
130 type: core
131 packages:
132 - '@tanstack/react-start'
133 - '@tanstack/start-client-core'
134 - '@tanstack/start-server-core'
135 covers:
136 - createServerFn (GET/POST)
137 - validator (Zod or function)
138 - useServerFn hook
139 - Server context utilities (getRequest, getRequestHeader, setResponseHeader, setResponseStatus)
140 - Error handling (throw errors, redirect, notFound)
141 - Streaming (ReadableStream, async generators)
142 - File organization (.functions.ts, .server.ts)
143 - FormData handling
144 tasks:
145 - 'Create a server function for data fetching'
146 - 'Validate server function inputs'
147 - 'Call server functions from components'
148 - 'Stream data from server functions'
149 - 'Handle errors in server functions'
150 failure_modes:
151 - mistake: 'Putting server-only code in loaders instead of server functions'
152 mechanism: >-
153 Loaders are ISOMORPHIC β€” they run on both client and server.
154 Database queries, file system access, and secret API keys
155 in loaders will either fail on the client or leak to the
156 client bundle. Use createServerFn for server-only logic.
157 wrong_pattern: |
158 export const Route = createFileRoute('/posts')({
159 loader: async () => {
160 const posts = await db.query('SELECT * FROM posts')
161 return { posts }
162 },
163 })
164 correct_pattern: |
165 const getPosts = createServerFn({ method: 'GET' })
166 .handler(async () => {
167 const posts = await db.query('SELECT * FROM posts')
168 return { posts }
169 })
170​
171 export const Route = createFileRoute('/posts')({
172 loader: () => getPosts(),
173 })
174 source: 'maintainer interview'
175 priority: CRITICAL
176 status: active
177 skills: ['server-functions', 'execution-model']
178​
179 - mistake: 'Using dynamic imports for server functions'
180 mechanism: >-
181 Dynamic imports of server functions can cause bundler
182 issues. Static imports are safe β€” the build process
183 replaces server implementations with RPC stubs.
184 wrong_pattern: |
185 const { getUser } = await import('~/utils/users.functions')
186 correct_pattern: |
187 import { getUser } from '~/utils/users.functions'
188 source: 'docs/start/framework/react/guide/server-functions.md'
189 priority: HIGH
190 status: active
191​
192 - mistake: 'Generating Next.js or Remix server patterns'
193 mechanism: >-
194 Agents generate getServerSideProps, "use server" directives,
195 or Remix-style loader exports. TanStack Start uses
196 createServerFn for server-only code.
197 wrong_pattern: |
198 'use server'
199 export async function getUser() { ... }
200 correct_pattern: |
201 const getUser = createServerFn({ method: 'GET' })
202 .handler(async () => { ... })
203 source: 'maintainer interview'
204 priority: CRITICAL
205 status: active
206​
207 # ── Middleware and Context ───────────────────────────────────────
208 - name: 'Middleware'
209 slug: 'middleware'
210 domain: 'middleware-and-context'
211 description: >-
212 Request middleware and server function middleware with
213 createMiddleware, context passing via next(), sendContext
214 for client-server transfer, global middleware via createStart
215 in src/start.ts, middleware factories, fetch override
216 precedence, header merging.
217 type: core
218 packages:
219 - '@tanstack/react-start'
220 - '@tanstack/start-client-core'
221 - '@tanstack/start-server-core'
222 covers:
223 - createMiddleware
224 - Request middleware (.server only)
225 - Server function middleware (.client + .server)
226 - Context passing via next({ context })
227 - sendContext for client-server transfer
228 - Global middleware (createStart in src/start.ts)
229 - Middleware factories
230 - Fetch override precedence
231 - Header merging
232 - Method order enforcement (middleware β†’ validator β†’ client β†’ server)
233 tasks:
234 - 'Add authentication middleware'
235 - 'Pass context through middleware chain'
236 - 'Configure global request middleware'
237 - 'Create reusable middleware factories'
238 failure_modes:
239 - mistake: 'Trusting client context without server validation'
240 mechanism: >-
241 Client context via sendContext is NOT validated by default.
242 Dynamic user-generated data must be validated in server-side
243 middleware before use.
244 source: 'docs/start/framework/react/guide/middleware.md'
245 priority: HIGH
246 status: active
247​
248 - mistake: 'Wrong middleware method order'
249 mechanism: >-
250 TypeScript enforces method order: middleware β†’ validator
251 β†’ client β†’ server. Wrong order causes type errors and
252 runtime failures.
253 source: 'docs/start/framework/react/guide/middleware.md'
254 priority: MEDIUM
255 status: active
256​
257 - mistake: 'Confusing request vs server function middleware'
258 mechanism: >-
259 Request middleware runs on ALL server requests (SSR, server
260 routes, server functions). Server function middleware runs
261 only for server functions and has .client() method. Using
262 the wrong type causes unexpected scope.
263 source: 'docs/start/framework/react/guide/middleware.md'
264 priority: MEDIUM
265 status: active
266​
267 # ── Execution Model ──────────────────────────────────────────────
268 - name: 'Execution Model'
269 slug: 'execution-model'
270 domain: 'execution-model'
271 description: >-
272 Isomorphic code execution model, environment boundary functions
273 (createServerFn, createServerOnlyFn, createClientOnlyFn,
274 createIsomorphicFn), import protection, dead code elimination,
275 environment variable safety (VITE_ prefix), useHydrated hook.
276 type: core
277 packages:
278 - '@tanstack/react-start'
279 - '@tanstack/start-client-core'
280 - '@tanstack/start-server-core'
281 covers:
282 - Isomorphic-by-default principle
283 - createServerFn (RPC boundary)
284 - createServerOnlyFn (throws on client)
285 - createClientOnlyFn (throws on server)
286 - createIsomorphicFn (different impl per env)
287 - ClientOnly component
288 - useHydrated hook
289 - Import protection (experimental)
290 - Environment variables (VITE_ prefix, process.env)
291 - Dead code elimination / tree shaking
292 tasks:
293 - 'Protect server-only code from client bundles'
294 - 'Use environment-specific implementations'
295 - 'Handle environment variables safely'
296 - 'Debug import protection violations'
297 failure_modes:
298 - mistake: 'Assuming loaders are server-only'
299 mechanism: >-
300 ALL code in TanStack Start is isomorphic by default.
301 Loaders run on BOTH server and client. Server-only
302 operations must use createServerFn, createServerOnlyFn,
303 or server routes.
304 wrong_pattern: |
305 export const Route = createFileRoute('/dashboard')({
306 loader: async () => {
307 const secret = process.env.API_SECRET
308 return fetch(`https://api.example.com/data`, {
309 headers: { Authorization: secret }
310 })
311 },
312 })
313 correct_pattern: |
314 const getData = createServerFn({ method: 'GET' })
315 .handler(async () => {
316 const secret = process.env.API_SECRET
317 return fetch(`https://api.example.com/data`, {
318 headers: { Authorization: secret }
319 })
320 })
321​
322 export const Route = createFileRoute('/dashboard')({
323 loader: () => getData(),
324 })
325 source: 'docs/start/framework/react/guide/execution-model.md'
326 priority: CRITICAL
327 status: active
328 skills: ['execution-model', 'server-functions']
329​
330 - mistake: 'Exposing secrets via module-level process.env'
331 mechanism: >-
332 Module-level process.env access runs in both environments.
333 The variable value leaks into the client bundle. Access
334 secrets only inside createServerFn or createServerOnlyFn.
335 wrong_pattern: |
336 const apiKey = process.env.SECRET_KEY
337 export function fetchData() { ... }
338 correct_pattern: |
339 const fetchData = createServerFn({ method: 'GET' })
340 .handler(async () => {
341 const apiKey = process.env.SECRET_KEY
342 return fetch(url, { headers: { Authorization: apiKey } })
343 })
344 source: 'docs/start/framework/react/guide/execution-model.md'
345 priority: CRITICAL
346 status: active
347​
348 - mistake: 'Using VITE_ prefix for server secrets'
349 mechanism: >-
350 VITE_ prefixed variables are exposed to the client bundle.
351 Server secrets must NOT have the VITE_ prefix. Access
352 them via process.env inside server functions only.
353 source: 'docs/start/framework/react/guide/environment-variables.md'
354 priority: CRITICAL
355 status: active
356​
357 # ── Server Routes ────────────────────────────────────────────────
358 - name: 'Server Routes'
359 slug: 'server-routes'
360 domain: 'server-routes'
361 description: >-
362 Define server-side API endpoints alongside app routes using
363 the server property with HTTP method handlers, per-handler
364 middleware via createHandlers, request/response patterns.
365 type: core
366 packages:
367 - '@tanstack/react-start'
368 - '@tanstack/start-server-core'
369 covers:
370 - server property on createFileRoute
371 - handlers object (GET, POST, PUT, DELETE)
372 - createHandlers for per-handler middleware
373 - Handler context (request, params, context)
374 - Request body parsing (json, text, formData)
375 - Response helpers (Response.json)
376 - File naming for API routes
377 tasks:
378 - 'Create a REST API endpoint'
379 - 'Add middleware to server route handlers'
380 - 'Handle different HTTP methods'
381 failure_modes:
382 - mistake: 'Duplicate path resolution for server routes'
383 mechanism: >-
384 Each route can only have a single handler file. Having
385 both users.ts and users/index.ts causes errors.
386 source: 'docs/start/framework/react/guide/server-routes.md'
387 priority: MEDIUM
388 status: active
389​
390 # ── Deployment and Rendering ─────────────────────────────────────
391 - name: 'Deployment'
392 slug: 'deployment'
393 domain: 'deployment-and-rendering'
394 description: >-
395 Deploy TanStack Start to Cloudflare Workers, Netlify, Vercel,
396 Node.js/Docker, Bun, Railway. Configure selective SSR, SPA
397 mode, static prerendering, ISR with Cache-Control headers.
398 type: core
399 packages:
400 - '@tanstack/react-start'
401 - '@tanstack/start-plugin-core'
402 covers:
403 - Cloudflare Workers deployment
404 - Netlify deployment
405 - Vercel / Railway deployment
406 - Node.js / Docker deployment
407 - Bun deployment
408 - Selective SSR (ssr option per route)
409 - SPA mode configuration
410 - Static prerendering (prerender option)
411 - ISR with Cache-Control headers
412 - SEO (head property, structured data)
413 tasks:
414 - 'Deploy to Cloudflare Workers'
415 - 'Deploy to Netlify'
416 - 'Configure selective SSR per route'
417 - 'Enable SPA mode'
418 - 'Set up static prerendering'
419 - 'Configure ISR with cache headers'
420 failure_modes:
421 - mistake: 'Bun deployment with React 18'
422 mechanism: >-
423 Bun-specific deployment only works with React 19.
424 For React 18, use Node.js deployment guidelines.
425 source: 'docs/start/framework/react/guide/hosting.md'
426 priority: MEDIUM
427 status: active
428​
429 - mistake: 'Missing nodejs_compat flag for Cloudflare Workers'
430 mechanism: >-
431 Cloudflare Workers requires compatibility_flags:
432 ["nodejs_compat"] in wrangler config. Without it,
433 Node.js APIs used by Start fail at runtime.
434 source: 'docs/start/framework/react/guide/hosting.md'
435 priority: HIGH
436 status: active
437​
438 - mistake: 'Child route loosening parent SSR config'
439 mechanism: >-
440 SSR config inherits from parent and can only become MORE
441 restrictive (true β†’ data-only β†’ false). A child cannot
442 set ssr: true if parent has ssr: false.
443 source: 'docs/start/framework/react/guide/selective-ssr.md'
444 priority: MEDIUM
445 status: active
446​
447tensions:
448 - name: 'Isomorphic defaults vs server-only expectations'
449 skills: ['execution-model', 'server-functions']
450 description: >-
451 All code runs everywhere by default. Agents trained on
452 Next.js/Remix assume loaders and route code are server-only.
453 implication: >-
454 Agents put secrets, DB queries, and file system access in
455 loaders instead of server functions, causing client-side
456 failures or security leaks.
457​
458 - name: 'Simplicity of isomorphic code vs security boundaries'
459 skills: ['execution-model', 'middleware']
460 description: >-
461 The isomorphic model makes code easy to write but requires
462 explicit boundaries for security. Agents don't realize they
463 need to actively constrain execution environment.
464 implication: >-
465 Agents expose secrets via module-level process.env or
466 forget to validate sendContext data in middleware.
467​
468cross_references:
469 - from: 'server-functions'
470 to: 'execution-model'
471 reason: 'Server functions ARE the isomorphic boundary β€” understanding the execution model is prerequisite'
472 - from: 'server-functions'
473 to: 'middleware'
474 reason: 'Server function middleware chains compose with server functions'
475 - from: 'middleware'
476 to: 'server-routes'
477 reason: 'Server routes use the same middleware system'
478 - from: 'deployment'
479 to: 'execution-model'
480 reason: 'Deployment target affects which environment code runs in'
481​
482gaps: []