Server Actions

Server actions allow you to use oRPC procedures directly as form handlers in frameworks that support server actions (like Next.js). They provide automatic type coercion and FormData handling out of the box.

Context Requirements

Server actions are automatically enabled for procedures that have either:

No context requirements (undefined context)
Optional context (Context | undefined)

"use server"
 
import { os } from '@orpc/server'
import { z } from 'zod'
 
// This creates a server action since context is undefined
const actionProcedure = os
  .input(z.object({ id: z.number() }))
  .handler(() => 'result')
 
// This also creates a server action since context is optional
const optionalContextProcedure = os
  .context<{ auth: boolean } | undefined>()
  .handler(() => 'result')
 
// This won't be a server action since it requires context
const regularProcedure = os
  .context<{ auth: boolean }>()
  .handler(() => 'result')

Usage Examples

Define Server Action

Create type-safe server actions with full input validation:

"use server"
 
import { os } from '@orpc/server'
import { oz } from '@orpc/zod'
import { z } from 'zod'
import { redirect } from "next/navigation"
 
export const createPost = os
  .input(
    z.object({
      nested: z.object({
        title: z.string(),
        description: z.string(),
        thumbs: z.array(oz.file().type('image/*')).nullable(),
      }),
    }),
  )
  .handler((input) => {
    redirect('/posts/new')
  })

Form Integration

Use with React forms and get automatic type coercion:

import { createPost } from 'examples/server-action'
import * as React from 'react'
 
export default function CreatePostForm() {
  return (
    <form action={createPost}>
      {/* Nested objects use square bracket notation */}
      <input type="text" name="nested[title]" required />
      <input type="text" name="nested[description]" required />
      <input
        id="files"
        type="file"
        name="nested[thumbs][]"
        multiple
        accept="image/*"
      />
    </form>
  )
}

Direct Client Calls

Call server actions directly from client components:

"use client"
 
import { createPost } from 'examples/server-action'
import * as React from 'react'
 
export default function CreateUserButton() {
  async function handleClick() {
    const files = (document.getElementById('files') as HTMLInputElement).files
 
    // Call with plain object - types are preserved
    await createPost({
      nested: {
        title: 'hello',
        description: 'world',
        thumbs: files ? [...files] : null,
      },
    })
  }
 
  return <button onClick={handleClick}>Create User</button>
}

Server Actions

Server Actions

Context Requirements

Usage Examples

Define Server Action

Form Integration

Direct Client Calls

On this page