createSafeActionClient()

createSafeActionClient creates a new safe action client instance. This is the entry point for defining type-safe server actions.

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

const actionClient = createSafeActionClient(opts);

Parameters

createSafeActionClient accepts an optional options object:

Prop

Type

Return value

Returns a SafeActionClient instance with all chainable methods available.

Examples

Minimal client

src/lib/safe-action.ts

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

export const actionClient = createSafeActionClient();

Custom error handling

src/lib/safe-action.ts

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

export const actionClient = createSafeActionClient({
	handleServerError: (error, { metadata }) => {
		// Log to your error tracking service
		reportError(error, { metadata });

		// Return a user-friendly message
		if (error instanceof DatabaseError) {
			return "A database error occurred. Please try again.";
		}

		return "Something went wrong.";
	},
});

With metadata schema

src/lib/safe-action.ts

import { createSafeActionClient } from "next-safe-action";
import { z } from "zod";

export const actionClient = createSafeActionClient({
	defineMetadataSchema: () =>
		z.object({
			actionName: z.string(),
		}),
});

// All actions using this client must now call .metadata()
export const myAction = actionClient
	.metadata({ actionName: "myAction" })
	.action(async () => {
		// ...
	});

Flattened validation errors

src/lib/safe-action.ts

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

export const actionClient = createSafeActionClient({
	defaultValidationErrorsShape: "flattened",
});

// All actions using this client return flattened errors:
// { formErrors: string[], fieldErrors: { [field]: string[] } }

`ServerErrorFunctionUtils`

The second argument passed to handleServerError:

Prop

Type

Parameters

Return value

Examples

Minimal client

Custom error handling

With metadata schema

Flattened validation errors

`ServerErrorFunctionUtils`

See also

On this page