Safe Action Better Auth

next-safe-action/skills/skills/safe-action-better-auth

by next-safe-actiona2605bd2e84321245cba8f5718c144a6e4a5fa47No licenseListed Oct 9, 2026Updated Oct 9, 2026

Use when adding authentication or authorization to safe actions with Better Auth -- covers betterAuth() middleware setup, typed session context (BetterAuthContext), custom authorize callbacks (AuthorizeFn), unauthorized() handling, nextCookies() configuration, and Next.js authInterrupts setup

Instructions onlySoftware Development

AI-generated overview

Adds Better Auth session authentication and authorization middleware to next-safe-action server actions.

What it does: This skill documents how to wire the @next-safe-action/adapter-better-auth adapter into a next-safe-action client so server actions require an authenticated session. It covers installing the package, creating a Better Auth instance with the nextCookies() plugin, enabling the Next.js authInterrupts flag, and attaching betterAuth(auth) middleware to an action client. It also explains the typed context (ctx.auth.user and ctx.auth.session), the authorize callback, unauthorized() handling, and common anti-patterns. A companion reference file describes custom authorize patterns such as role checks, redirects, and organization access.
When to use it: Use it when adding authentication or authorization to safe actions in a Next.js project that uses Better Auth. It fits setups where actions need a typed session context, custom authorize logic, or cookie-setting auth flows such as sign-in and sign-up.
Requirements: Requires a Next.js project with next-safe-action and Better Auth, plus the @next-safe-action/adapter-better-auth and better-auth npm packages. The Next.js config must enable the experimental authInterrupts flag, and the Better Auth instance should include the nextCookies() plugin. No scripts are shipped; the skill is instructions only.

next-safe-action Better Auth Adapter

Install

Import

Quick Start

1. Set up Better Auth

Create your Better Auth server instance. Add the nextCookies() plugin if your actions need to set cookies (e.g. signInEmail, signUpEmail):

// src/lib/auth.tsimport { betterAuth } from "better-auth";import { nextCookies } from "better-auth/next-js";
export const auth = betterAuth({  // ...your config (database, plugins, etc.)  plugins: [    // ...other plugins    nextCookies(), // must be the last plugin in the array  ],});

// src/lib/auth.tsimport { betterAuth } from "better-auth";import { nextCookies } from "better-auth/next-js";
export const auth = betterAuth({  // ...your config (database, plugins, etc.)  plugins: [    // ...other plugins    nextCookies(), // must be the last plugin in the array  ],});

2. Enable auth interrupts in Next.js

The default behavior uses unauthorized() from next/navigation, which requires this flag:

// next.config.tsimport type { NextConfig } from "next";
const nextConfig: NextConfig = {  experimental: {    authInterrupts: true,  },};
export default nextConfig;

// next.config.tsimport type { NextConfig } from "next";
const nextConfig: NextConfig = {  experimental: {    authInterrupts: true,  },};
export default nextConfig;

3. Create an authenticated action client

// src/lib/safe-action.tsimport { createSafeActionClient } from "next-safe-action";import { betterAuth } from "@next-safe-action/adapter-better-auth";import { auth } from "./auth";
// Public action client (no auth required)export const actionClient = createSafeActionClient();
// Authenticated action clientexport const authClient = actionClient.use(betterAuth(auth));

// src/lib/safe-action.tsimport { createSafeActionClient } from "next-safe-action";import { betterAuth } from "@next-safe-action/adapter-better-auth";import { auth } from "./auth";
// Public action client (no auth required)export const actionClient = createSafeActionClient();
// Authenticated action clientexport const authClient = actionClient.use(betterAuth(auth));

4. Use it in your actions

// src/app/actions.ts"use server";
import { z } from "zod";import { authClient } from "@/lib/safe-action";
export const updateProfile = authClient  .inputSchema(z.object({ name: z.string().min(1) }))  .action(async ({ parsedInput, ctx }) => {    // ctx.auth.user and ctx.auth.session are fully typed,    // including fields from Better Auth plugins    const userId = ctx.auth.user.id;
    await db.user.update({      where: { id: userId },      data: { name: parsedInput.name },    });
    return { success: true };  });

// src/app/actions.ts"use server";
import { z } from "zod";import { authClient } from "@/lib/safe-action";
export const updateProfile = authClient  .inputSchema(z.object({ name: z.string().min(1) }))  .action(async ({ parsedInput, ctx }) => {    // ctx.auth.user and ctx.auth.session are fully typed,    // including fields from Better Auth plugins    const userId = ctx.auth.user.id;
    await db.user.update({      where: { id: userId },      data: { name: parsedInput.name },    });
    return { success: true };  });

How It Works

betterAuth() creates a pre-validation middleware for the safe action client's .use() chain:

Fetches the session by calling auth.api.getSession({ headers: await headers() }) using the request headers from next/headers
Blocks unauthenticated requests by calling unauthorized() from next/navigation when no session exists
Injects typed context by passing { auth: { user, session } } to next(), merging it into the action context

The context is namespaced under auth to avoid collisions with other middleware context properties.

Type Inference

The middleware infers the exact user and session types from your Better Auth instance, including any fields added by plugins. For example, if you use the organization plugin, ctx.auth.session will include activeOrganizationId. No manual type annotations are needed.

Entry Points

Exported Types

Type	Description
`BetterAuthContext<O>`	The context shape added by the middleware: `{ auth: { user, session } }`. Types are inferred from the Better Auth instance via `Auth<O>["$Infer"]["Session"]`.
`AuthorizeFn<O, NC, Ctx>`	The `authorize` callback signature. Receives `{ authData, ctx, next }`.
`BetterAuthOpts<O, NC, Ctx>`	The options object type for `betterAuth()`. Contains the optional `authorize` callback.

vs. Manual Auth Middleware

If you are using Better Auth, prefer betterAuth(auth) over writing manual auth middleware. The adapter handles session fetching, cookie integration, typing, and unauthorized rejection automatically.

// Manual — don't do this if you have @next-safe-action/adapter-better-auth installedconst authClient = actionClient.use(async ({ next }) => {  const session = await auth.api.getSession({ headers: await headers() });  if (!session) {    throw new Error("Unauthorized");  }  return next({ ctx: { userId: session.user.id } });});
// With adapter — do this insteadconst authClient = actionClient.use(betterAuth(auth));// ctx.auth.user and ctx.auth.session are fully typed automatically

// Manual — don't do this if you have @next-safe-action/adapter-better-auth installedconst authClient = actionClient.use(async ({ next }) => {  const session = await auth.api.getSession({ headers: await headers() });  if (!session) {    throw new Error("Unauthorized");  }  return next({ ctx: { userId: session.user.id } });});
// With adapter — do this insteadconst authClient = actionClient.use(betterAuth(auth));// ctx.auth.user and ctx.auth.session are fully typed automatically

Supporting Docs

Custom authorize patterns (role checks, redirects, org access)

Anti-Patterns

// BAD: Missing nextCookies() plugin — cookies won't be set in Server Actions// Session will silently be null when actions try to set cookiesimport { betterAuth } from "better-auth";
export const auth = betterAuth({  plugins: [/* no nextCookies() */],});
// GOOD: Add nextCookies() as the last pluginimport { betterAuth } from "better-auth";import { nextCookies } from "better-auth/next-js";
export const auth = betterAuth({  plugins: [    // ...other plugins    nextCookies(), // must be last  ],});

// BAD: Missing nextCookies() plugin — cookies won't be set in Server Actions// Session will silently be null when actions try to set cookiesimport { betterAuth } from "better-auth";
export const auth = betterAuth({  plugins: [/* no nextCookies() */],});
// GOOD: Add nextCookies() as the last pluginimport { betterAuth } from "better-auth";import { nextCookies } from "better-auth/next-js";
export const auth = betterAuth({  plugins: [    // ...other plugins    nextCookies(), // must be last  ],});

// BAD: Missing authInterrupts flag — unauthorized() will throw a runtime error// next.config.tsconst nextConfig: NextConfig = {};
// GOOD: Enable authInterruptsconst nextConfig: NextConfig = {  experimental: {    authInterrupts: true,  },};

// BAD: Missing authInterrupts flag — unauthorized() will throw a runtime error// next.config.tsconst nextConfig: NextConfig = {};
// GOOD: Enable authInterruptsconst nextConfig: NextConfig = {  experimental: {    authInterrupts: true,  },};

// BAD: Re-fetching session inside authorize — it's already pre-fetched as authDataactionClient.use(  betterAuth(auth, {    authorize: async ({ next }) => {      const session = await auth.api.getSession({ headers: await headers() }); // Redundant!      if (!session || session.user.role !== "admin") {        unauthorized();      }      return next({ ctx: { auth: session } });    },  }));
// GOOD: Use the pre-fetched authData directlyactionClient.use(  betterAuth(auth, {    authorize: ({ authData, next }) => {      if (!authData || authData.user.role !== "admin") {        unauthorized();      }      return next({ ctx: { auth: authData } });    },  }));

// BAD: Re-fetching session inside authorize — it's already pre-fetched as authDataactionClient.use(  betterAuth(auth, {    authorize: async ({ next }) => {      const session = await auth.api.getSession({ headers: await headers() }); // Redundant!      if (!session || session.user.role !== "admin") {        unauthorized();      }      return next({ ctx: { auth: session } });    },  }));
// GOOD: Use the pre-fetched authData directlyactionClient.use(  betterAuth(auth, {    authorize: ({ authData, next }) => {      if (!authData || authData.user.role !== "admin") {        unauthorized();      }      return next({ ctx: { auth: authData } });    },  }));

// BAD: Writing manual Better Auth middleware when the adapter is installedimport { auth } from "./auth";
const authClient = actionClient.use(async ({ next }) => {  const session = await auth.api.getSession({ headers: await headers() });  if (!session) throw new Error("Unauthorized");  return next({ ctx: { user: session.user } });});
// GOOD: Use the adapter — handles typing, cookies, and unauthorized() automaticallyimport { betterAuth } from "@next-safe-action/adapter-better-auth";import { auth } from "./auth";
const authClient = actionClient.use(betterAuth(auth));

// BAD: Writing manual Better Auth middleware when the adapter is installedimport { auth } from "./auth";
const authClient = actionClient.use(async ({ next }) => {  const session = await auth.api.getSession({ headers: await headers() });  if (!session) throw new Error("Unauthorized");  return next({ ctx: { user: session.user } });});
// GOOD: Use the adapter — handles typing, cookies, and unauthorized() automaticallyimport { betterAuth } from "@next-safe-action/adapter-better-auth";import { auth } from "./auth";
const authClient = actionClient.use(betterAuth(auth));

Source and attribution

Source:next-safe-action/skillsinskills/safe-action-better-authat commita2605bd

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Safe Action Better Auth

next-safe-action Better Auth Adapter

Install

Import

Quick Start

1. Set up Better Auth

2. Enable auth interrupts in Next.js

3. Create an authenticated action client

4. Use it in your actions

How It Works

Type Inference

Entry Points

Exported Types

vs. Manual Auth Middleware

Supporting Docs

Anti-Patterns

Source and attribution

More from next-safe-action/skills

Safe Action Validation Errors

Safe Action Middleware

Safe Action Hooks

Safe Action Testing

Safe Action Client

Safe Action Forms

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices