К основному содержанию
скилл CX Codex

server-functions — скилл для Claude Code: что делает и как установить

Скилл server-functions обучает агента писать типобезопасные RPC-функции через createServerFn в TanStack Start, валидировать входные данные схемами Zod и вызывать их из компонентов.

MIT 221 установок ★ 15 341 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add TanStack/router --skill server-functions -a claude-code
Открыть на GitHub

Что делает server-functions

Скилл содержит шаблоны и правила работы с серверными функциями в TanStack Start. Он учит агента объявлять вызовы через createServerFn с методами GET или POST, проверять параметры вручную или схемами Zod, а также разбирать входящие данные FormData. Для безопасного вызова процедур из событий интерфейса используется хук useServerFn.

В коде чётко разграничиваются среды исполнения. Лоадеры в TanStack Start изоморфны и могут запускаться в браузере. Поэтому прямые запросы к базе данных, файловые операции и секретные ключи переносятся внутрь createServerFn. Скилл прямо запрещает директивы "use server" и паттерны Next.js или Remix.

Для работы требуется базовый скилл start-core. Авторизацию необходимо проверять прямо внутри обработчика или через middleware: серверная функция работает как публичный HTTP-эндпоинт, поэтому проверки в beforeLoad роута недостаточно для защиты данных.

Какие задачи решает

  • вынести запросы к базе данных и секретные ключи из изоморфных лоадеров
  • валидировать аргументы серверных вызовов через Zod или функции
  • связать серверные мутации со сбросом кэша через router.invalidate
  • обрабатывать отправку FormData внутри серверного обработчика

Примеры запросов агенту

  • Создай функцию сохранения через createServerFn с методом POST и валидацией Zod, затем подключи её в компонент через useServerFn
  • Перенеси прямой SQL-запрос из лоадера маршрута внутрь серверной функции
  • Напиши функцию удаления записи с проверкой сессии внутри обработчика и инвалидацией роутера

Как установить server-functions

1Через Skills CLI (Vercel)

npx skills add TanStack/router --skill server-functions -a claude-code

2Вручную: положить файлы

~/.claude/skills/server-functions/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/server-functions/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о server-functions

Как установить server-functions в Claude Code?

Выполните команду npx skills add TanStack/router --skill server-functions -a claude-code.

Зачем нужен этот скилл?

Он объясняет агенту правильную архитектуру RPC в TanStack Start, предотвращает утечку серверного кода в клиентские бандлы и задаёт правила валидации данных.

Почему нельзя проверять права только в beforeLoad роута?

Серверные функции доступны как отдельные эндпоинты независимо от UI. Если в обработчике нет собственной проверки авторизации, данные останутся уязвимыми.

Исходный текст

SKILL.md · MIT
---
name: server-functions
description: >-
  createServerFn (GET/POST), validator (Zod or function),
  useServerFn hook, server context utilities (getRequest,
  getRequestHeader, setResponseHeader, setResponseStatus), error
  handling (throw errors, redirect, notFound), streaming, FormData
  handling, file organization (.functions.ts, .server.ts).
metadata:
  type: sub-skill
  library: tanstack-start
  library_version: '1.170.14'
requires:
  - start-core
sources:
  - TanStack/router:docs/start/framework/react/guide/server-functions.md
---

# Server Functions

Server functions are type-safe RPCs created with `createServerFn`. They run exclusively on the server but can be called from anywhere — loaders, components, hooks, event handlers, or other server functions.

> **CRITICAL**: Server functions are API endpoints. They are reachable independently of whichever route renders the calling UI. **Auth must be enforced inside the handler (or via middleware) for any server function that touches private data.** Route `beforeLoad` is UX, not the data boundary. See [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md) for the session/middleware pattern.
> **CRITICAL**: Loaders are ISOMORPHIC — they run on BOTH client and server. Database queries, file system access, and secret API keys MUST go inside `createServerFn`, NOT in loaders directly.
> **CRITICAL**: Do not use `"use server"` directives, `getServerSideProps`, or any Next.js/Remix server patterns. TanStack Start uses `createServerFn` exclusively.

## Basic Usage

```tsx
import { createServerFn } from '@tanstack/react-start'

// GET (default)
const getData = createServerFn().handler(async () => {
  return { message: 'Hello from server!' }
})

// POST
const saveData = createServerFn({ method: 'POST' }).handler(async () => {
  return { success: true }
})
```

## Calling from Loaders

```tsx
import { createFileRoute } from '@tanstack/react-router'
import { createServerFn } from '@tanstack/react-start'

const getPosts = createServerFn({ method: 'GET' }).handler(async () => {
  const posts = await db.query('SELECT * FROM posts')
  return { posts }
})

export const Route = createFileRoute('/posts')({
  loader: () => getPosts(),
  component: PostList,
})

function PostList() {
  const { posts } = Route.useLoaderData()
  return (
    <ul>
      {posts.map((p) => (
        <li key={p.id}>{p.title}</li>
      ))}
    </ul>
  )
}
```

## Calling from Components

Use the `useServerFn` hook to call server functions from event handlers:

```tsx
import { useServerFn } from '@tanstack/react-start'

const deletePost = createServerFn({ method: 'POST' })
  .validator((data: { id: string }) => data)
  .handler(async ({ data }) => {
    await db.delete('posts').where({ id: data.id })
    return { success: true }
  })

function DeleteButton({ postId }: { postId: string }) {
  const deletePostFn = useServerFn(deletePost)

  return (
    <button onClick={() => deletePostFn({ data: { id: postId } })}>
      Delete
    </button>
  )
}
```

## Cache-Coherent Mutations

Keep reads and writes behind server functions that use the same authoritative store. Await the write, then invalidate the route cache so its loader reads the persisted result:

```tsx
const listIssues = createServerFn({ method: 'GET' }).handler(() => {
  return db.issues.findMany()
})

const createIssue = createServerFn({ method: 'POST' })
  .validator((data: unknown) => {
    if (
      typeof data !== 'object' ||
      data === null ||
      !('title' in data) ||
      typeof data.title !== 'string' ||
      data.title.trim().length === 0
    ) {
      throw new Error('Title is required')
    }
    return { title: data.title.trim() }
  })
  .handler(async ({ data }) => {
    return db.issues.create({ data })
  })

export const Route = createFileRoute('/issues')({
  loader: () => listIssues(),
  component: IssuesPage,
})

function IssuesPage() {
  const router = useRouter()
  const createIssueFn = useServerFn(createIssue)

  const handleCreate = async (title: string) => {
    await createIssueFn({ data: { title } })
    await router.invalidate({ sync: true })
  }

  // render Route.useLoaderData() and call handleCreate from the form
}
```

Do not update only local component state after a persistent mutation. Verify the rendered list after create, update, delete, and a fresh page load.

## Input Validation

### Basic Validator

```tsx
const greetUser = createServerFn({ method: 'GET' })
  .validator((data: { name: string }) => data)
  .handler(async ({ data }) => {
    return `Hello, ${data.name}!`
  })

await greetUser({ data: { name: 'John' } })
```

### Zod Validator

```tsx
import { z } from 'zod'

const createUser = createServerFn({ method: 'POST' })
  .validator(
    z.object({
      name: z.string().min(1),
      age: z.number().min(0),
    }),
  )
  .handler(async ({ data }) => {
    return `Created user: ${data.name}, age ${data.age}`
  })
```

Input validation does not validate output serialization. When a response schema changes, update the database selection, service return value, server-function result, loader consumer, and UI. Add a runtime test that calls the handler or HTTP boundary and asserts the new field in the returned payload.

### FormData

```tsx
const submitForm = createServerFn({ method: 'POST' })
  .validator((data) => {
    if (!(data instanceof FormData)) {
      throw new Error('Expected FormData')
    }
    return {
      name: data.get('name')?.toString() || '',
      email: data.get('email')?.toString() || '',
    }
  })
  .handler(async ({ data }) => {
    return { success: true }
  })
```

## Error Handling

### Errors

```tsx
const riskyFunction = createServerFn().handler(async () => {
  throw new Error('Something went wrong!')
})

try {
  await riskyFunction()
} catch (error) {
  console.log(error.message) // "Something went wrong!"
}
```

### Redirects

```tsx
import { redirect } from '@tanstack/react-router'

const requireAuth = createServerFn().handler(async () => {
  const user = await getCurrentUser()
  if (!user) {
    throw redirect({ to: '/login' })
  }
  return user
})
```

### Not Found

```tsx
import { notFound } from '@tanstack/react-router'

const getPost = createServerFn()
  .validator((data: { id: string }) => data)
  .handler(async ({ data }) => {
    const post = await db.findPost(data.id)
    if (!post) {
      throw notFound()
    }
    return post
  })
```

## Server Context Utilities

Access request/response details inside server function handlers:

```tsx
import { createServerFn } from '@tanstack/react-start'
import {
  getRequest,
  getRequestHeader,
  setResponseHeaders,
  setResponseStatus,
} from '@tanstack/react-start/server'

// Public, non-personalized data — safe to cache shared across users.
const getPublicData = createServerFn({ method: 'GET' }).handler(async () => {
  setResponseHeaders({
    // 'public' is correct ONLY when the response does not depend on identity.
    // For anything tied to a session/user/tenant, use 'private' or 'no-store'.
    'Cache-Control': 'public, max-age=300',
  })
  setResponseStatus(200)
  return fetchPublicData()
})

// Authenticated data — must NOT be 'public'.
const getMyData = createServerFn({ method: 'GET' }).handler(async () => {
  const authHeader = getRequestHeader('Authorization')
  // ... auth check ...

  setResponseHeaders({
    // 'private' = only the user-agent may cache. Vary by Cookie/Authorization
    // so any intermediary that does cache keys by identity, not URL alone.
    'Cache-Control': 'private, max-age=60',
    Vary: 'Cookie, Authorization',
  })
  return fetchPersonalizedData()
})
```

Available utilities:

- `getRequest()` — full Request object
- `getRequestHeader(name)` — single request header
- `setResponseHeader(name, value)` — single response header
- `setResponseHeaders(headers)` — multiple response headers
- `setResponseStatus(code)` — HTTP status code

## File Organization

```text
src/utils/
├── users.functions.ts   # createServerFn wrappers (safe to import anywhere)
├── users.server.ts      # Server-only helpers (DB queries, internal logic)
└── schemas.ts           # Shared validation schemas (client-safe)
```

```tsx
// users.server.ts — server-only helpers
import { db } from '~/db'

export async function findUserById(id: string) {
  return db.query.users.findFirst({ where: eq(users.id, id) })
}
```

```tsx
// users.functions.ts — server functions
import { createServerFn } from '@tanstack/react-start'
import { findUserById } from './users.server'

export const getUser = createServerFn({ method: 'GET' })
  .validator((data: { id: string }) => data)
  .handler(async ({ data }) => {
    return findUserById(data.id)
  })
```

Static imports of server functions are safe — the build replaces implementations with RPC stubs in client bundles.

## Common Mistakes

### 1. CRITICAL: Relying on a route guard to protect a server function

A `beforeLoad` redirect protects the **route's UI**, not the **data endpoint**. `createServerFn` exposes a callable endpoint that an attacker can hit directly — no need to load the route at all. Auth on the endpoint is the security boundary; auth on the route is UX.

```tsx
// WRONG — the route guard doesn't reach the handler
const getMyOrders = createServerFn({ method: 'GET' }).handler(async () => {
  return db.orders.findMany() // ← anyone can call the RPC
})
export const Route = createFileRoute('/_authenticated/orders')({
  beforeLoad: ({ context }) => {
    if (!context.auth.isAuthenticated) throw redirect({ to: '/login' })
  },
  loader: () => getMyOrders(),
})

// CORRECT — auth enforced on the handler itself
const getMyOrders = createServerFn({ method: 'GET' })
  .middleware([authMiddleware])
  .handler(async ({ context }) => {
    return db.orders.findMany({ where: { userId: context.session.userId } })
  })
```

Apply `authMiddleware` (or an equivalent in-handler check) to **every** `createServerFn` that needs auth. See [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md) for the full session/middleware pattern and [start-core/middleware](../middleware/SKILL.md) for composing the factory.

### 2. CRITICAL: Putting server-only code in loaders

```tsx
// WRONG — loader is ISOMORPHIC, runs on BOTH client and server
export const Route = createFileRoute('/posts')({
  loader: async () => {
    const posts = await db.query('SELECT * FROM posts')
    return { posts }
  },
})

// CORRECT — use createServerFn for server-only logic
const getPosts = createServerFn({ method: 'GET' }).handler(async () => {
  const posts = await db.query('SELECT * FROM posts')
  return { posts }
})

export const Route = createFileRoute('/posts')({
  loader: () => getPosts(),
})
```

### 3. CRITICAL: Using Next.js / Remix / React Router DOM patterns

If the file lives at `src/pages/`, `app/layout.tsx`, `_app/`, or imports anything from `react-router-dom` or `next/`, it is wrong-framework code. TanStack Start uses `src/routes/` + `createFileRoute` + `createServerFn`.

```tsx
// WRONG — "use server" is a React directive, not used in TanStack Start
'use server'
export async function getUser() { ... }

// WRONG — getServerSideProps is Next.js Pages Router
export async function getServerSideProps() { ... }

// WRONG — Next.js App Router server component data fetching
export default async function Page() {
  const data = await fetch(...).then(r => r.json())
  return <div>{data}</div>
}

// WRONG — Remix
export async function loader({ request }) { ... }
export async function action({ request }) { ... }

// WRONG — react-router-dom (a different library)
import { Link, useNavigate } from 'react-router-dom'

// CORRECT — TanStack Start
import { createServerFn } from '@tanstack/react-start'
import { Link, useNavigate, createFileRoute } from '@tanstack/react-router'

const getUser = createServerFn({ method: 'GET' })
  .handler(async () => { ... })

export const Route = createFileRoute('/users/$id')({
  loader: ({ params }) => getUser({ data: { id: params.id } }),
  component: UserPage,
})
```

If you see `src/pages/`, `app/layout.tsx`, or `react-router-dom` in agent output, the agent is generating for the wrong framework. Build will fail or routes will conflict at runtime.

### 4. HIGH: Dynamic imports for server functions

```tsx
// WRONG — can cause bundler issues
const { getUser } = await import('~/utils/users.functions')

// CORRECT — static imports are safe, build handles environment shaking
import { getUser } from '~/utils/users.functions'
```

### 5. HIGH: Awaiting server function without calling it

`createServerFn` returns a function — it must be invoked with `()`:

```tsx
// WRONG — getItems is a function, not a Promise
const data = await getItems

// CORRECT — call the function
const data = await getItems()

// With validated input
const data = await getItems({ data: { id: '1' } })
```

### 6. CRITICAL: Caching authenticated responses with `Cache-Control: public`

`Cache-Control: public, max-age=N` tells every CDN, proxy, and shared cache between you and the user that this response can be served to anyone. If the response depends on the session (user, tenant, role), the first user's response gets cached and replayed to the next user — a cross-tenant data leak.

```tsx
// WRONG — auth'd response, public cache, leaks to next user via CDN
const getMyOrders = createServerFn({ method: 'GET' }).handler(async () => {
  const session = await requireSession() // identity-dependent
  setResponseHeaders({ 'Cache-Control': 'public, max-age=300' })
  return db.orders.findMany({ where: { userId: session.userId } })
})

// CORRECT — private + Vary so any cache that does store it keys by identity
const getMyOrders = createServerFn({ method: 'GET' }).handler(async () => {
  const session = await requireSession()
  setResponseHeaders({
    'Cache-Control': 'private, max-age=60',
    Vary: 'Cookie, Authorization',
  })
  return db.orders.findMany({ where: { userId: session.userId } })
})

// ALSO CORRECT — opt out entirely for sensitive data
setResponseHeaders({ 'Cache-Control': 'no-store' })
```

Rule of thumb: if the handler reads a session/cookie/auth header or branches on identity, the response is **not** `public`. Default to `private` (or `no-store` for sensitive data); reach for `public` only on responses that are byte-for-byte identical regardless of who asks. See also [start-core/deployment](../deployment/SKILL.md) for ISR/Cache-Control on full pages.

### 7. MEDIUM: When to wrap with `useServerFn`

`useServerFn` is **required** when the server function uses `throw redirect()` or `throw notFound()` — the hook wires the throw into the router so the redirect actually navigates. For server functions that just return data (call them directly or via `useMutation`/`useQuery`), the hook is optional.

```tsx
// Plain data — direct call is fine (also fine to pass to useMutation/useQuery)
<button onClick={() => deletePost({ data: { id } })}>Delete</button>
useMutation({ mutationFn: deletePost })

// Throws redirect/notFound — MUST wrap with useServerFn so the router handles the throw
const signupFn = useServerFn(signup) // signup throws redirect on success
<button onClick={() => signupFn({ data: form })}>Sign up</button>
```

If in doubt: wrap with `useServerFn`. It's a no-op for plain-data functions and the safe default when a function might later add a redirect.

### 8. CRITICAL: Self-fetching a relative API URL from a loader

```tsx
// WRONG — this loader also runs during SSR, where a relative URL may fail
export const Route = createFileRoute('/issues')({
  loader: () => fetch('/api/issues').then((response) => response.json()),
})

// CORRECT — call the server function; the client build gets an RPC stub
export const Route = createFileRoute('/issues')({
  loader: () => listIssues(),
})
```

Relative `fetch` is fine in a browser-only event handler. It is not a universal loader data strategy.

## Cross-References

- [start-core/execution-model](../execution-model/SKILL.md) — understanding where code runs
- [start-core/middleware](../middleware/SKILL.md) — composing server functions with middleware
- [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md) — sessions, cookies, OAuth, CSRF, rate limiting (the server-side half of auth; `getCurrentUser` and external session helpers belong here, not at module scope)
- `@tanstack/router-core#router-core/auth-and-guards` — routing-side UX guards; data auth belongs in the server function, server route, or API endpoint handler/middleware

© TanStack · MIT · TanStack/router

Похожие скиллы

Все скиллы по теме «Фронтенд и UI» →
tanstack-start-cursorrules-prompt-file PatrickJS Правило tanstack-start-cursorrules-prompt-file для Cursor описывает структуру TanStack Start и типобезопасную разработку с SSR. Активируется в проектах Start, маршрутах TanStack Router и конфигурации Vinxi. CX Codex +1 ★ 41 178звёзд репо tanstack-ai tanstack-skills Скилл обучает ассистента работать с TanStack AI: настраивать стриминг ответов, вызов функций и валидацию схем в React или Solid. CX Codex +1 1 600установок tanstack-start-shadcn-tailwind официальный github Правило tanstack-start-shadcn-tailwind для GitHub Copilot унифицирует работу с TanStack Start, задавая стандарты типизации, валидации через Zod и интеграции компонентов Shadcn. CX Codex +1 ★ 41 430звёзд репо procedure finom Скилл procedure для Claude Code описывает типизированную серверную логику в Vovk.ts. Он включается при работе с данными на сервере, обработчиками форм и API. CX Codex +1 ★ 57звёзд репо base44-platform-backend-functions base44 Скилл base44-platform-backend-functions для Claude Code помогает писать серверный код для приложений Base44. Включается, когда приложению нужны внешние API, привилегированная логика или задачи по расписанию. CX Codex +1 3 100установок hono-routing secondsky Скилл hono-routing для работы с Hono: маршруты, middleware, валидация через Zod или Valibot, RPC-клиент с выводом типов. Помогает избежать 12 типичных ошибок при построении API. CX Codex +1 256установок

Из того же набора25

Весь набор →
router-plugin Настраивает плагин сборщика для генерации маршрутов и разделения кода в TanStack Router. Помогает подключить Vite, Webpack, Rspack или esbuild. CX Codex +1 374установок data-loading Скилл data-loading помогает настраивать загрузку данных в TanStack Router: кэш, состояния ожидания, ошибки и контекст роутера. CX Codex +1 230установок search-params Скилл search-params добавляет ассистенту правила работы со строкой поиска в TanStack Router: валидацию через Zod, наследование в дочерних маршрутах и middleware. CX Codex +1 228установок type-safety Скилл type-safety учит ИИ-кодеру правильно писать типизированный код с TanStack Router: не добавлять аннотации к выведенным значениям, использовать Register, сужать типы через from и getRouteApi. CX Codex +1 223установок auth-and-guards Скилл auth-and-guards для защиты маршрутов в TanStack Router. Перенаправляет неавторизованных пользователей, встраивает проверку ролей и прав, интегрирует Auth0, Clerk, Supabase через контекст роутера. CX Codex +1 219установок navigation Скилл navigation помогает агенту настраивать навигацию в TanStack Router: ссылки, переходы, предзагрузку маршрутов и блокировку ухода со страницы. CX Codex +1 214установок execution-model Скилл execution-model помогает агенту правильно разделять серверный и клиентский код в TanStack Start и учитывать SSR, гидрацию и переменные окружения. CX Codex +1 214установок code-splitting Скилл code-splitting разделяет код маршрутов TanStack Router на критичную и ленивую части: автоматически создаёт отдельные чанки или позволяет настроить разделение вручную. CX Codex +1 212установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой