start-server-routes

TanStack Start Server Routes

Server routes are raw HTTP endpoints defined alongside app routes in src/routes/. They use the server property on createFileRoute (imported from @tanstack/react-router) and return standard Response objects. This skill targets @tanstack/react-start v1.166.2.

Agent Workflow (MANDATORY)

Before implementing, verify current APIs against Context7 (/websites/tanstack_start_framework_react) + Exa, then explore the target codebase. After changes, run fuse-ai-pilot:sniper.

Critical Rules (read first)

1. Server route vs server function: an endpoint callable from outside your app (webhooks, public REST, cross-origin) → server route. Internal type-safe RPC → server function. See vs-server-functions.md.
2. One handler file per route path. routes/users.ts, routes/users/index.ts, and routes/users.index.ts all resolve to /users and error if duplicated.
3. Always await body methods. request.json(), .text(), .formData() return Promises — un-awaited, you get a Promise, not the data.
4. Handlers must return Response (or Promise<Response>). Use Response.json(...) for JSON, or new Response(body, { status, headers }).
5. The same file can be both a UI route and an API route — add component alongside server.

Overview

Feature	Description
Definition	server: { handlers: { GET, POST, ... } } on createFileRoute
Handler context	{ request, params, context, pathname, next }
Middleware	server.middleware (all handlers) or createHandlers (per handler)
Params	Dynamic ($id) and splat ($) from the file name

Architecture

src/routes/
├── api/
│   ├── hello.ts              # /api/hello
│   ├── users/$id.ts          # /api/users/$id (dynamic param)
│   └── file/$.ts             # /api/file/$ (splat param)
└── webhooks/stripe.ts        # /webhooks/stripe (external POST)

→ See rest-endpoint.md

Reference Guide

Concepts

Topic	Reference	Load when
Defining routes	defining.md	Handlers, params, body, responses, middleware
Routes vs functions	vs-server-functions.md	Deciding between the two mechanisms

Templates

Template	When to Use
rest-endpoint.md	Full REST resource with params + middleware

Quick Reference

Basic GET

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

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

JSON with dynamic param and status

// src/routes/api/users/$id.ts
export const Route = createFileRoute('/api/users/$id')({
  server: {
    handlers: {
      GET: async ({ params }) => {
        const user = await findUser(params.id)
        if (!user) return new Response('Not found', { status: 404 })
        return Response.json(user)
      },
    },
  },
})

→ See defining.md for middleware and body parsing

Best Practices

DO

• Use server routes for webhooks, public REST, and cross-origin endpoints
• Return Response.json() for JSON (sets Content-Type automatically)
• await every request body method
• Add authMiddleware on routes handling private data

DON'T

• Duplicate a route path across multiple files
• Reach for a server route when you want internal type-safe RPC
• Forget to return a Response