npx nuxi module add nuxt-actions

# Zod (most popular)
pnpm add zod

# Valibot (smallest bundle)
pnpm add valibot

# ArkType (fastest runtime)
pnpm add arktype

// server/api/todos.post.ts
import { z } from 'zod'

export default defineAction({
  input: z.object({
    title: z.string().min(1, 'Title is required'),
  }),
  handler: async ({ input }) => {
    const todo = await db.todo.create({ data: input })
    return todo
  },
})

// With Valibot
import * as v from 'valibot'

export default defineAction({
  input: v.object({ title: v.pipe(v.string(), v.minLength(1)) }),
  handler: async ({ input }) => ({ id: Date.now(), title: input.title }),
})

// With ArkType
import { type } from 'arktype'

export default defineAction({
  input: type({ title: 'string > 0' }),
  handler: async ({ input }) => ({ id: Date.now(), title: input.title }),
})

// server/utils/action-clients.ts
export const authClient = createActionClient()
  .use(authMiddleware)
  .use(rateLimitMiddleware)

export const adminClient = createActionClient()
  .use(authMiddleware)
  .use(adminMiddleware)

// server/api/admin/users.get.ts
import { z } from 'zod'
import { adminClient } from '~/server/utils/action-clients'

export default adminClient
  .schema(z.object({
    page: z.coerce.number().default(1),
  }))
  .metadata({ role: 'admin', action: 'list-users' })
  .action(async ({ input, ctx }) => {
    // ctx.user and ctx.isAdmin available from middleware chain
    return await db.user.findMany({
      skip: (input.page - 1) * 10,
      take: 10,
    })
  })

export default defineAction({
  input: z.object({ id: z.string() }),
  outputSchema: z.object({
    id: z.string(),
    name: z.string(),
    email: z.string().email(),
  }),
  handler: async ({ input }) => {
    return await db.user.findUnique({ where: { id: input.id } })
  },
})

<script setup lang="ts">
const { execute, executeAsync, data, error, status, reset } = useAction<
  { title: string },
  { id: number; title: string }
>('/api/todos', {
  method: 'POST',
  onExecute(input) {
    console.log('Sending:', input)
  },
  onSuccess(data) {
    toast.success(`Created: ${data.title}`)
  },
  onError(error) {
    toast.error(error.message)
  },
})

// Option 1: Full result with success/error
async function handleSubmit(title: string) {
  const result = await execute({ title })
  if (result.success) console.log(result.data)
}

// Option 2: Direct data (throws on error)
async function handleSubmitAsync(title: string) {
  try {
    const todo = await executeAsync({ title })
    console.log(todo)
  } catch (err) {
    // err is ActionError
  }
}
</script>

<template>
  <form @submit.prevent="handleSubmit('Buy milk')">
    <button :disabled="status === 'executing'">
      {{ status === 'executing' ? 'Creating...' : 'Add Todo' }}
    </button>
    <p v-if="error" class="error">{{ error.message }}</p>
  </form>
</template>

<script setup lang="ts">
const todos = ref([
  { id: 1, title: 'Buy milk', done: false },
  { id: 2, title: 'Walk dog', done: true },
])

const { execute, optimisticData } = useOptimisticAction('/api/todos/toggle', {
  method: 'PATCH',
  currentData: todos,
  updateFn: (input, current) =>
    current.map(t => t.id === input.id ? { ...t, done: !t.done } : t),
  onError(error) {
    toast.error('Failed to update - changes reverted')
  },
})
</script>

<template>
  <ul>
    <li v-for="todo in optimisticData" :key="todo.id">
      <input
        type="checkbox"
        :checked="todo.done"
        @change="execute({ id: todo.id })"
      >
      {{ todo.title }}
    </li>
  </ul>
</template>

// server/utils/auth.ts
export const authMiddleware = defineMiddleware(async ({ event, next }) => {
  const session = await getUserSession(event)
  if (!session) {
    throw createActionError({
      code: 'UNAUTHORIZED',
      message: 'Authentication required',
      statusCode: 401,
    })
  }
  return next({ ctx: { user: session.user } })
})

// Published as `nuxt-actions-ratelimit`
export const rateLimitMiddleware = createMiddleware(async ({ event, next }) => {
  await checkRateLimit(event)
  return next()
})

throw createActionError({
  code: 'NOT_FOUND',
  message: 'Todo not found',
  statusCode: 404,
})

// With field-level errors
throw createActionError({
  code: 'VALIDATION_ERROR',
  message: 'Duplicate entry',
  statusCode: 422,
  fieldErrors: {
    email: ['Email is already taken'],
  },
})

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input validation failed",
    "statusCode": 422,
    "fieldErrors": {
      "title": ["Title is required"],
      "email": ["Invalid email address"]
    }
  }
}