0
Fork 0
mirror of https://github.com/TanStack/router.git synced 2026-11-16 19:38:07 +00:00
router/_artifacts/skill_spec.md
Tanner Linsley 940151cbed
feat: add @tanstack/intent AI agent skills for Router and Start (#6866)
* feat: add @tanstack/intent AI agent skills for Router and Start

Add SKILL.md files across 11 packages to help AI coding agents generate
correct TanStack Router and Start code. Skills cover common patterns,
API usage, and failure modes that agents frequently get wrong.

Packages with skills:
- router-core (10 skills): core concepts, search/path params, navigation,
  data loading, auth/guards, code splitting, not-found/errors, type safety, SSR
- react-router (3): React bindings, Router+Query composition, migration from React Router
- start-client-core (6): Start setup, server functions, middleware,
  execution model, server routes, deployment
- react-start (2): React Start bindings, migration from Next.js
- virtual-file-routes (1): programmatic route tree building
- router-plugin (1): bundler plugin configuration
- start-server-core (1): server-side runtime
- solid-router (1): Solid bindings
- vue-router (1): Vue bindings
- solid-start (1): Solid Start bindings
- vue-start (1): Vue Start bindings

Each package includes bin/intent.js shim, _artifacts/ metadata, and
@tanstack/intent devDependency.

* fix: address PR review comments on skill files

- Fix incorrect createTanstackRouter → createRouter in router-query examples
- Fix missing React type imports (ComponentPropsWithoutRef, FormEvent)
- Fix hardcoded localhost:3000 in SSR example, use req headers instead
- Fix session.update/clear to use await with data payload
- Fix start-setup → start-core slug mismatch in domain_map + skill_spec
- Make start-client-core skill_tree self-contained (remove react-start refs)
- Add framework-agnostic comments to execution-model and middleware skills
- Make virtual-file-routes vite example framework-agnostic
- Fix solid-router domain_map: Link is primary, createLink for wrappers
- Fix vue-router domain_map: scope Ref unwrapping to script, not templates
- Fix vue-router SKILL.md: tsx → vue fence language for template snippets
- Fix virtual-file-routes domain_map failure mode wording
- Fix MD028 blockquote blank lines across 11 files
- Fix MD040 missing fence languages across 4 files
- Update pnpm-lock.yaml

* fix: address review feedback and audit all 28 skills against source

- Address all 9 Sheraff review comments (ensureQueryData, auth patterns,
  open redirect, useLocation migration, reusable components, zodValidator)
- Address all 11 actionable CodeRabbit comments (naming collisions,
  framework-agnostic comments, missing imports, bin/intent.js error handling)
- Full source-verified audit of all 28 skills across 7 re-audited packages
- Fix solid-start: add HydrationScript, move HeadContent to body, use
  shellComponent pattern
- Fix solid-router: useLoaderDeps returns Accessor<T>, ScrollRestoration
  deprecated, add missing hooks/components
- Fix vue-router: useLinkProps returns LinkHTMLAttributes, useLoaderDeps
  returns Ref<T>, fix split-file convention
- Fix start-server-core: correct file path, server fn prefix, getValidatedQuery
  API, add createServerFn imports to all examples
- Fix router-core skills: preloadStaleTime wording, loader route param,
  error retry pattern, search-params adapter scoping
- All 28 skills pass @tanstack/intent validate

* chore: add changeset for intent skills feature
2026-03-16 16:54:37 -06:00

18 KiB

TanStack Router — Skill Spec

TanStack Router is a type-safe router for React and Solid applications with built-in SWR caching, JSON-first search params, file-based route generation, and end-to-end type inference. It is client-first/isomorphic — loaders run on the client by default and additionally on the server when used with TanStack Start.

Domains

Domain Description Skills
Defining Routes Setting up route trees, configuring the router, registering types route-setup, migrate-from-react-router
Navigating Links, imperative navigation, preloading, blocking navigation
Managing URL State Search params and path params with validation and serialization search-params, path-params
Loading Data Route loaders, SWR caching, external cache coordination, context/DI data-loading, external-data-loading
Protecting Routes Auth guards, RBAC, beforeLoad redirects auth-and-guards
Rendering and Layout Code splitting, error/not-found handling, route masking code-splitting, not-found-and-errors, route-masking
Type Safety Inference patterns, narrowing, TS performance type-safety
Server-Side Rendering SSR setup, hydration, head management ssr

Skill Inventory

Skill Type Domain What it covers Failure modes
route-setup core defining-routes createRouter, file/code/virtual routing, Register, plugin config, ESLint 5
navigation core navigating Link, useNavigate, Navigate, preloading, blocking, active states, scroll restoration 4
search-params core managing-url-state validateSearch, useSearch, middlewares, serialization, adapters 4
path-params core managing-url-state $params, splats, optional params, prefix/suffix patterns 3
data-loading core loading-data loader, loaderDeps, staleTime/gcTime, pending/error, context/DI, deferred 5
external-data-loading composition loading-data TanStack Query integration, SSR dehydration/hydration, streaming 3
auth-and-guards core protecting-routes beforeLoad redirects, layout auth, RBAC, provider integration 3
code-splitting core rendering-and-layout autoCodeSplitting, .lazy.tsx, getRouteApi, split groupings 4
not-found-and-errors core rendering-and-layout notFound(), notFoundComponent, errorComponent, CatchBoundary 3
route-masking core rendering-and-layout mask option, createRouteMask, unmaskOnReload 1
type-safety core type-safety Register, from narrowing, TS perf, type utilities 3
ssr core server-side-rendering RouterClient/Server, streaming, hydration, head management 3
migrate-from-react-router lifecycle defining-routes Migration checklist, API mapping, search params conversion 2

Failure Mode Inventory

route-setup (5 failure modes)

# Mistake Priority Source Cross-skill?
1 Missing router type registration CRITICAL docs/guide/creating-a-router type-safety
2 Not committing routeTree.gen.ts HIGH docs/faq —
3 Wrong route property order breaks type inference HIGH docs/eslint/create-route-property-order —
4 Placing TanStackRouter plugin after framework plugin HIGH docs/installation/with-vite —
5 Using getParentRoute incorrectly in code-based routing HIGH docs/decisions-on-dx —

navigation (4 failure modes)

# Mistake Priority Source Cross-skill?
1 Interpolating params into the to string CRITICAL docs/guide/navigation type-safety
2 Using useNavigate instead of Link for clickable elements MEDIUM docs/guide/navigation —
3 Not providing from for relative navigation HIGH docs/guide/navigation —
4 Using search as object instead of function loses params HIGH docs/how-to/navigate-with-search-params search-params

search-params (4 failure modes)

# Mistake Priority Source Cross-skill?
1 Using zod .catch() instead of adapter fallback() HIGH docs/guide/search-params —
2 Returning entire search object from loaderDeps HIGH docs/guide/data-loading data-loading
3 Passing Date objects in search params HIGH docs/how-to/arrays-objects-dates —
4 Parent route missing validateSearch blocks inheritance MEDIUM docs/how-to/share-search-params —

path-params (3 failure modes)

# Mistake Priority Source Cross-skill?
1 Interpolating path params into to string CRITICAL docs/guide/navigation navigation
2 Using * for splat routes instead of $ MEDIUM docs/routing/routing-concepts —
3 Using curly braces for basic dynamic segments MEDIUM docs/guide/path-params —

data-loading (5 failure modes)

# Mistake Priority Source Cross-skill?
1 Assuming loaders only run on the server CRITICAL maintainer interview ssr
2 Not understanding staleTime default is 0 MEDIUM docs/guide/data-loading —
3 Using reset() instead of router.invalidate() in error components HIGH docs/guide/data-loading —
4 Double parentheses missing on createRootRouteWithContext HIGH docs/guide/data-loading —
5 Using React hooks in beforeLoad or loader HIGH docs/guide/router-context —

external-data-loading (3 failure modes)

# Mistake Priority Source Cross-skill?
1 Not setting defaultPreloadStaleTime to 0 HIGH docs/guide/external-data-loading —
2 Creating QueryClient outside createRouter for SSR HIGH docs/guide/external-data-loading —
3 Awaiting prefetchQuery in loader blocks rendering MEDIUM docs/integrations/query —

auth-and-guards (3 failure modes)

# Mistake Priority Source Cross-skill?
1 Auth check in component instead of beforeLoad HIGH docs/how-to/setup-authentication —
2 Not re-throwing redirects in try/catch HIGH docs/guide/authenticated-routes —
3 Trying to conditionally render root route component MEDIUM docs/faq —

code-splitting (4 failure modes)

# Mistake Priority Source Cross-skill?
1 Exporting route property functions prevents code splitting HIGH docs/guide/automatic-code-splitting —
2 Trying to code-split the root route MEDIUM docs/guide/code-splitting —
3 Splitting the loader adds double async cost MEDIUM docs/guide/code-splitting —
4 Importing Route in code-split files for typed hooks HIGH docs/guide/code-splitting —

not-found-and-errors (3 failure modes)

# Mistake Priority Source Cross-skill?
1 Using deprecated NotFoundRoute HIGH docs/guide/not-found-errors —
2 Expecting useLoaderData to work in notFoundComponent MEDIUM docs/guide/not-found-errors —
3 Leaf route cannot handle not-found errors MEDIUM docs/guide/not-found-errors —

route-masking (1 failure mode)

# Mistake Priority Source Cross-skill?
1 Expecting masked URLs to survive sharing MEDIUM docs/guide/route-masking —

type-safety (3 failure modes)

# Mistake Priority Source Cross-skill?
1 Adding type annotations or casts to inferred values CRITICAL maintainer interview —
2 Using un-narrowed LinkProps type HIGH docs/guide/type-safety —
3 Not narrowing Link/useNavigate with from HIGH docs/guide/type-safety —

ssr (3 failure modes)

# Mistake Priority Source Cross-skill?
1 Using browser APIs in loaders without environment check HIGH docs/guide/ssr data-loading
2 Using hash fragments for server-rendered content MEDIUM docs/guide/navigation —
3 Generating Next.js or Remix SSR patterns CRITICAL maintainer interview route-setup, data-loading

migrate-from-react-router (2 failure modes)

# Mistake Priority Source Cross-skill?
1 Leaving React Router imports alongside TanStack Router HIGH docs/how-to/migrate-from-react-router —
2 Using React Router useSearchParams pattern HIGH docs/installation/migrate-from-react-router —

Tensions

Tension Skills Agent implication
Type safety strictness vs rapid prototyping type-safety ↔ route-setup Agents skip Register declaration or use type casts to silence errors
Client-first loaders vs SSR expectations data-loading ↔ ssr Agents put server-only code in client loaders or avoid browser APIs unnecessarily
Built-in SWR cache vs external cache coordination data-loading ↔ external-data-loading Agents use both caches simultaneously causing stale data or double-fetching
Code splitting granularity vs loader performance code-splitting ↔ data-loading Agents split everything including loaders, adding latency

Cross-References

From To Reason
route-setup type-safety Register declaration and property order are prerequisites for type inference
navigation search-params Link search prop directly interacts with search param validation
data-loading search-params loaderDeps consumes validated search params as cache keys
data-loading external-data-loading Understanding built-in caching is prerequisite for external cache coordination
auth-and-guards data-loading beforeLoad runs before loader — auth context flows into loader via route context
code-splitting data-loading Loader splitting decisions affect data loading performance
ssr data-loading SSR changes where loaders execute — must handle both environments
ssr external-data-loading SSR dehydration/hydration requires special Query setup
not-found-and-errors data-loading notFound() in loaders interacts with error boundaries and loader data availability
migrate-from-react-router route-setup Migration requires understanding TanStack Router route setup

Subsystems & Reference Candidates

Skill Subsystems Reference candidates
route-setup — file naming conventions (>10 distinct conventions)
search-params Zod adapter, Valibot adapter, ArkType adapter search param validation patterns (>10 distinct patterns)
All others — —
  • Core skills: route-setup, navigation, search-params, path-params, data-loading, code-splitting, not-found-and-errors, route-masking, type-safety, ssr, auth-and-guards
  • Framework skills: None needed separately — React and Solid share the same core API surface. Framework-specific notes belong inline.
  • Lifecycle skills: migrate-from-react-router
  • Composition skills: external-data-loading (TanStack Query)
  • Reference files: search-params (validation patterns), route-setup (file naming conventions)

Composition Opportunities

Library Integration points Composition skill needed?
@tanstack/react-query Loader coordination, SSR dehydration/hydration, streaming Yes — external-data-loading
Zod Search param validation No — covered as subsystem in search-params
Valibot Search param validation No — covered as subsystem in search-params
ArkType Search param validation No — covered as subsystem in search-params