TanStack Knowledge Graph — TanStack Atlas

Focus by product

Lesson 01TanStack is not one frameworkBefore installing packages, build a mental map of how Start, Router, and Query divide responsibility.

selection / composition

Tool responsibility boundaries

Classify the problem as full-stack runtime, routing and URL state, or asynchronous server state.

Engineering doc / decisionRouter loader or Query?Choose Loader, Query, or both from navigation criticality and data lifecycle needs.

Lesson 02Create your first Start appUse the official CLI to create a minimal app and locate the route tree, root document, and development server.

server / RPC

Start server boundary

Place SSR, Server Functions, and external Server Routes at the correct execution boundary.

Engineering doc / recipeCreate a server-only functionUse createServerFn to define a same-origin, type-safe server RPC.

Lesson 03Build a route tree from filesCreate issue list and detail pages, then connect file names, path params, and inferred types.

path / params

File routes and params

Connect file structure, path parameters, and Link through one type system.

Engineering doc / recipeCreate a file route with a path parameterCreate /posts/$postId in a React app and read the typed postId from the route instance.

Lesson 04Put filters in the URLBuild shareable, refresh-safe, typed issue filters with validated search params.

filters / pagination

Validated URL state

Put shareable, refresh-safe, navigable filter state into validated search params.

Engineering doc / recipeValidate pagination and filter search paramsTurn untrusted URL search params into stable, typed route input.

Lesson 05Let the loader warm the Query cacheRouter decides when navigation happens while Query owns the cache. Connect them with one shared queryOptions object.

loader / query

Navigation and async cache

Router coordinates navigation while Query owns caching and refetch lifecycles.

Engineering doc / decisionRouter loader or Query?Choose Loader, Query, or both from navigation criticality and data lifecycle needs.Engineering doc / recipePrefetch Query from a route loaderCreate a request-scoped QueryClient for SSR and reuse one queryOptions contract in the loader and useSuspenseQuery.

Lesson 06Write back from a Server FunctionValidate input at the network boundary, model write state with a mutation, then immutably update Query cache from the server response.

mutation / invalidation

Writes and cache consistency

Validate the write boundary, then update or invalidate cache from the server response.

Engineering doc / recipeUpdate cache from a mutation responseUse setQueryData when the write response contains the complete entity; invalidate when the correct cache cannot be derived.

Lesson 07Contain errors in the right routeUse a global default as the safety net and route errorComponent to isolate local data or render failures.

errors / retry

Failure containment and recovery

Stop failures at the nearest route boundary and provide a stable recovery path.

Engineering doc / errorContain route loader and render errorsSet a Router-wide default and override errorComponent on routes that need independent recovery.

Lesson 08Put external endpoints in a Server RouteSeparate application RPC from public HTTP endpoints and use a native Response to express status, body, and cache policy.

server route / HTTP

External HTTP boundary

Use a Server Route to expose explicit status, caching, security, and input contracts to external callers.

Engineering doc / recipeCreate an externally callable Server RouteBuild a native HTTP endpoint for third-party callers with explicit status, caching, and safe responses.

Lesson 09Pass dependencies through Router ContextDeclare typed dependencies at the root, then use beforeLoad to add inferred context for a route subtree.

context / beforeLoad

Typed route dependencies

Inject stable dependencies at the root and add inferred context to subtrees with beforeLoad.

Engineering doc / contractEstablish typed Router ContextDeclare dependencies at the root and use beforeLoad to add inferred derived context to a subtree.

Lesson 10Define when data is freshSeparate staleTime from gcTime and co-locate keys, fetchers, and time policy in shared queryOptions.

staleTime / gcTime

Cache freshness policy

Define independently when data becomes stale and how long inactive queries remain cached.

Engineering doc / contractDefine a Query freshness contractSet staleTime from data volatility and decide inactive-cache gcTime independently.

Lesson 11Compose request boundaries with MiddlewareSeparate request middleware from Server Function middleware and compose logging, context, and security checks with next().

middleware / next

Server request pipeline

Choose the correct middleware scope for requests and Server Functions, then advance the chain explicitly.

Engineering doc / contractEstablish a Start Middleware chainDefine request and function scopes, compose context through next(), and preserve authentication and CSRF boundaries.

Lesson 13Propagate Query cancellation to the networkConsume the AbortSignal supplied to queryFn so obsolete fetches stop and cancellation state remains predictable.

AbortSignal / fetch

Async request cancellation

Propagate Query AbortSignal to the network layer to stop obsolete I/O and preserve cache semantics.

Engineering doc / contractConsume Query AbortSignalPass the queryFn signal into the request layer so cancellation stops I/O with explicit cache-revert semantics.

Lesson 14Confirm identity before child routes loadProtect a route group with typed Router Context and a pathless layout beforeLoad while preserving the correct post-login destination.

beforeLoad / redirect

Auth gates and server authorization

Stop private child loading in a parent beforeLoad while preserving resource authorization at server data boundaries.

Engineering doc / recipeProtect a route subtree with beforeLoadRead typed auth context in a pathless layout, stop signed-out users before child loading, and preserve a constrained return URL.

Lesson 15Keep infinite lists bounded and recoverableDefine pagination with initialPageParam, cursors, and maxPages while preserving the pages and pageParams structure.

pageParam / maxPages

Bounded infinite pagination

Let server cursors drive page params while preserving pages, pageParams, and memory bounds.

Engineering doc / recipeBuild a bounded cursor Infinite QueryUse one queryKey for the full list, let server cursors drive pageParam, and bound cache and refetch cost with maxPages.

Lesson 16Isolate and stream Query state across SSRUse the Router SSR Query integration for dehydration, hydration, and streaming while creating an isolated cache per server request.

SSR / hydration

Query SSR and streaming hydration

Isolate QueryClient per server request and choose blocking, hydration, or streaming for critical data.

Engineering doc / contractConfigure Query SSR and streaming hydrationCreate a QueryClient per SSR request, use the Router integration for dehydration and hydration, and classify blocking versus streaming queries.

Lesson 17Make optimistic updates safe to roll backChoose UI-only pending output or a cache-level update, then handle failure and concurrency with cancellation, snapshots, rollback, and revalidation.

onMutate / rollback

Optimistic consistency and rollback

Use cancellation, snapshots, immutable writes, and revalidation so immediate feedback converges on server truth.

Engineering doc / recipeImplement a rollback-safe optimistic updateCancel conflicting refetches, snapshot cache, write an immutable draft, roll back on failure, and revalidate on settlement.

Lesson 18Model issue data as a headless tableConnect data to semantic table markup with typed column definitions, a core row model, and flexRender while retaining full styling control.

ColumnDef / row model

Headless tables and server state

Describe the view with typed columns and row models while keeping sorting, pagination, and remote data boundaries explicit.

Engineering doc / contractCoordinate sorting and pagination for a server-backed tableLet Table own view state and Query own remote data, using manualSorting, manualPagination, and rowCount to avoid processing only the current page.

Lesson 19Keep fields, validation, and submission on one typeBuild a controlled form with useForm, Field, and Subscribe, making validation timing, error display, and async submission explicit.

field / validator

Form validation and submission boundaries

Coordinate field types, synchronous and asynchronous validation, and submission state while preserving final server validation.

Engineering doc / contractBuild a safe boundary for async field validationReject invalid input synchronously, run async validation through built-in debouncing, and separate early feedback from final server validation.

One set of engineering facts. Two reading paths.