next-safe-action
is a library that takes full advantage of the latest and greatest Next.js, React and TypeScript features to let you define typesafe actions on the server and call them from Client Components.
Note: server actions are implemented but undocumented at this time in Next.js. They are available since 13.3.0
release.
Features
- ✅ Pretty simple
- ✅ End to end type safety
- ✅ Input validation
- ✅ Direct or hook usage from client
- ✅ Authenticated actions
Requirements
Next.js >= 13.3.0 and >= TypeScript 5.0.
Installation
npm i next-safe-action zod
Code example ⬇️
Check out this example repository to see a basic implementation of this library and to experiment a bit with it.
Project configuration
First of all, you need to create the safe action client:
import { createSafeActionClient } from "next-safe-action";
const action = createSafeActionClient();
export { action };
Then, create a file for an action:
"use server";
import { z } from "zod";
import { action } from "~/lib/safe-action";
const input = z.object({
username: z.string().min(3).max(10),
password: z.string().min(8).max(100),
});
export const loginUser = action({ input }, async ({ username, password }) => {
if (username === "johndoe") {
return {
error: {
reason: "user_suspended",
},
};
}
if (username === "user" && password === "password") {
return {
success: true,
};
}
return {
error: {
reason: "incorrect_credentials",
},
};
}
);
action
returns a new function (in this case loginUser
). To make it actually work, we must pass the action to a Client Component as a prop, otherwise Server Component functions (e.g. cookies()
or headers()
) wouldn't work in the server action body (defined above).
import Login from "./login";
import { loginUser } from "./login-action";
export default function Home() {
return (
{}
<Login loginUser={loginUser} />
);
}
There are two ways to call safe actions from the client:
1. The direct way
"use client";
import type { loginUser } from "./login-action";
type Props = {
loginUser: typeof loginUser;
}
export default function Login({ loginUser }: Props) {
return (
<button
onClick={async () => {
// Typesafe action called from client.
const res = await loginUser({ username: "user", password: "password" });
// Res keys.
const { data, validationError, serverError } = res;
}}>
Log in
</button>
);
}
On the client you get back a typesafe response object, with three optional keys:
-
data
: if action runs without issues, you get what you returned in the server action body.
-
validationError
: if an invalid input object (parsed by Zod via input validator) is passed from the client when calling the action, invalid fields will populate this key, in the form of:
{
"validationError": {
"fieldName": ["issue"],
}
}
serverError
: if an unexpected error occurs in the server action body, it will be caught, and the client will only get back a serverError
response. By default, the server error will be logged via console.error
, but this is configurable.
2. The hook way
Another way to mutate data from client is by using the useAction
hook. This is useful when you need global access to the action state in the Client Component.
Here's how it works:
"use client";
import { useAction } from "next-safe-action/hook";
import { loginUser } from "./login-action";
type Props = {
loginUser: typeof loginUser;
};
export default function Login({ loginUser }: Props) {
const { execute, isExecuting, res } = useAction(loginUser);
return (
<>
<button
onClick={async () => {
// Typesafe action called from client.
await execute({ username: "user", password: "password" });
}}>
Log in
</button>
<p>Is executing: {JSON.stringify(isExecuting)}</p>
<p>Res: {JSON.stringify(res)}</p>
</>
);
}
The useAction
hook returns an object with three keys:
execute
: a caller for the safe action you provided as argument to the hook. Here you pass your typesafe input
, the same way you do when using safe action the non-hooky way.isExecuting
: a boolean
that is true while the execute
function is mutating data.res
: when execute
finished mutating data, the response object. Otherwise it is null
. It has the same three optional keys as the one above (data
, validationError
, serverError
), plus one: fetchError
. This additional optional key is populated when communication with the server fails for some reason.
Image example:
Authenticated action
The library also supports creating protected actions, that will return a serverError
back if user is not authenticated. You need to make some changes to the above code in order to use them.
First, when creating the safe action client, you must provide an async function
called getAuthData
as an option. You can return anything you want from here. If you find out that the user is not authenticated, you can safely throw an error in this function. It will be caught, and the client will receive a serverError
response.
import { createSafeActionClient } from "next-safe-action";
const action = createSafeActionClient({
getAuthData: async () => {
const session = true;
if (!session) {
throw new Error("user is not authenticated!");
}
return {
userId: "coolest_user_id",
};
},
});
export { action };
Then, you can provide a withAuth: true
option to the safe action you're creating:
"use server";
import { z } from "zod";
import { action } from "~/lib/safe-action";
...
export const editUser = action({ input, withAuth: true },
async (parsedInput, { userId }) => {
console.log(userId);
...
}
);
If you set withAuth
to true
in the safe action you're creating, but you forgot to define a getAuthData
function when creating the client (above step), an error will be thrown when calling the action from client, that results in a serverError
response for the client.
Custom server error logging
As you just saw, you can provide a getAuthData
function to createSafeActionClient
function.
You can also provide a custom logger function for server errors. By default, they'll be logged via console.error
(on the server, obviously), but this is configurable:
import { createSafeActionClient } from "next-safe-action";
const action = createSafeActionClient({
serverErrorLogFunction: (e) => {
console.error("CUSTOM ERROR LOG FUNCTION:", e);
},
});
export { action };
Alternatives
License
This project is licensed under the MIT License.