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
  })

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>
}

With Hooks

import { useAction } from '@orpc/next/client'
import { updateUser } from 'examples/server-action'
 
// with a hook
const { execute, isPending, isError, error, output, input, status } = useAction(updateUser)
 
const onSubmit2 = () => {
  execute({ 
    id: 1992n,
    user: {
      name: 'Unnoq',
      avatar: ( document.getElementById('avatar') as any).files[0],
    },
  })
}

To handle errors gracefully or use hooks for improved reusability, you can leverage createSafeAction and useSafeAction:

import { useSafeAction } from '@orpc/next/client'
import { createSafeAction } from '@orpc/next'
import { updateUser } from 'examples/server-action'
 
// on server
const updateUserSA = createSafeAction({ 
  procedure: updateUser,
})
 
// with a hook
const { execute, isPending, isError, error, output, input, status } = useSafeAction(updateUserSA)
 
// error will include more information than normal useAction

Enhanced Form Integration

React forms integrate seamlessly with server actions using createFormAction. This setup enables automatic type coercion

// on server
import { createFormAction } from '@orpc/next'
import { updateUser } from 'examples/server-action'
const updateUserFA = createFormAction({ 
  procedure: updateUser,
  onSuccess: () => {
    // redirect('/some-where')
  }
})
 
// on client
import * as React from 'react'
 
export default function UpdateUserForm() {
  return (
    <form action={updateUserFA}>
      {/* 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.

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 or createSafeAction and createFormAction (built on top of createProcedureCaller) to provide the required context dynamically, making the procedure callable and usable as a server action.

import { createSafeAction, createFormAction } from '@orpc/next'
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({ // or createSafeAction or createFormAction
    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

This flexibility ensures you can adapt server actions to scenarios requiring runtime information, enhancing usability across diverse use cases.