Type-Safe Next.js Server Actions

Common errors

• Error: Cannot find module 'next-safe-action' or its corresponding type declarations.

  cause Incorrect import path or CommonJS project attempting to import an ESM package.
  fix Verify that `next-safe-action` is installed correctly (`npm i next-safe-action`) and ensure you are using ES module imports (`import ... from 'next-safe-action';`). If using CommonJS in Node.js, you might need to configure your project for ESM or use a bundler that handles ESM correctly.

• Error: `useAction` is not a function or `useAction` is not defined.

  cause Incorrect import path for the `useAction` hook.
  fix The `useAction` hook must be imported from the `/hook` subpath: `import { useAction } from 'next-safe-action/hook';`.

• TypeError: Cannot read properties of undefined (reading 'validationErrors')

  cause Accessing properties like `validationErrors` directly on `result` without checking if `result` or `result.validationErrors` is defined, or if the action even produced validation errors.
  fix Always conditionally access properties of `result` and its nested objects, e.g., `result?.validationErrors?.fieldName` or `if (result.validationErrors) { /* handle errors */ }`. With v8.5.0+, leverage the discriminated union by checking `result.validationErrors` first.

Warnings

• breaking next-safe-action v8 introduced breaking changes, including how action clients are created and used. Refer to the migration guide for a smooth transition.
  Fix: Consult the official v7 to v8 migration guide at `https://next-safe-action.dev/docs/migrations/v7-to-v8` to update action client initialization and action definitions.
• gotcha Version 8.5.0 narrowed `SafeActionResult` into a discriminated union, meaning `data`, `serverError`, and `validationErrors` are now mutually exclusive in the type system.
  Fix: Ensure your client-side logic correctly handles the narrowed types. When `result.data` is present, `serverError` and `validationErrors` will be `undefined` (and vice-versa). This improves type safety but might require adjustments to conditional checks.
• gotcha Using `require()` for imports will lead to errors as `next-safe-action` is an ESM-first package. Node.js environments configured for CommonJS will not resolve imports correctly.
  Fix: Always use ES module `import` syntax (e.g., `import { createSafeActionClient } from 'next-safe-action';`). Ensure your Next.js project and `tsconfig.json` are configured for ESM.
• gotcha When using `useAction`, ensure the component where it's called is a React Client Component. Server Actions are defined on the server, but the `useAction` hook must be run in a client environment.
  Fix: Add the `'use client';` directive at the top of any file defining a component that calls `useAction`.

Install

• npm install next-safe-action npm
• yarn add next-safe-action yarn
• pnpm add next-safe-action pnpm

Imports

• createSafeActionClient
  wrong:

  const { createSafeActionClient } = require('next-safe-action');

  correct:

  import { createSafeActionClient } from 'next-safe-action';

  next-safe-action is an ESM-first library. Use `import` statements. `createSafeActionClient` is used to initialize the action client with middleware and context.
• useAction
  wrong:

  import { useAction } from 'next-safe-action';

  correct:

  import { useAction } from 'next-safe-action/hook';

  `useAction` is a React hook and must be imported from the `/hook` subpath. It is designed for client components.
• safeAction

  const action = client.action(schema, async (input) => { /* ... */ });

  This is not a direct import but the result of calling `client.action()`. It represents the actual server action function.

Quickstart

This quickstart demonstrates how to define a type-safe server action with input validation using Zod and then execute it from a client component using the `useAction` hook, handling loading states and displaying errors.

import { createSafeActionClient } from 'next-safe-action';
import { z } from 'zod';
import { useAction } from 'next-safe-action/hook';

// server/actions.ts
export const actionClient = createSafeActionClient();

export const addTodo = actionClient
  .schema(z.object({ text: z.string().min(1) }))
  .action(async ({ text }) => {
    // Simulate database operation
    await new Promise(resolve => setTimeout(resolve, 500));
    console.log(`Adding todo: ${text}`);
    return { success: true, newTodo: { id: Date.now(), text } };
  });

// app/page.tsx (or any client component)
'use client';

import { useState } from 'react';
import { addTodo } from '@/server/actions'; // Adjust path as needed

export default function TodoForm() {
  const [todoText, setTodoText] = useState('');
  const { execute, result, status } = useAction(addTodo, {
    onSuccess: (data) => {
      console.log('Todo added successfully:', data?.newTodo);
      setTodoText('');
    },
    onError: (error) => {
      console.error('Failed to add todo:', error);
    }
  });

  const isLoading = status === 'executing';

  return (
    <form onSubmit={(e) => {
      e.preventDefault();
      execute({ text: todoText });
    }}>
      <input
        type="text"
        value={todoText}
        onChange={(e) => setTodoText(e.target.value)}
        placeholder="New todo item"
        disabled={isLoading}
      />
      <button type="submit" disabled={isLoading}>
        {isLoading ? 'Adding...' : 'Add Todo'}
      </button>
      {result.validationErrors?.text && (
        <p style={{ color: 'red' }}>{result.validationErrors.text[0]}</p>
      )}
      {result.serverError && (
        <p style={{ color: 'red' }}>{result.serverError}</p>
      )}
    </form>
  );
}