/start-server-functions

name: start-server-functions
description: Use when creating type-safe RPC server logic with createServerFn — validators, handlers, FormData, redirects. Do NOT use for raw HTTP endpoints or middleware chains.
version: 1.0.0
user-invocable: true
references: references/creating.md, references/calling.md, references/security.md, references/templates/crud-server-functions.md, references/templates/form-with-validation.md

<objective> Covers createServerFn, TanStack Start's same-origin type-safe RPC mechanism: GET/POST methods, .validator() (Zod or a plain function), .handler(), the useServerFn hook, FormData input, Response output, strict serialization, throwing redirect()/notFound(), server context utilities, and CSRF protection. Server functions run only on the server but are callable from loaders, components, hooks, and other server functions. Targets @tanstack/react-start v1.166.2.

Critical rules: a server function is an independent HTTP endpoint reachable directly, so a route's beforeLoad redirect protects the UI only — auth must live inside the handler or its middleware for every function touching private data; never use Next.js/Remix patterns ("use server", getServerSideProps, Remix loader/action); loaders are isomorphic, so DB/secrets/filesystem access belongs in a server function, never a loader; useServerFn is mandatory when a function throws redirect() or notFound() (optional otherwise); and strict serialization is on by default (FormData allowed as POST input, Response as output).

Includes templates for a full CRUD module and for FormData submissions with Zod validation.

Do NOT use this skill for raw external/public HTTP endpoints (use start-server-routes), for composable middleware chains (use start-middleware), or for Next.js/Remix "use server" patterns. </objective>

TanStack Start Server Functions

Server functions are same-origin, type-safe RPC endpoints created with `createServerFn`. They run only on the server but are callable from loaders, components, hooks, and other server functions. 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. **A server function is an independent HTTP endpoint.** A route `beforeLoad` redirect protects the route UI, NOT the RPC — an attacker can hit the endpoint directly. Put auth **inside** the `.handler()` or in middleware for every function touching private data. 2. **Never use Next.js/Remix patterns.** No `"use server"`, `getServerSideProps`, Remix `loader`/`action`, or `react-router-dom`. Use `createServerFn` exclusively (from `@tanstack/react-start`). 3. **Loaders are isomorphic** (run on client AND server). DB queries, secrets, and file-system access MUST live in a server function, never in a loader. 4. **`useServerFn` is MANDATORY** when the function does `throw redirect()` or `throw notFound()` — the hook wires the throw into the router. Optional for plain-data functions (a direct call or `useMutation`/`useQuery` is fine). 5. **Strict serialization is on by default.** Validator input and handler return types must be serializable (`FormData` allowed as POST input, `Response` allowed as output). `strict: false` disables only the TS check, not runtime.

Overview

| When to Use | Do NOT Use | |-------------|------------| | Internal type-safe RPC from your own app | Public/cross-origin API (use start-server-routes) | | Data fetching in loaders | Raw HTTP method routing on a URL path | | Mutations from event handlers | Composable auth/logging chains (use start-middleware) |

Architecture

src/utils/
├── users.functions.ts   # createServerFn wrappers — safe to import anywhere
├── users.server.ts      # Server-only helpers (DB queries, secrets)
└── schemas.ts           # Shared Zod schemas — client-safe

The build replaces server function bodies with RPC stubs in the client bundle, so static imports of `.functions.ts` from client components are safe.

→ See [crud-server-functions.md](references/templates/crud-server-functions.md)

Reference Guide

Concepts

| Topic | Reference | Load when | |-------|-----------|-----------| | Creating functions | [creating.md](references/creating.md) | Defining createServerFn, validators, serialization | | Calling functions | [calling.md](references/calling.md) | Invoking from loaders/components, useServerFn, redirect/notFound | | Security | [security.md](references/security.md) | Enforcing auth, CSRF, caching auth'd responses |

Templates

| Template | When to Use | |----------|-------------| | [crud-server-functions.md](references/templates/crud-server-functions.md) | Building a full CRUD module | | [form-with-validation.md](references/templates/form-with-validation.md) | Handling FormData submissions with Zod |

Quick Reference

Basic function with validation

import { createServerFn } from '@tanstack/react-start'
import { z } from 'zod'

export const createUser = createServerFn({ method: 'POST' })
  .validator(z.object({ name: z.string().min(1) }))
  .handler(async ({ data }) => db.users.create(data))

await createUser({ data: { name: 'John' } })

Redirect (requires useServerFn in components)

import { useServerFn } from '@tanstack/react-start'
import { redirect } from '@tanstack/react-router'

const signup = createServerFn({ method: 'POST' })
  .handler(async () => { throw redirect({ to: '/dashboard' }) })

// In a component:
const signupFn = useServerFn(signup)

→ See [calling.md](references/calling.md) for the full redirect/notFound rules

Best Practices

DO

• Enforce auth inside every handler that reads/writes private data
• Split server-only helpers into `.server.ts`, wrappers into `.functions.ts`
• Validate every input crossing the network bo