Getting Started

Installation

Install nuxt-safe-action for Nuxt 3.8+ and 4 with Zod, Valibot, ArkType, Yup, or Standard Schema validation.

Installation

These docs describe the latest release. Newer features are marked with the version that added them, such as 0.8+; check your installed version with npm ls nuxt-safe-action and see the changelog for earlier releases.
npx nuxi module add nuxt-safe-action

Then install the validator you use in your actions:

pnpm add zod
# Or: pnpm add valibot
# Or: pnpm add arktype
# Or: pnpm add yup@^1.7.0

For manual installation, install the module and add it to your Nuxt configuration:

pnpm add nuxt-safe-action zod
nuxt.config.ts
export default defineNuxtConfig({ modules: ['nuxt-safe-action'] })

Zod is optional when using another validator. Standard Schema v1 validators are accepted directly. Zod 3.24+ and Zod 4 support that contract; older supported Zod 3.20+ schemas use the legacy async parsing path. Yup 1.7+ also implements Standard Schema v1 natively; no adapter is needed. Older Yup releases are not accepted directly. Existing Zod .schema() calls remain valid. See validation.

Deployment and compatibility

Actions require a running Nuxt/Nitro server. Use nuxt build and a suitable server deployment. A static-only nuxt generate deployment cannot execute server actions.

Nuxt 3.8.0 or newer and Nuxt 4 are supported; earlier Nuxt 3 releases lack the server auto-import API the module relies on. CI exercises the 3.8.0 floor and the latest Nuxt 3 and 4 releases with Zod 3 and 4; use a Node version supported by your selected Nuxt release. The repository's development and CI toolchain uses Node 24.

Configuration

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-safe-action'],
  safeAction: { actionsDir: 'actions' },
})
OptionDefaultDescription
actionsDir'actions'Action directory relative to Nuxt's serverDir
csrf (0.8+)'strict'Same-origin protection for non-GET actions; 'off' restores 0.7 body parsing. See authentication

An empty action directory is valid. Custom server directories and build directories are supported. Action filenames must generate valid, unique JavaScript export names; ambiguous names fail with a diagnostic rather than silently overwriting routes.

Copyright © 2026