Guide

Defining Actions

Action filenames, HTTP methods, generated references, and validated contracts.

Defining actions

Default-export a builder action from server/actions/. The generated client reference carries input/output types without importing the handler at runtime.

server/actions/greet.ts
import { z } from 'zod'
import { actionClient } from '../utils/action-client'

export default actionClient
  .schema(z.object({ name: z.string().trim().min(1) }))
  .action(({ parsedInput }) => ({ greeting: `Hello, ${parsedInput.name}!` }))
import { greet } from '#safe-action/actions'
const action = useAction(greet)

File conventions

FileMethodClient exportRoute
create-post.tsPOSTcreatePost/api/_actions/create-post
get-user.get.tsGETgetUser/api/_actions/get-user
update-user.put.tsPUTupdateUser/api/_actions/update-user
update-field.patch.tsPATCHupdateField/api/_actions/update-field
remove-item.delete.tsDELETEremoveItem/api/_actions/remove-item
auth/login.tsPOSTauthLogin/api/_actions/auth/login

An explicit .post.ts suffix is supported. If the same route name has multiple different methods, their exports include method suffixes: user.get.ts and user.post.ts become userGet and userPost. A single-method route retains its existing export name. Duplicated route/method combinations and ambiguous JavaScript names fail with diagnostics.

Use letters, numbers, underscores, and single hyphens; each path segment must start with a letter or underscore. index.ts and declaration files are excluded. Adding/removing action files in development restarts Nuxt so routes and references regenerate.

Validation and metadata

export default actionClient
  .metadata({ name: 'greet' })
  .schema(z.object({ name: z.string().trim().min(1) }))
  .outputSchema(z.object({ greeting: z.string() }))
  .action(({ parsedInput }) => ({ greeting: `Hello, ${parsedInput.name}!` }))

Input is validated before the handler, after middleware. Output parsing determines the data sent to the client. See validation for validator choice and transforms. The module returns the parsed output, so explicitly construct public fields and use an output schema rather than returning a database record wholesale.

GET and no-input actions

GET actions serialize JSON input in one input query parameter; other methods send JSON bodies. null, false, 0, and strings are valid schema inputs. GET URLs can appear in logs and browser infrastructure, so use GET only for reads and avoid sensitive input in the query.

server/actions/get-stats.get.ts
import { createSafeActionClient } from '#safe-action'

export default createSafeActionClient().action(() => ({ status: 'ready' }))

Call a no-input action with execute(undefined). For SSR queries, use the Nuxt useAsyncData recipe.

Copyright © 2026