Auth.js (NextAuth) Simplified for Developers

Let’s talk about authentication. Specifically, Auth.js, formerly known as NextAuth.js. It’s a fantastic library for adding authentication to your Next.js applications. But like anything powerful, it can seem a bit daunting at first. My goal here is to cut through the noise and give you a practical, no-nonsense guide to getting it set up without pulling your hair out.

Why Auth.js?

First off, why bother with Auth.js? Because building authentication from scratch is a pain. You’ve got session management, CSRF protection, credential hashing, OAuth integration, and a whole lot more to worry about. Auth.js handles most of that for you, letting you focus on your app’s core features. It’s flexible, supports numerous providers (Google, GitHub, email, credentials, etc.), and integrates seamlessly with Next.js. Plus, it’s actively maintained, which is always a good sign.

The Core Concepts

Auth.js revolves around a few key pieces:

• API Routes: The authentication logic lives here. Typically at /pages/api/auth/[...nextauth].js (or the equivalent in the App Router).
• Configuration: You define your providers, database adapter (if using one), callbacks, and other settings here.
• Session Management: How user sessions are maintained (JWT or database). It handles token generation, verification, and cookie management.
• Providers: The external services you connect to for authentication (e.g., Google, GitHub).
• Callbacks: Functions that run at different stages of the authentication flow, allowing you to customize behavior, like modifying user or session objects.

Getting Started: A Basic Setup

Let’s get a simple email/password (credentials) provider up and running. We’ll assume you’re using the Pages Router for this example, but the concepts are similar for the App Router.

First, install Auth.js:

1
npm install next-auth
2
# or
3
yarn add next-auth
4
# or
5
pnpm add next-auth

Next, create your API route file. In a Pages Router project, this would be pages/api/auth/[...nextauth].js.

1
import NextAuth from 'next-auth';
2
import CredentialsProvider from 'next-auth/providers/credentials';
3

4
export default NextAuth({
5
  providers: [
6
    CredentialsProvider({
7
      name: 'Credentials',
8
      credentials: {
9
        username: {
10
          label: 'Username',
11
          type: 'text',
12
          placeholder: 'Your username',
13
        },
14
        password: {
15
          label: 'Password',
16
          type: 'password',
17
        },
18
      },
19
      async authorize(credentials, req) {
20
        // Add your user validation logic here.
21
        // For example, query your database.
22
        const users = [
23
          { id: '1', name: 'johndoe', email: 'john.doe@example.com', password: 'hashedpassword123' },
24
        ];
25

26
        const user = users.find(u => u.name === credentials.username);
27

28
        // In a real app, you'd compare hashed passwords.
29
        if (user && credentials.password === 'password') { // Replace 'password' with your actual password check logic
30
          // Any object returned will be saved in 'user' property of the JWT passed to the callbacks
31
          return { id: user.id, name: user.name, email: user.email };
32
        }
33

34
        // If you return null then an error will be reported to the client
35
        return null;
36

37
        // You can also Reject this callback with an Error or a short message to return
38
        // throw new Error('Invalid credentials');
39
      },
40
    }),
41
  ],
42
  session: {
43
    strategy: 'jwt',
44
  },
45
  pages: {
46
    signIn: '/auth/signin',
47
  },
48
});

Notice the authorize function. This is where you’ll put your logic to verify a user’s credentials. In a real application, you’d be checking against a database, ideally comparing a hashed password. For simplicity, I’ve used a hardcoded check.

Protecting Routes

Now you need a way to show protected content only to logged-in users. You can do this in your pages/components using the useSession hook.

First, set up the Session Provider in your _app.js (or layout.js for App Router):

1
import { SessionProvider } from 'next-auth/react';
2

3
function MyApp({ Component, pageProps: { session, ...pageProps } }) {
4
  return (
5
    <SessionProvider session={session}>
6
      <Component {...pageProps} />
7
    </SessionProvider>
8
  );
9
}
10

11
export default MyApp;

Then, in your protected page or component:

1
import { useSession, signIn, signOut } from 'next-auth/react';
2

3
export default function Dashboard() {
4
  const { data: session, status } = useSession();
5

6
  if (status === 'loading') {
7
    return <p>Loading...</p>;
8
  }
9

10
  if (session) {
11
    return (
12
      <>
13
        <p>Welcome, {session.user.name}!</p>
14
        <button onClick={() => signOut()}>Sign out</button>
15
      </>
16
    );
17
  }
18

19
  return (
20
    <>
21
      <p>You are not signed in.</p>
22
      <button onClick={() => signIn()}>Sign in</button>
23
    </>
24
  );
25
}

Keep It Simple, Stupid (KISS)

Auth.js is powerful. Don’t get lost in all the options immediately. Start with a single provider, get your basic sign-in and session management working, and then layer on more complexity as needed. Use the documentation, but always bring it back to your specific needs. You’ve got this.

Tags: Web Development, Next.js, Authentication, Auth.js, NextAuth