Open History to see the last commit
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 },
18}
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
73}
74β
75declare module '@tanstack/react-router' {
76 interface Register {
77 server: {
78 requestContext: MyRequestContext
79 }
80 }
81}
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).