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

request-lifecycle.md

271 lines11.4 KB

Every request to a TanStack Start app travels through the same pipeline before a response is produced. This guide walks that pipeline end to end β€” from the moment a request enters your server, through middleware and server routes, to the point where it delegates to SSR and streams HTML back to the client.

Understanding this lifecycle helps you reason about where to put logic: a global middleware for cross-cutting concerns, a server route for an HTTP endpoint, or a route component for a rendered page.

The big picture

flowchart TD
    A["HTTP Request<br/>(WinterCG fetch)"] --> B["Server entry<br/>src/server.ts (optional)"]
    B --> C["Global request middleware"]
    C --> D{"Is it a<br/>server function call?<br/>(/_serverFn/...)"}
    D -- yes --> E["Server function handler<br/>β†’ Response"]
    D -- no --> F["Server route matching"]
    F --> G["Route + handler middleware"]
    G --> H{"Handler returns<br/>a Response?"}
    H -- yes --> I["Server route Response"]
    H -- "no / next()<br/>(route has a component)" --> J["SSR render"]
    J --> K["Streamed HTML Response"]

At a high level, a request flows: entry point β†’ global request middleware β†’ (server function fast-path) β†’ server route matching β†’ route middleware β†’ handler β†’ SSR. SSR is always the final step in the chain β€” a server route handler that doesn't return a response delegates to it.

1. Where it enters: the server entry point

The entry point is the universal fetch handler for your app. It is optional β€” if you don't define src/server.ts, TanStack Start generates a default for you that is equivalent to:

// auto-generated default
import {
  createStartHandler,
  defaultStreamHandler,
} from '@tanstack/react-start/server'

const fetch = createStartHandler(defaultStreamHandler)

export default createServerEntry({ fetch })

When you do define an entry, it must conform to the ServerEntry shape β€” a single fetch(request, opts?) method β€” the same format used by Cloudflare Workers and other WinterCG-compatible runtimes:

// src/server.ts
import handler, { createServerEntry } from '@tanstack/react-start/server-entry'

export default createServerEntry({
  fetch(request) {
    return handler.fetch(request)
  },
})

Whether you statically generate or serve dynamically, server.ts is the entry point for all SSR work, server routes, and server function requests.

Note

createServerEntry only adds type safety β€” it has no runtime logic of its own. The real pipeline lives inside the fetch returned by createStartHandler.

See The Server Entry Point for deployment-specific extensions (e.g. Cloudflare queues and scheduled events).

Request context

When your server needs to pass typed data into the request (authenticated user info, a database connection, per-request flags), register a request context type via module augmentation. The registered context is delivered as the second argument to the fetch handler and is available throughout the entire server-side chain β€” global middleware, request/function middleware, server routes, server functions, and the router itself.

2. Where it goes next: global request middleware

Before anything else runs, every request passes through your global request middleware. Register it on your Start instance:

// src/start.ts
import { createStart } from '@tanstack/react-start'

export const startInstance = createStart(() => ({
  requestMiddleware: [myGlobalMiddleware],
}))

Important

Global request middleware runs before every request β€” server routes, SSR, and server functions alike.

Each middleware is next-able: it must call next() to invoke the rest of the chain, which lets it short-circuit, transform the response, or contribute context.

import { createMiddleware } from '@tanstack/react-start'

const loggingMiddleware = createMiddleware().server(
  async ({ next, request }) => {
    const start = Date.now()
    const result = await next() // run the rest of the chain (eventually: SSR)
    console.log(`${request.method} ${request.url} β€” ${Date.now() - start}ms`)
    return result
  },
)

Context flows forward through next({ context }), and middleware dependencies are resolved dependency-first (a middleware's dependencies run before it), with automatic de-duplication so a shared dependency never runs twice.

For the full middleware reference β€” including server function middleware, .client()/.server() phases, and sendContext β€” see the Middleware guide.

3. The server function fast-path

If the request targets a server function (its path begins with the internal /_serverFn/ prefix that createServerFn() generates), Start handles it on a dedicated path: it runs your global request middleware, then the server function's own middleware and handler, and returns the result.

These requests never reach server route matching or SSR β€” they are an RPC channel, not a page render. Everything else continues to the next stage.

4. Server routes

For all other requests, Start matches the incoming URL against your route tree and looks for a server route β€” a server block on a file route that defines HTTP method handlers:

// routes/hello.ts
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/hello')({
  server: {
    handlers: {
      GET: async ({ request }) => {
        return new Response('Hello, World! from ' + request.url)
      },
    },
  },
})

Each handler receives the incoming request, the matched params, and the shared middleware context. Method resolution follows HTTP semantics β€” for example, a HEAD request falls back to the GET handler (with its body stripped).

A single route can define both server handlers and a component, letting the same path serve an API method and a rendered page:

export const Route = createFileRoute('/hello')({
  server: {
    handlers: {
      POST: async ({ request }) => {
        /* handle the form submission */
        return new Response('Created', { status: 201 })
      },
    },
  },
  component: HelloComponent, // GET renders this page
})

5. Server route middleware

Server routes support middleware at two levels, and both run after your global request middleware:

export const Route = createFileRoute('/hello')({
  server: {
    middleware: [authMiddleware], // runs for every handler on this route
    handlers: ({ createHandlers }) =>
      createHandlers({
        GET: async () => new Response('Hello, World!'),
        POST: {
          middleware: [validationMiddleware], // runs only for POST, after authMiddleware
          handler: async ({ request }) => {
            /* ... */
            return new Response('OK')
          },
        },
      }),
  },
})

The effective execution order for a matched request is:

  1. Global request middleware (from createStart)
  2. Route-level middleware β€” collected from every matched route in the tree, parent to child
  3. Handler-level middleware β€” for the specific HTTP method, on an exact match
  4. The method handler β€” or, if there is none, SSR

Tip

Use pathless layout routes to apply middleware to a group of routes without adding a path segment. See Server Routes for the full pattern, including breaking out of inherited middleware.

6. How server routes delegate to SSR

This is the key insight that ties the lifecycle together: SSR is the last step in the route middleware chain, not a separate branch. After all route and handler middleware, Start appends the SSR renderer as the final link. What happens next depends on your route:

  • No matching server handler (or a non-exact match) β†’ the request flows straight to SSR and renders your page.
  • A handler that returns a Response β†’ that response is sent; SSR is never reached.
  • A handler that calls next() β†’ it defers to SSR. This is only allowed when the route also defines a component.
export const Route = createFileRoute('/dashboard')({
  server: {
    handlers: {
      GET: async ({ next, request }) => {
        if (!isAuthenticated(request)) {
          return new Response('Unauthorized', { status: 401 })
        }
        return next() // authenticated β†’ render the page via SSR
      },
    },
  },
  component: Dashboard,
})

Warning

If a server route handler returns nothing and the route has no component, Start throws an error: "It looks like you forgot to return a response from your server route handler. If you want to defer to the app router, make sure to have a component set in this route." Either return a Response, or add a component so the handler can next() to SSR.

What SSR does

When a request reaches SSR, Start:

  1. Resolves the asset manifest (CSS/JS) for the matched routes and fires HTTP 103 Early Hints.
  2. Creates the router instance and runs load() β€” executing beforeLoad and route loaders.
  3. Short-circuits if a loader issues a redirect.
  4. Dehydrates the router's state into the document so the client can hydrate.
  5. Builds the response headers (Content-Type: text/html plus any per-route headers).
  6. Calls your render handler to produce the HTML stream.

The render handler is what createStartHandler wraps. By default it is defaultStreamHandler, which streams the app:

export const defaultStreamHandler = defineHandlerCallback(
  ({ request, router, responseHeaders }) =>
    renderRouterToStream({
      request,
      router,
      responseHeaders,
      children: <StartServer router={router} />,
    }),
)

You can supply your own to wrap or replace this behavior:

// src/server.ts
import {
  createStartHandler,
  defaultStreamHandler,
  defineHandlerCallback,
} from '@tanstack/react-start/server'
import { createServerEntry } from '@tanstack/react-start/server-entry'

const customHandler = defineHandlerCallback((ctx) => {
  // add custom logic here (logging, headers, alternate renderer)
  return defaultStreamHandler(ctx)
})

export default createServerEntry({ fetch: createStartHandler(customHandler) })

The renderer picks the right streaming API for your runtime (renderToReadableStream on edge/WinterCG runtimes, renderToPipeableStream on Node), waits for the full HTML when the request is from a bot, and injects the dehydrated router state into the stream so the client can hydrate seamlessly.

Summary

StageWhat runsCan it end the request?
Server entrycreateServerEntry({ fetch })β€” (delegates inward)
Global request middlewarecreateStart({ requestMiddleware })Yes (short-circuit)
Server function fast-pathserver function handlerYes
Server route middlewareroute- and handler-levelYes
Server route handlermethod handlerYes (return a Response)
SSRloaders β†’ dehydrate β†’ render handlerYes (final step)