Server Functions

Server Functions

Server functions are a core feature of TanStack Start that allow you to write server-side code that can be called directly from your client components. They provide type-safe, serializable communication between client and server.

What are Server Functions?

Server functions enable you to:

• Execute code exclusively on the server
• Access server-only resources (databases, file systems, APIs)
• Maintain type safety across client-server boundaries
• Avoid exposing sensitive logic or credentials to the client

Creating a Server Function

Use createServerFn() to define a server function:

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

export const getUser = createServerFn({ method: 'GET' })
  .inputValidator((userId: string) => userId)
  .handler(async ({ data }) => {
    // This code runs ONLY on the server
    const user = await db.users.findById(data)
    return user
  })

HTTP Methods

Server functions support two HTTP methods:

GET Requests

Use GET for read operations and data fetching:

export const getPosts = createServerFn({ method: 'GET' }).handler(async () => {
  const posts = await db.posts.findAll()
  return posts
})

POST Requests

Use POST for mutations, form submissions, or when sending complex data:

export const createPost = createServerFn({ method: 'POST' })
  .inputValidator((data: { title: string; body: string }) => data)
  .handler(async ({ data }) => {
    const post = await db.posts.create(data)
    return post
  })

Input Validation

Validate and transform input data using validators:

Function Validators

export const fetchPost = createServerFn({ method: 'POST' })
  .inputValidator((postId: string) => {
    if (!postId) throw new Error('Post ID is required')
    return postId
  })
  .handler(async ({ data }) => {
    return await db.posts.findById(data)
  })

Zod Validators

import { z } from 'zod'

const postSchema = z.object({
  title: z.string().min(1),
  body: z.string(),
})

export const createPost = createServerFn({ method: 'POST' })
  .inputValidator(postSchema)
  .handler(async ({ data }) => {
    // data is fully typed from the schema
    return await db.posts.create(data)
  })

Calling Server Functions

From Client Components

import { getUser } from '~/utils/users'

function UserProfile() {
  const [user, setUser] = useState(null)

  const handleFetch = async () => {
    const userData = await getUser({ data: 'user-123' })
    setUser(userData)
  }

  return <button onClick={handleFetch}>Load User</button>
}

In Route Loaders

import { createFileRoute } from '@tanstack/react-router'
import { fetchPost } from '~/utils/posts'

export const Route = createFileRoute('/posts/$postId')({
  loader: ({ params }) => fetchPost({ data: params.postId }),
})

With Custom Options

// With custom headers
const data = await getUser({
  data: 'user-123',
  headers: {
    'X-Custom-Header': 'value',
  },
})

// With AbortSignal
const controller = new AbortController()
const data = await getUser({
  data: 'user-123',
  signal: controller.signal,
})

// With custom fetch
const data = await getUser({
  data: 'user-123',
  fetch: customFetch,
})

Server Function Context

Access server-only context in your handlers:

export const getServerData = createServerFn({ method: 'GET' }).handler(
  async ({ context, serverFnMeta, method }) => {
    // context contains middleware data and request context
    // serverFnMeta contains function metadata (id, name, filename)
    // method is the HTTP method used

    console.log('Function called:', serverFnMeta.name)
    console.log('Method:', method)

    return { success: true }
  },
)

Working with FormData

Server functions can handle FormData directly:

export const uploadFile = createServerFn({ method: 'POST' })
  .inputValidator((data: FormData) => data)
  .handler(async ({ data }) => {
    const file = data.get('file') as File
    const name = data.get('name') as string

    // Process the file
    const buffer = await file.arrayBuffer()
    await fs.writeFile(`/uploads/${name}`, Buffer.from(buffer))

    return { success: true }
  })

From the client:

function UploadForm() {
  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault()
    const formData = new FormData(e.currentTarget)
    await uploadFile({ data: formData })
  }

  return (
    <form onSubmit={handleSubmit}>
      <input type="file" name="file" />
      <input type="text" name="name" />
      <button type="submit">Upload</button>
    </form>
  )
}

Error Handling

Throwing Errors

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

export const fetchPost = createServerFn({ method: 'GET' })
  .inputValidator((postId: string) => postId)
  .handler(async ({ data }) => {
    const post = await db.posts.findById(data)

    if (!post) {
      throw notFound()
    }

    return post
  })

Catching Errors

function PostLoader() {
  try {
    const post = await fetchPost({ data: 'invalid-id' })
  } catch (error) {
    if (error.status === 404) {
      console.log('Post not found')
    } else {
      console.error('Error fetching post:', error)
    }
  }
}

Advanced Patterns

Composing Server Functions

const getAuthUser = createServerFn({ method: 'GET' }).handler(async () => {
  // Get authenticated user
  return { id: '123', name: 'John' }
})

const getUserPosts = createServerFn({ method: 'GET' }).handler(async () => {
  const user = await getAuthUser()
  return await db.posts.findByUserId(user.id)
})

Streaming Responses

Server functions support streaming for large datasets:

export const streamData = createServerFn({ method: 'GET' }).handler(
  async () => {
    const stream = new ReadableStream({
      async start(controller) {
        for (let i = 0; i < 100; i++) {
          controller.enqueue({ chunk: i })
          await new Promise((r) => setTimeout(r, 100))
        }
        controller.close()
      },
    })

    return stream
  },
)

Deferred Data Loading

Defer slow data fetching to improve initial page load:

export const Route = createFileRoute('/dashboard')({
  loader: async () => {
    // Fast data loaded immediately
    const user = await getUser()

    // Slow data deferred
    const metrics = getSlowMetrics()

    return {
      user,
      metrics, // Promise returned, resolved on client
    }
  },
})

Best Practices

1. Choose the Right HTTP Method

   • Use GET for read operations that can be cached
   • Use POST for mutations or operations with side effects

2. Validate All Inputs

   • Always use input validators to ensure data integrity
   • Prefer schema validation libraries like Zod for complex types

3. Keep Functions Focused

   • Each server function should do one thing well
   • Compose smaller functions for complex operations

4. Handle Errors Gracefully

   • Throw appropriate errors for different scenarios
   • Use router utilities like notFound() and redirect()

5. Avoid Over-fetching

   • Only return data that the client needs
   • Use projection/selection in database queries

6. Consider Performance

   • Use deferred loading for slow operations
   • Implement caching strategies for frequently accessed data

7. Security First

   • Never expose sensitive data or credentials
   • Validate and sanitize all inputs
   • Use authentication and authorization checks

Type Safety

Server functions maintain full type safety:

type User = {
  id: string
  name: string
  email: string
}

export const getUser = createServerFn({ method: 'GET' })
  .inputValidator((userId: string) => userId)
  .handler(async ({ data }): Promise<User> => {
    // data is typed as string
    // return type is enforced as User
    return await db.users.findById(data)
  })

// In client code:
const user = await getUser({ data: 'user-123' })
// user is typed as User

Next Steps

• Learn about Data Fetching strategies
• Add Middleware to your server functions
• Explore API Routes for REST endpoints