# TanStack React Start Server and Router Setup Architecture in OpenSEO

> Explore the TanStack React Start server and router setup architecture in OpenSEO. Learn how it integrates SSR, type-safe routing, and server-only functions in Cloudflare Workers.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: architecture
- Published: 2026-09-04

---

**OpenSEO builds its web application on TanStack React Start, combining server-side rendering (SSR), type-safe routing via TanStack Router, and server-only functions within a single Cloudflare Worker runtime.**

The OpenSEO repository implements a three-layer architecture that separates concerns between the Start instance configuration, the server handler entry point, and the client-side router. This setup enables full-stack type safety, streaming server rendering, and seamless server function calls from the client.

## The Three-Layer Architecture

OpenSEO organizes its TanStack React Start implementation into distinct layers:

- **Start Instance** ([`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts)): Boots the runtime, registers global middleware including CSRF protection, and exposes the configuration used across the application.
- **Server Handler** ([`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts)): Provides the Cloudflare Worker entry point, wrapping the Start instance in a streaming handler while managing OAuth, agency routing, and database connections.
- **Router** ([`src/router.tsx`](https://github.com/every-app/open-seo/blob/main/src/router.tsx)): Generates a type-safe route tree from file-based routes and creates the TanStack Router that hydrates on the client.

## The Start Instance Layer

The foundation of the architecture lives in [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts), where OpenSEO creates the Start instance using `createStart` from `@tanstack/react-start`.

```typescript
import { createCsrfMiddleware, createStart } from "@tanstack/react-start";

const csrfMiddleware = createCsrfMiddleware({
  filter: (ctx) => ctx.handlerType === "serverFn",
});

export const startInstance = createStart(() => ({
  requestMiddleware: [csrfMiddleware],
  functionMiddleware: globalServerFunctionMiddleware,
}));

```

This configuration applies **CSRF protection** to all server functions through `createCsrfMiddleware`, filtering specifically for `serverFn` handler types. The `globalServerFunctionMiddleware` injects shared context such as database connections and authentication state into every server function invocation.

The exported `startInstance` object serves as the central configuration hub that both the server handler and server functions reference throughout the application lifecycle.

## The Server Handler Layer

The Cloudflare Worker entry point resides in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts), where OpenSEO constructs the streaming SSR handler and routes incoming requests.

```typescript
import {
  createStartHandler,
  defaultStreamHandler,
} from "@tanstack/react-start/server";

const appFetch = createStartHandler(defaultStreamHandler);
const openSeoOAuthProvider = createOpenSeoOAuthProvider(appFetch);

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    // … auth-mode detection, self-host routing, GDPR, etc.
    return handleFetch(request, env, ctx);
  },
};

```

The implementation follows a specific sequence:

1. **`createStartHandler`** builds the `appFetch` streaming handler using `defaultStreamHandler` for SSR.
2. **OAuth provider** initialization attaches authentication capabilities for hosted mode deployments.
3. **`handleFetch`** inspects URLs and dispatches to specialized routes including GDPR erasure endpoints (`/gdpr-storage-erasure`), Agent Durable Objects (`/agents/*`), and self-host MCP routes before falling back to the SSR handler.

This layer handles the runtime boundary between Cloudflare's Worker environment and the React application, managing execution context, environment variables, and request routing logic.

## The Router Layer

Client-side navigation relies on [`src/router.tsx`](https://github.com/every-app/open-seo/blob/main/src/router.tsx), which instantiates TanStack Router using the generated route tree.

```typescript
import { createRouter as createTanStackRouter } from "@tanstack/react-router";
import { routeTree } from "./routeTree.gen";

export function getRouter() {
  const router = createTanStackRouter({
    routeTree,
    defaultPreload: "intent",
    defaultErrorComponent: DefaultCatchBoundary,
    defaultNotFoundComponent: () => <NotFound />,
    scrollRestoration: true,
  });
  return router;
}

```

The router configuration enables **intent-based preloading**, where data fetches trigger only when the user shows clear navigation intent. It also provides default error boundaries through `DefaultCatchBoundary` and 404 handling via the `NotFound` component, while preserving scroll position across navigations for native-like behavior.

The `routeTree` import comes from [`src/routeTree.gen.ts`](https://github.com/every-app/open-seo/blob/main/src/routeTree.gen.ts), an auto-generated file that TanStack Router updates whenever files in `src/routes/` change, ensuring type safety across the entire route hierarchy.

## Server Functions Architecture

OpenSEO implements server-only logic through `createServerFn` from `@tanstack/react-start`, housed in `src/serverFunctions/*.ts` files.

```typescript
// src/serverFunctions/keywords.ts
import { createServerFn } from "@tanstack/react-start";

export const fetchKeywords = createServerFn(async (projectId: string) => {
  // ... DB queries, external API calls, etc.
});

```

These functions execute exclusively on the server within the same Cloudflare Worker context that handles SSR. The Start instance's middleware pipeline—including CSRF protection and database context—injects automatically into each function call. Client components consume these functions via `useServerFn` hooks, maintaining type safety across the network boundary.

## How the Pieces Fit Together

The architecture flows through a specific request lifecycle:

1. **Cloudflare Worker** receives an HTTP request at [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts).
2. **`handleFetch`** determines the appropriate sub-handler (OAuth, agents, or SSR).
3. For page requests, **`appFetch`** processes the request using the **Start instance** configuration from [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts).
4. The Start instance renders the React tree on the server, embedding the **client router** configuration.
5. The browser receives HTML containing the hydrated TanStack Router ([`src/router.tsx`](https://github.com/every-app/open-seo/blob/main/src/router.tsx)), which uses the same `routeTree` for seamless client-side navigation.
6. Subsequent **server function calls** route through the Start instance's middleware stack and execute within the Worker context.

## Practical Implementation Examples

### Defining a New Server Function

Create type-safe server logic that automatically receives request context:

```typescript
// src/serverFunctions/example.ts
import { createServerFn } from "@tanstack/react-start";

export const helloWorld = createServerFn(async (name: string) => {
  return { message: `Hello, ${name}!` };
});

```

### Consuming Server Functions in Components

Access server data with automatic loading and error states:

```tsx
import { useServerFn } from "@tanstack/react-start";
import { helloWorld } from "@/serverFunctions/example";

export function Greeting() {
  const { data, error, isLoading } = useServerFn(helloWorld, "Alice");

  if (isLoading) return <div>Loading…</div>;
  if (error) return <div>Error: {error.message}</div>;

  return <div>{data?.message}</div>;
}

```

### Adding File-Based Routes

Create new routes through filesystem placement:

1. Create [`src/routes/_app/example.tsx`](https://github.com/every-app/open-seo/blob/main/src/routes/_app/example.tsx):

```tsx
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/example")({
  component: () => <h1>OpenSEO Example Page</h1>,
});

```

2. TanStack Router auto-generates the type definitions in [`src/routeTree.gen.ts`](https://github.com/every-app/open-seo/blob/main/src/routeTree.gen.ts), making the route immediately available without manual router configuration.

### Implementing Custom Middleware

Extend the Start instance with request logging or auditing:

```typescript
// src/start.ts
import { createStart } from "@tanstack/react-start";

export const startInstance = createStart(() => ({
  requestMiddleware: [
    (ctx, next) => {
      console.log("Incoming request:", ctx.request.method, ctx.request.url);
      return next();
    },
  ],
}));

```

This middleware executes for every request including server functions, enabling cross-cutting concerns like logging, metrics, or authentication verification.

## Summary

- **Start Instance** ([`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts)): Configures the TanStack React Start runtime with CSRF middleware and global server function context.
- **Server Handler** ([`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts)): Cloudflare Worker entry point managing streaming SSR, OAuth routing, and request dispatching.
- **Router** ([`src/router.tsx`](https://github.com/every-app/open-seo/blob/main/src/router.tsx)): Hydrates the TanStack Router with auto-generated type-safe routes and intent-based preloading.
- **Server Functions**: Execute within the Worker environment via `createServerFn`, callable from client components through `useServerFn`.
- **File-Based Routing**: Routes defined in `src/routes/` automatically generate TypeScript definitions in [`src/routeTree.gen.ts`](https://github.com/every-app/open-seo/blob/main/src/routeTree.gen.ts).

## Frequently Asked Questions

### How does OpenSEO handle CSRF protection in TanStack React Start?

OpenSEO implements CSRF protection through the `createCsrfMiddleware` function in [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts), filtering specifically for `serverFn` handler types. This middleware automatically validates cross-site request forgery tokens on all server function invocations while allowing regular page requests to pass through unimpeded.

### What is the difference between `createStartHandler` and `createStart` in the OpenSEO architecture?

`createStart` (used in [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts)) boots the TanStack React Start runtime and configures middleware pipelines, while `createStartHandler` (used in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts)) builds the actual HTTP request handler that Cloudflare Workers invoke. The Start instance provides configuration; the Start handler processes incoming requests using that configuration.

### How does file-based routing work with TypeScript type safety?

TanStack Router scans the `src/routes/` directory and auto-generates [`src/routeTree.gen.ts`](https://github.com/every-app/open-seo/blob/main/src/routeTree.gen.ts), which contains TypeScript definitions for every route, its parameters, and hierarchical relationships. When developers import `routeTree` into [`src/router.tsx`](https://github.com/every-app/open-seo/blob/main/src/router.tsx), the `createTanStackRouter` function uses these definitions to enforce type safety on route navigation, parameters, and search queries.

### Can server functions access the database and authentication context?

Yes. Server functions defined with `createServerFn` execute within the same Cloudflare Worker context as the SSR handler. The `globalServerFunctionMiddleware` registered in [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts) automatically injects database connections, authentication state, and other context into every server function invocation, making these resources available without manual passing.