Execution contract
- Use when
- Use for webhooks, external clients, or integrations requiring a standard HTTP endpoint.
- Avoid when
- Prefer a Server Function for app-internal calls that need end-to-end types.
- Preconditions
- Define method, path, input, status codes, response schema, authentication, and idempotency requirements.
- Verification
- Use an independent HTTP client to test success, unauthorized, invalid-input, and not-found responses.
- Failure mode
- HTML or 200 error payloads indicate missing explicit Response status and Content-Type handling.
- Security
- External endpoints must handle identity, authorization, input size, and replay risk without relying on browser same-origin behavior.
Selection contract
Use a Server Function for in-app, same-origin RPC with end-to-end types. Use a Server Route for webhooks, mobile clients, third-party integrations, or an independent HTTP contract.
Minimal implementation
Return a Response from file-route server.handlers. Every failure branch chooses an explicit status; page-level notFound() control flow is not a Server Route 404 response.
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/api/health.json')({
server: {
handlers: {
GET: async () => Response.json(
{ ok: true },
{ headers: { 'Cache-Control': 'no-store' } },
),
},
},
})Security and validation
Treat params, search, headers, and body as unknown. Validate and enforce authentication, authorization, and rate limits before writes. Return stable error objects without internal exceptions. Identity-dependent responses use no-store or private, never public shared caching.