Next.js integration
Better Auth can be easily integrated with Next.js. It'll also comes with utilities to make it easier to use Better Auth with Next.js.
Before you start, make sure you have a Better Auth instance configured. If you haven't done that yet, check out the installation.
Create API Route
We need to mount the handler to an API route. Create a route file inside /api/auth/[...all]
directory. And add the following code:
You can change the path on your better-auth configuration but it's recommended to keep it as /api/auth/[...all]
For pages
route, you need to use toNodeHandler
instead of toNextJsHandler
and set bodyParser
to false
in the config
object. Here is an example:
Create a client
Create a client instance. You can name the file anything you want. Here we are creating client.ts
file inside the lib/
directory.
Once you have created the client, you can use it to sign up, sign in, and perform other actions. Some of the actions are reactive. The client uses nano-store to store the state and re-render the components when the state changes.
The client also uses better-fetch to make the requests. You can pass the fetch configuration to the client.
RSC and Server actions
The api
object exported from the auth instance contains all the actions that you can perform on the server. Every endpoint made inside Better Auth is a invocable as a function. Including plugins endpoints.
Example: Getting Session on a server action
Example: Getting Session on a RSC
Server Action Cookies
When you call a function that needs to set cookies, like signInEmail
or signUpEmail
in a server action, cookies won’t be set. This is because server actions need to use the cookies
helper from Next.js to set cookies.
To simplify this, you can use the nextCookies
plugin, which will automatically set cookies for you whenever a Set-Cookie
header is present in the response.
Now, when you call functions that set cookies, they will be automatically set.
Middleware
In Next.js middleware, it's recommended to only check for the existence of a session cookie to handle redirection. To avoid blocking requests by making API or database calls.
You can use the getSessionCookie
helper from Better Auth for this purpose:
The getSessionCookie()
function does not automatically reference the auth config specified in auth.ts
. Therefore, you need to ensure that the configuration in getSessionCookie()
matches the config defined in your auth.ts
.
For Next.js release 15.1.7
and below
If you need the full session object, you'll have to fetch it from the /get-session
API route. Since Next.js middleware doesn't support running Node.js APIs directly, you must make an HTTP request.
The example uses better-fetch, but you can use any fetch library.
For Next.js release 15.2.0
and above
From the version 15.2.0, Next.js allows you to use the Node.js
runtime in middleware. This means you can use the auth.api
object directly in middleware.
You may refer to the Next.js documentation for more information about runtime configuration, and how to enable it. Be careful when using the new runtime. It's an experimental feature and it may be subject to breaking changes.