OpenWikitanstack/router

Deployment and Operations

Purpose and Scope

TanStack Start is the full-stack layer for Router-first applications, so production work is broader than copying a static bundle to a host. A Start deployment must preserve the Router contract for routes, search state, loaders, links, and generated route trees while adding server rendering, streaming, server functions, and host-specific output. The repository deployment guide also covers plain TanStack Router single page applications, which matters because many operational rules are shared: unknown application URLs must still reach the app, generated route files must be present at build time, and debugging tools should be intentionally included or excluded for the target environment.

Sources: docs/router/how-to/deploy-to-production.md, docs/router/api/file-based-routing.md, docs/router/api/router.md

This page focuses on the production responsibilities an application owner must coordinate: hosting rewrites, build output, server runtime routing, generated route artifacts, operational debugging, and user-facing navigation behavior. It does not replace host documentation, but it explains how the repository docs expect Router and Start applications to behave when deployed. The key distinction is that a static Router app usually rewrites all browser routes to the client entry document, while a Start app needs an SSR or server-function path that can handle requests before falling back to static assets and client navigation.

Sources: docs/router/how-to/deploy-to-production.md

Relevant Source Files

  • docs/router/how-to/deploy-to-production.md — Primary deployment guide for SPA rewrites and platform examples, including Netlify, Cloudflare Pages, Vercel, and GitHub Pages, plus Start SSR sketches.
  • docs/router/devtools.md — Documents devtools installation, production import behavior, root-route placement, manual router binding, and floating mode operational behavior.
  • docs/router/api/file-based-routing.md — Defines file-based routing configuration that must be stable in production builds, including routesDirectory, generatedRouteTree, route ignore settings, autoCodeSplitting, disableLogging, and formatting controls.
  • docs/router/api/router.md — Provides the API index for operationally important Router functions, components, hooks, and types used by deployed apps.
  • docs/router/api/router/ActiveLinkOptionsType.md — Describes active and inactive link props, which are relevant to production navigation state, styling, and regression checks.
  • docs/router/api/router/AsyncRouteComponentType.md — Defines the preloadable async route component contract used by code-split routes.

Hosting Model and Rewrites

For a static Router application, the most important production rule is that server routing must not fight client routing. The deployment guide states that single page applications need special server configuration so every client-side route can be served by the application shell. Netlify and Cloudflare Pages examples use a redirects file that maps all paths to the main document with a successful status. Vercel uses a rewrite rule with the same intent, while GitHub Pages uses a duplicate fallback document because it cannot run arbitrary rewrite logic in the same way.

Sources: docs/router/how-to/deploy-to-production.md

Start changes the hosting model because server rendering and server functions must execute on a runtime, not only in the browser. The deployment guide shows Start-specific configuration sketches for Netlify, Cloudflare Pages, and Vercel. The Netlify example publishes static assets from a public output directory and points functions at a server output directory, then routes API traffic to the server function. The Cloudflare Pages example introduces middleware for SSR requests. The Vercel example routes all requests to a server destination and declares a Node runtime for the server entry.

Sources: docs/router/how-to/deploy-to-production.md

Treat those examples as deployment shapes rather than universal copy-paste files. In production, decide first whether the app is a static Router SPA, a Start app with full-document SSR, or a hybrid where static assets and server routes coexist. Then make the host resolve assets directly, send application URLs to the right server or fallback document, and keep API or server-function paths from being swallowed by a static fallback. If a route works locally but reloads fail in production, the rewrite layer is the first thing to inspect.

Sources: docs/router/how-to/deploy-to-production.md

Build Output, Route Generation, and Code Splitting

File-based routing is a build-time and runtime contract. The file-based routing API identifies a route directory and a generated route tree file, both relative to the current working directory. The default route directory is the source routes folder, and the generated route tree default is the route tree file in source. Production builds must generate and bundle that route tree consistently, because the router API surface assumes the application has a concrete route tree for route creation, navigation, matching, loaders, redirects, and not-found behavior.

Sources: docs/router/api/file-based-routing.md, docs/router/api/router.md

Operationally, route generation settings are part of deployment configuration. Prefixes, ignore prefixes, ignore patterns, index tokens, route tokens, generated-file headers or footers, temporary directories, and logging controls influence which files become routes and what code lands in the build. The file-based routing API warns against choosing prefixes or ignore patterns that collide with documented naming conventions, because that can create unexpected behavior. In a production pipeline, those options should be reviewed before moving route files, colocating tests, or introducing generated directories near the routes folder.

Sources: docs/router/api/file-based-routing.md

Code splitting is another deployment concern because a successful page load may depend on a route component that is fetched after the shell or document has already started rendering. The async route component type describes a route component that can expose a preload method returning a promise. That contract aligns with production preloading and streaming goals: important route code can be prepared before navigation completes, while less critical code remains split. When a deployment introduces CDN caching, asset fingerprinting, or edge rewrites, verify that split chunks remain reachable from every application URL.

Sources: docs/router/api/router/AsyncRouteComponentType.md, docs/router/api/file-based-routing.md

Platform Configuration Examples

The repository deployment guide gives concrete platform patterns that can be used as starting points. A Netlify SPA can use a redirects file with a catch-all rule to the main document, or a configuration file with a redirects block plus a build command and publish directory. A Start deployment on Netlify uses different output assumptions: public output is published, server output becomes functions, API traffic is routed to the function server, and general application traffic still has a fallback. That separation is the operational difference between static hosting and server-capable hosting.

Sources: docs/router/how-to/deploy-to-production.md

Cloudflare Pages follows the same split between static and server-aware deployments. For a static app, a redirects file or routes configuration can control which paths are handled by Pages and which are excluded. For Start SSR, the guide shows middleware as the place where SSR requests are handled. Vercel similarly distinguishes a plain rewrite to the application document from a Start SSR configuration that sends requests to a server endpoint. GitHub Pages is the most static-oriented example and requires the build output to include a fallback document for client-side routes.

Sources: docs/router/how-to/deploy-to-production.md

A practical deployment checklist starts with the build command, output directory, and runtime target. Confirm that the package manager and CI environment run the route generator before bundling. Confirm that the host publishes the directory your bundler actually writes. Confirm that public assets are served without being intercepted by SSR middleware. For Start apps, also confirm that server functions can access their runtime secrets and that API-like paths are routed to the server layer before the SPA fallback. The provided examples name the deployment files, but the important invariant is request ownership.

Sources: docs/router/how-to/deploy-to-production.md, docs/router/api/file-based-routing.md

Environment, Observability, and Debugging

Environment variables belong on the server side whenever they contain database credentials, authentication secrets, API tokens, or deployment-specific configuration. Start’s product model places database, auth, and environment work behind explicit server boundaries, while Router keeps the URL, matching, loader, and navigation contract typed across the app. In production, that means client bundles should not be used as the source of truth for secret configuration. Review loader and server-function behavior alongside host environment settings, and prefer explicit validation so a misconfigured deployment fails predictably instead of leaking partial behavior to users.

Sources: docs/router/api/router.md

Observability starts with knowing which layer handled a request. A production incident may be caused by the host rewrite, the SSR function, a route loader, a redirect, a not-found response, or a client navigation state mismatch. The Router API index shows the public surface involved in these paths, including redirect and not-found helpers, route matching components, loader hooks, location hooks, router state hooks, and route context hooks. Use that API map to choose the right instrumentation point: server logs for incoming requests, loader logs for data dependencies, and client state inspection for navigation mismatches.

Sources: docs/router/api/router.md

The devtools are intentionally separate packages and are useful during staging, support sessions, and production diagnostics when enabled deliberately. The docs explain that the normal devtools import is not shown in production. If an application really needs devtools where the environment is production, the production-specific import exposes the same options. This distinction is an operational safety mechanism: teams can keep diagnostic UI out of normal production bundles while still having an explicit escape hatch for restricted environments, internal builds, or temporary investigations.

Sources: docs/router/devtools.md

Production navigation quality is not only about successful HTTP responses. Active link styling, pending states, preloaded code, and route matching all affect whether users trust the app after deployment. The active link options type extends link options with active and inactive props for anchor elements. That makes navigation state a testable part of the UI contract: when a route is active, the link can receive specific attributes or styling; when it is inactive, it can receive different props. Include those states in visual tests for menus, breadcrumbs, and layout navigation.

Sources: docs/router/api/router/ActiveLinkOptionsType.md, docs/router/api/router.md

SEO and social previews are most relevant for Start deployments that render full documents on the server. The operational goal is that crawlers and users receive meaningful HTML, head tags, and route data from the first response rather than depending entirely on client-side navigation. The supplied repository snippets do not expose a dedicated head-management deployment file, so treat SEO validation as an application-level release step: test canonical URLs, redirects, not-found pages, route-specific metadata, and streaming behavior on the real host. Rewrites should preserve the visible URL that the route tree expects.

Sources: docs/router/how-to/deploy-to-production.md, docs/router/api/router.md

CDN asset handling should preserve the relationship between generated route code, split chunks, and public files. If a CDN caches static files aggressively, make sure the deployment produces fingerprinted assets and invalidates or versions any route-tree-related output when route files change. If the application is deployed under a subpath, the GitHub Pages example shows that bundler base configuration may need to reflect the repository or path prefix. The same principle applies outside GitHub Pages: asset URLs, router base paths, and server rewrites must agree before a release is considered healthy.

Sources: docs/router/how-to/deploy-to-production.md, docs/router/api/file-based-routing.md

Operational Next Steps

Before shipping, run a production build locally or in CI, inspect the generated route tree, and confirm that route chunks, public assets, and server output are present in the expected directories. Then test direct reloads for nested routes, dynamic routes, not-found routes, and API or server-function paths. Deploy to a preview environment and verify both browser navigation and hard refresh behavior. If debugging is needed, add Router devtools in a controlled way, inspect route matching and router state, and remove or gate diagnostic UI before public release.

Sources: docs/router/devtools.md, docs/router/how-to/deploy-to-production.md, docs/router/api/file-based-routing.md

Read the file-based routing, router plugin, Start routing, server functions, and rendering pages next if you need to change how routes are generated or how server work is executed. Read the debugging and devtools pages when a deployed app behaves differently from local development. For platform work, keep the deployment guide open while translating its Netlify, Cloudflare Pages, Vercel, and GitHub Pages examples into the exact build command, output directory, function runtime, and rewrite rules used by your hosting provider.

Sources: docs/router/devtools.md, docs/router/how-to/deploy-to-production.md

Ask a question...