Server Actions

Introduction

oRPC makes it simple to implement server actions, offering a robust and type-safe way to manage server-side logic. Server actions are supported out of the box and are powered by several key features:

Requirements

To use a procedure as a server action, the procedure must either:

Be directly callable, or
Use Calling Procedures with Context to create a callable procedure with context.

Usage

"use server"
 
import { os, ORPCError } from '@orpc/server'
import { z } from 'zod'
import { headers } from 'next/headers'
import { redirect } from "next/navigation"
import { oz } from '@orpc/zod'
 
const authMid = os.middleware(async (input, context, meta) => {
      const headersList = await headers()
      const user = headersList.get('Authorization') ? { id: 'example' } : undefined
 
      if(!user) {
          throw new ORPCError({ code: 'UNAUTHORIZED' })
      }
 
      return meta.next({
          context: {
              user,
          }
      })
})
 
export const updateUser = os
  .use(authMid)
  .input(
    z.object({
      id: z.bigint(),
      user: z.object({
        name: z.string(),
        avatar: oz.file().type('image/*').optional(),
      }),
    }),
  )
  .func((input, context, meta) => {
    // ^ context.user is automatically injected
     redirect('/some-where') // or return some thing
  })

Form Integration

Integrate server actions seamlessly with React forms for automatic type coercion:

import { updateUser } from 'examples/server-action'
import * as React from 'react'
 
export default function UpdateUserForm() {
  return (
    <form action={updateUser}>
      {/* Auto convert 1992 to bigint */}
      <input type="number" name="id" value="1992" />
      {/* Auto parse user object */}
      <input type="text" name="user[name]" value="Unnoq" />
      <input
        id="avatar"
        type="file"
        name="user[avatar]"
        accept="image/*"
      />
    </form>
  )
}

Thanks to Smart Conversion, and Bracket Notation, automatically convert 1992 into a bigint and seamlessly parse objects like user.

Direct Client Calls

Call server actions directly from client components for greater flexibility:

"use client"
 
import { updateUser } from 'examples/server-action'
import * as React from 'react'
 
export default function UpdateUserButton() {
  async function handleClick() {
    const files = (document.getElementById('avatar') as HTMLInputElement).files
 
    // Call with plain object - types are preserved
    await updateUser({
      id: 1992n,
      user: {
        name: 'Unnoq',
        avatar: files?.[0],
      },
    })
  }
 
  return <button onClick={handleClick}>Update User</button>
}

Some procedures cannot be used as server actions directly. This is typically because they require additional context, such as user information or other runtime data. In such cases, you can use createProcedureCaller to provide the required context dynamically, making the procedure callable and usable as a server action.

import { createProcedureCaller, os } from '@orpc/server'
import { z } from 'zod'
 
type Context = { user?: { id: string } }
 
const getting = os
.context<Context>()
.input(z.object({ name: z.string() }))
.func(({ name }) => `Hello, ${name}!`)
 
getting({ name: 'Unnoq' }) // ❌ cannot call this procedure directly, and cannot be used as a server actionThis expression is not callable.
  Type 'Procedure<Context, undefined, ZodObject<{ name: ZodString; }, "strip", ZodTypeAny, { name: string; }, { name: string; }>, undefined, string> & { ...; }' has no call signatures.
 
export const caller = createProcedureCaller({
    procedure: getting,
    context: async () => {
        // you can access headers, cookies, etc. here to create context
        return { user: { id: 'example' } }
    },
})
 
caller({ name: 'Unnoq' }) // ✅ can call this procedure directly, and can be used as a server action