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

server-entry-point.md

104 lines3.6 KB

1---
2id: server-entry-point
3title: Server Entry Point
4---
5​
6> [!NOTE]
7> The server entry point is **optional** out of the box. If not provided, TanStack Start will automatically handle the server entry point for you using the below as a default.
8​
9The Server Entry Point supports the universal fetch handler format, commonly used by [Cloudflare Workers](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/) and other WinterCG-compatible runtimes.
10​
11To ensure interoperability, the default export must conform to our `ServerEntry` interface:
12​
13```ts
14export default {
15 fetch(req: Request, opts?: RequestOptions): Response | Promise<Response> {
16 // ...
17 },
19```
20​
21TanStack Start exposes a wrapper to make creation type-safe. This is done in the `src/server.ts` file.
22​
23```tsx
24// src/server.ts
25import handler, { createServerEntry } from '@tanstack/react-start/server-entry'
26​
27export default createServerEntry({
28 fetch(request) {
29 return handler.fetch(request)
30 },
31})
32```
33​
34Whether we are statically generating our app or serving it dynamically, the `server.ts` file is the entry point for doing all SSR-related work as well as for handling server routes and server function requests.
35​
36## Custom Server Handlers
37​
38You can create custom server handlers to modify how your application is rendered:
39​
40```tsx
41// src/server.ts
42import {
43 createStartHandler,
44 defaultStreamHandler,
45 defineHandlerCallback,
46} from '@tanstack/react-start/server'
47import { createServerEntry } from '@tanstack/react-start/server-entry'
48​
49const customHandler = defineHandlerCallback((ctx) => {
50 // add custom logic here
51 return defaultStreamHandler(ctx)
52})
53​
54const fetch = createStartHandler(customHandler)
55​
56export default createServerEntry({
57 fetch,
58})
59```
60​
61## Request context
62​
63When your server needs to pass additional, typed data into request handlers (for example, authenticated user info, a database connection, or per-request flags), register a request context type via TypeScript module augmentation. The registered context is delivered as the second argument to the server `fetch` handler and is available throughout the server-side middleware chain β€” including global middleware, request/function middleware, server routes, server functions, and the router itself.
64​
65To add types for your request context, augment the `Register` interface from `@tanstack/react-router` with a `server.requestContext` property. The runtime `context` you pass to `handler.fetch` will then match that type. Example:
66​
67```tsx
68import handler, { createServerEntry } from '@tanstack/react-start/server-entry'
69​
70type MyRequestContext = {
71 hello: string
72 foo: number
74​
75declare module '@tanstack/react-router' {
76 interface Register {
77 server: {
78 requestContext: MyRequestContext
79 }
80 }
82​
83export default createServerEntry({
84 async fetch(request) {
85 return handler.fetch(request, { context: { hello: 'world', foo: 123 } })
86 },
87})
88```
89​
90## Server Configuration
91​
92The server entry point is where you can configure server-specific behavior:
93​
94- Request/response middleware
95- Custom error handling
96- Authentication logic
97- Database connections
98- Logging and monitoring
99​
100This flexibility allows you to customize how your TanStack Start application handles server-side rendering while maintaining the framework's conventions.
101​
102## Cloudflare Workers
103​
104When deploying to Cloudflare Workers, you can extend `server.ts` to handle additional Workers features like queues, scheduled events, and Durable Objects. For a comprehensive guide, see the [Cloudflare Workers documentation for TanStack Start](https://developers.cloudflare.com/workers/framework-guides/web-apps/tanstack-start/#custom-entrypoints).