TanStack Start skill for Codex

Done well means: server-only code runs only inside server functions, server routes or server-only helpers; loaders stay isomorphic and reach the server through server functions; every server function validates its input and checks auth in middleware; and the code uses the API names of the installed Start version, not a blog post’s.

Know the version first

Start moved fast through beta and RC. Before writing code, read package.json (@tanstack/react-start, @tanstack/react-router) and match these renames:

Older code	Current code
@tanstack/start, Vinxi, app.config.ts	@tanstack/react-start, Vite plugin in vite.config.ts
.validator(...) on createServerFn	.inputValidator(...)
createAPIFileRoute / createServerFileRoute	server: { handlers: { GET, POST } } on createFileRoute
export function createRouter() in router.tsx	export function getRouter()
serverOnly(fn) / clientOnly(fn)	createServerOnlyFn(fn) / createClientOnlyFn(fn)

If the project is on an older line, either keep its idioms consistently or upgrade in a dedicated change. Upgrading needs network access to install packages; ask for approval when the sandbox blocks it. Read AGENTS.md for the package manager and scripts.

Project skeleton

// vite.config.ts
import { defineConfig } from "vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [tanstackStart(), viteReact()], // Start's plugin must come before React's
});

// src/routes/__root.tsx
import { createRootRouteWithContext, HeadContent, Outlet, Scripts } from "@tanstack/react-router";

export const Route = createRootRouteWithContext<{ queryClient: QueryClient }>()({
  head: () => ({ meta: [{ charSet: "utf-8" }, { title: "Acme" }] }),
  component: () => (
    <html lang="en">
      <head><HeadContent /></head>
      <body>
        <Outlet />
        <Scripts />
      </body>
    </html>
  ),
});

src/router.tsx exports getRouter(), which creates the router with routeTree and context. Routing itself (search params, loaders, links) follows the tanstack-router skill.

Server functions

// src/features/projects/server.ts
import { createServerFn } from "@tanstack/react-start";
import { notFound } from "@tanstack/react-router";
import { z } from "zod";
import { authMiddleware } from "@/server/auth-middleware";
import { db } from "@/server/db";

export const getProject = createServerFn({ method: "GET" })
  .middleware([authMiddleware])
  .inputValidator(z.object({ id: z.string().uuid() }))
  .handler(async ({ data, context }) => {
    const project = await db.project.findFirst({ where: { id: data.id, orgId: context.user.orgId } });
    if (!project) throw notFound();
    return { id: project.id, name: project.name, updatedAt: project.updatedAt.toISOString() };
  });

export const renameProject = createServerFn({ method: "POST" })
  .middleware([authMiddleware])
  .inputValidator(z.object({ id: z.string().uuid(), name: z.string().trim().min(1).max(80) }))
  .handler(async ({ data, context }) => {
    await db.project.updateMany({ where: { id: data.id, orgId: context.user.orgId }, data: { name: data.name } });
    return { ok: true as const };
  });

• Call with { data }: await getProject({ data: { id } }).
• GET for reads (cacheable, idempotent), POST for writes.
• A server function is a public HTTP endpoint. Validation and auth are not optional.
• Return plain serializable data. Map ORM rows to DTOs; never return the full record.
• Import server functions statically. Dynamic import() of a server function module defeats the compiler’s server/client split.

Loaders are isomorphic

Route loaders run on the server for the first request and in the browser on client navigations. Code inside a loader therefore ships to the client.

export const Route = createFileRoute("/projects/$projectId")({
  loader: ({ params }) => getProject({ data: { id: params.projectId } }), // RPC on client nav
  component: ProjectPage,
});

• Never query the database or read secrets directly in a loader; call a server function.
• With TanStack Query: loader: ({ context, params }) => context.queryClient.ensureQueryData(projectQuery(params.projectId)), where the query’s queryFn calls the server function.
• For code that must differ by environment, use createIsomorphicFn().server(...).client(...).

Middleware

// src/server/auth-middleware.ts
import { createMiddleware } from "@tanstack/react-start";
import { getRequest } from "@tanstack/react-start/server";

export const authMiddleware = createMiddleware({ type: "function" }).server(async ({ next }) => {
  const user = await getUserFromSession(getRequest());
  if (!user) throw new Error("Unauthorized"); // or throw redirect({ to: "/login" })
  return next({ context: { user } });
});

Type	Runs for	Use for
createMiddleware({ type: "function" })	server function calls	auth, input logging, adding context; .client() can add headers
createMiddleware() (request, default)	every server request, including SSR and server routes	security headers, request logging, rate limiting

Register app-wide middleware in src/start.ts with createStart(() => ({ requestMiddleware: [...], functionMiddleware: [...] })).

Server routes (HTTP endpoints)

// src/routes/api/webhooks/billing.ts
export const Route = createFileRoute("/api/webhooks/billing")({
  server: {
    handlers: {
      POST: async ({ request }) => {
        const raw = await request.text();
        if (!verifySignature(raw, request.headers.get("x-signature"))) {
          return new Response("invalid signature", { status: 401 });
        }
        await enqueueBillingEvent(JSON.parse(raw));
        return new Response(null, { status: 204 });
      },
    },
  },
});

Use server routes for webhooks, third-party callers, file downloads and anything not called from your own UI. Use server functions for your UI’s reads and writes.

Rendering and environment

• Selective SSR per route: ssr: true (default), "data-only" (run loader on server, render component on client) or false (client only, for browser-dependent widgets).
• Environment variables: only VITE_-prefixed values are exposed via import.meta.env in client code. Read secrets with process.env inside server functions, server routes or createServerOnlyFn helpers.
• Hosting: the Vite build targets Node by default; providers such as Netlify, Vercel and Cloudflare have dedicated plugins or presets. Follow the hosting guide for the installed version rather than copying config from another project.

Gotchas

• A helper that imports the DB client, used by both a server function and a component, drags the DB client toward the client bundle. Keep server modules under src/server/ and import them only from server functions and server routes.
• Server function return values must be serializable; Date and other rich types depend on the serializer of your version. Return ISO strings when in doubt.
• Cookie-authenticated POST server functions need CSRF protection: SameSite=Lax (or stricter) session cookies plus an origin check in request middleware.
• Throwing a plain Error in a server function surfaces as an error on the client; for expected failures, return a typed result instead.
• After renaming a route file, the generated routeTree.gen.ts updates on the next dev or build run; type errors before that are stale.

Verification

• vite build passes; grep the client output for server-only identifiers (grep -r "DATABASE_URL\|prisma" dist/client .output/public 2>/dev/null adjusted to the build output folder) and expect no matches.
• tsc --noEmit passes.
• Load each touched route directly (SSR) and through client navigation; both paths return the same data.
• Call a protected server function without a session (from tests or curl against the dev server) and confirm rejection; send invalid input and confirm a validation error.

Output

List server functions (method, input schema, middleware, returned shape), server routes with their auth or signature checks, and routes with non-default SSR modes.