Next auth usesession

The NextAuth.js client library makes it easy to interact with sessions from React applications.

Example Session Object​

useSession()​

• Client Side: Yes
• Server Side: No

The React Hook in the NextAuth.js client is the easiest way to check if someone is signed in.

It works best when the is added to .

Example​

getSession()​

• Client Side: Yes
• Server Side: Yes

NextAuth.js provides a method which can be called client or server side to return a session.

It calls and returns a promise with a session object, or null if no session exists.

The tutorial securing pages and API routes shows how to use in server side calls.

getCsrfToken()​

Next.js

​

tip

You can create a helper function so you don't need to pass around:

auth.ts

When calling from the server-side i.e. in Route Handlers, React Server Components, API routes or in , we recommend using this function instead of to retrieve the object. This method is especially useful when you are using NextAuth.js with a database. This method can drastically reduce response time when used over on server-side, due to avoiding an extra to an API Route (this is generally not recommended in Next.js). In addition, or changed something.

requires passing the same object you would pass to when initializing NextAuth.js. To do so, you can export your NextAuth.js options in the following way:

In :

In API Routes:​

In App Router:​

You can also use in Next.js' server components:

info

In contrast to , which will return a only returns a .

danger

Currently, the underlying Next.js method only provides read accessThis means that the value is stripped away from in Server Components. Furthermore, there is a hard expiry on sessions, after which the user will be required to sign in again. (The default expiry is 30 days).

Caching​

Note that using this f

Getting Started

The example code below describes how to add authentication to a Next.js app.

New Project​

The easiest way to get started is to clone the example app and follow the instructions in README.md. You can try out a live demo at https://next-auth-example.vercel.app/

Existing Project​

Install NextAuth​

info

If you are using TypeScript, NextAuth.js comes with its types definitions within the package. To learn more about TypeScript for , check out the TypeScript documentation

Add API route​

To add NextAuth.js to a project create a file called in . This contains the dynamic route handler for NextAuth.js which will also contain all of your global NextAuth.js configurations.

If you're using Next.js 13.2 or above with the new App Router (), you can initialize the configuration using the new Route Handlers by following our guide.

pages/api/auth/[...nextauth].js

All requests to (, , , etc.) will automatically be handled by NextAuth.js.

Further Reading:

• See the options documentation for more details on how to configure providers, databases and other options.
• Read more about how to add authentication providers here.

Configure Shared session state​

T

Securing pages and API routes

You can easily protect client and server side rendered pages and API routes with NextAuth.js.

You can uncover working examples of the approaches shown below in the example project.

tip

The methods and both restore an if a session is valid and if a session is invalid or has expired.

Securing Pages​

If data on a page is fetched using calls to secure API routes - i.e. routes which use or to access the session - you can use the React Connect to secure pages.

pages/client-side-example.js

Next.js (Middleware)​

With NextAuth.js 4.2.0 and Next.js 12, you can now protect your pages via the middleware pattern more easily. If you would enjoy to protect all pages, you can create a file at the root or in the src directory (same level as your ) which looks fond this:

/middleware.js

If you only want to secure certain pages, export a object with a :

For the time being, the middleware only supports as session strategy.

More details can be found here.

tip

To contain all nested routes (sub pages like , ) you can pass to .

For other patterns check out the Next.js Middleware documentation.

You can protect server side rendered pages using the metho


TypeScript

NextAuth.js has its own type definitions to use in your TypeScript projects safely. Even if you don't use TypeScript, IDEs like VSCode will pick this up to provide you with a better developer experience. While you are typing, you will get suggestions about what certain objects/functions look like, and sometimes links to documentation, examples, and other valuable resources.

Check out the example repository showcasing how to use on a Next.js application with TypeScript:
https://github.com/nextauthjs/next-auth-example

---

Adapters​

If you're writing your own custom Adapter, you can take advantage of the types to make sure your implementation conforms to what's expected:

JSDoc to get helpful editor hints and auto-completion like so:

note

This will work in code editors with a strong TypeScript integration like VSCode or WebStorm. It might not work if you're using more lightweight editors like VIM or Atom.

Module Augmentation​

comes with certain types/interfaces that are shared across submodules. Good examples are and . Ideally, you should only need to create these types at a single place, and TS should pick them up in every location where