NextAuth.js (Auth.js) setup in NextJS - Step-by-Step Execution

Concept Flow - NextAuth.js (Auth.js) setup

Import NextAuth and Providers

↓

Create authOptions object

↓

Configure providers (e.g., GitHub)

↓

Export NextAuth with authOptions

↓

NextAuth API route handles requests

↓

User signs in/out, session managed

↓

Protected pages check session

↓

Access granted or denied

This flow shows how NextAuth.js is set up by importing, configuring providers, exporting the handler, and managing user sessions.

Execution Sample

NextJS

import NextAuth from "next-auth";
import GitHubProvider from "next-auth/providers/github";

export const authOptions = {
  providers: [GitHubProvider({ clientId: process.env.GITHUB_ID, clientSecret: process.env.GITHUB_SECRET })],
};

export default NextAuth(authOptions);

This code sets up NextAuth with GitHub as an authentication provider.

Execution Table

Step	Action	Evaluation	Result
1	Import NextAuth and GitHubProvider	Modules imported	Ready to configure auth
2	Create authOptions object	Add GitHub provider with env vars	Providers configured
3	Export NextAuth handler with authOptions	NextAuth function called with config	API route ready to handle auth
4	User visits sign-in page	NextAuth shows GitHub sign-in button	User can click to sign in
5	User clicks sign-in	Redirect to GitHub OAuth	User authenticates on GitHub
6	GitHub redirects back with token	NextAuth verifies token	Session created
7	User accesses protected page	Session checked	Access granted if signed in
8	User signs out	Session cleared	User logged out
9	End of flow	No more actions	Authentication cycle complete

💡 Authentication flow ends when user signs out or session expires.

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 6	Final
authOptions	undefined	{"providers":["GitHubProvider config"]}	{"providers":["GitHubProvider config"]}	{"providers":["GitHubProvider config"]}	{"providers":["GitHubProvider config"]}
session	null	null	null	{"user":{...}, "expires":"..."}	null or session depending on sign out

Key Moments - 3 Insights

Why do we use environment variables for clientId and clientSecret?

Environment variables keep sensitive info like clientId and clientSecret safe and out of the codebase, as shown in Step 2 of the execution_table.

What happens if the user is not signed in and tries to access a protected page?

NextAuth checks the session (Step 7). If no session exists, access is denied or redirected to sign-in, ensuring security.

How does NextAuth handle the OAuth redirect from GitHub?

After user authenticates on GitHub (Step 5), GitHub redirects back with a token (Step 6), which NextAuth verifies to create a session.

Visual Quiz - 3 Questions

Look at the execution_table, what is the state of authOptions after Step 3?

A Null

B An object with GitHub provider configured

C Undefined

D A string with client secrets

💡 Hint

Check the 'After Step 3' column in variable_tracker for authOptions.

At which step does NextAuth create a user session?

A Step 4

B Step 7

C Step 6

D Step 8

💡 Hint

Look at the execution_table row describing token verification and session creation.

If the environment variables for GitHub clientId and clientSecret are missing, what happens at Step 2?

A NextAuth throws an error or fails to authenticate

B Providers configured successfully

C User is signed in automatically

D Session is created without provider

💡 Hint

Step 2 shows provider configuration depends on environment variables.

Concept Snapshot

NextAuth.js setup:
1. Import NextAuth and providers.
2. Create authOptions with providers using env vars.
3. Export NextAuth handler with authOptions.
4. NextAuth manages sign-in, session, and sign-out.
5. Protect pages by checking session.
Use environment variables for secrets.

Full Transcript

NextAuth.js setup in Next.js starts by importing NextAuth and authentication providers like GitHubProvider. Then, you create an authOptions object that configures providers using environment variables for clientId and clientSecret to keep secrets safe. Next, you export the NextAuth handler with this configuration. When a user visits the sign-in page, NextAuth shows sign-in options. Clicking sign-in redirects the user to GitHub for authentication. After successful login, GitHub redirects back with a token, which NextAuth verifies to create a session. Protected pages check this session to allow or deny access. Signing out clears the session. This flow ensures secure and easy authentication in Next.js apps.

Practice

1. What is the main purpose of NextAuth.js in a Next.js application?

easy

A. To optimize images automatically

B. To manage database connections

C. To style components with CSS

D. To handle user authentication and login flows easily

Solution

1. Step 1: Understand NextAuth.js role

   NextAuth.js is a library designed to simplify adding authentication to Next.js apps.

2. Step 2: Identify main functionality

   It manages login flows, sessions, and providers for user authentication.

3. Final Answer:

   To handle user authentication and login flows easily -> Option D

4. Quick Check:

   NextAuth.js = Authentication helper [OK]

Hint: NextAuth.js is all about login and user sessions [OK]

Common Mistakes:

• Confusing NextAuth.js with styling or database tools
• Thinking it manages images or CSS
• Assuming it handles API routing unrelated to auth

2. Which file path is the correct place to create the NextAuth.js API route in a Next.js app?

easy

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

B. /pages/auth/nextauth.js

C. /api/auth.js

D. /pages/api/nextauth.js

Solution

1. Step 1: Recall NextAuth.js API route convention

   NextAuth.js requires a catch-all API route named [...nextauth].js inside /pages/api/auth/.

2. Step 2: Match the correct path

   Only /pages/api/auth/[...nextauth].js matches the required path: /pages/api/auth/[...nextauth].js.

3. Final Answer:

   /pages/api/auth/[...nextauth].js -> Option A

4. Quick Check:

   API route = /api/auth/[...nextauth] [OK]

Hint: NextAuth.js uses catch-all API route [...nextauth].js [OK]

Common Mistakes:

• Placing the file outside /api/auth/
• Using a non-catch-all filename
• Missing the brackets in filename

3. Given this NextAuth.js configuration snippet, what will be the value of session.user.name after a successful login?

import NextAuth from "next-auth";
import GithubProvider from "next-auth/providers/github";

export default NextAuth({
  providers: [
    GithubProvider({
      clientId: process.env.GITHUB_ID,
      clientSecret: process.env.GITHUB_SECRET
    })
  ],
  callbacks: {
    async session({ session, user }) {
      session.user.name = "CustomName";
      return session;
    }
  }
});

medium

A. The GitHub username

B. "CustomName"

C. Undefined

D. The user's email

Solution

1. Step 1: Understand the session callback

   The session callback modifies the session object before it is returned to the client.

2. Step 2: Check the modification

   It sets session.user.name explicitly to "CustomName" regardless of original data.

3. Final Answer:

   "CustomName" -> Option B

4. Quick Check:

   Session callback overrides user.name = "CustomName" [OK]

Hint: Session callback can override user data before sending [OK]

Common Mistakes:

• Assuming user.name stays as GitHub username
• Thinking session.user.name is undefined by default
• Confusing email with name property

4. You wrote this NextAuth.js provider config but get an error: TypeError: GithubProvider is not a function. What is the likely cause?

import { GithubProvider } from "next-auth/providers/github";

export default NextAuth({
  providers: [
    GithubProvider({
      clientId: process.env.GITHUB_ID,
      clientSecret: process.env.GITHUB_SECRET
    })
  ]
});

medium

A. Provider config must be inside callbacks

B. Missing environment variables

C. Incorrect import syntax; should use default import without braces

D. NextAuth must be imported from 'next-auth/client'

Solution

1. Step 1: Check import style for GithubProvider

   GithubProvider is the default export, so it should be imported without braces.

2. Step 2: Identify correct import syntax

   Use import GithubProvider from "next-auth/providers/github"; instead of curly braces.

3. Final Answer:

   Incorrect import syntax; should use default import without braces -> Option C

4. Quick Check:

   Default export = no braces in import [OK]

Hint: Default exports import without braces {} [OK]

Common Mistakes:

• Using named import syntax for default export
• Assuming environment variables cause this error
• Placing provider config inside callbacks

5. You want to add Google and GitHub login providers in NextAuth.js with environment variables. Which is the correct way to configure both providers in /pages/api/auth/[...nextauth].js?

hard

A. import GoogleProvider from "next-auth/providers/google";
import GithubProvider from "next-auth/providers/github";

export default NextAuth({
providers: [
GoogleProvider({ clientId: process.env.GOOGLE_ID, clientSecret: process.env.GOOGLE_SECRET }),
GithubProvider({ clientId: process.env.GITHUB_ID, clientSecret: process.env.GITHUB_SECRET })
]
});

B. import { GoogleProvider, GithubProvider } from "next-auth/providers";

export default NextAuth({
providers: [
GoogleProvider(process.env.GOOGLE_ID, process.env.GOOGLE_SECRET),
GithubProvider(process.env.GITHUB_ID, process.env.GITHUB_SECRET)
]
});

C. import GoogleProvider from "next-auth/providers/google";
import GithubProvider from "next-auth/providers/github";

export default NextAuth({
providers: {
google: GoogleProvider,
github: GithubProvider
}
});

D. import GoogleProvider from "next-auth/providers/google";
import GithubProvider from "next-auth/providers/github";

export default NextAuth({
providers: [
GoogleProvider,
GithubProvider
]
});

Solution

1. Step 1: Import providers correctly

   Each provider is a default export from its own module and must be imported separately.

2. Step 2: Configure providers as array with clientId and clientSecret

   Providers must be called as functions with an object containing clientId and clientSecret from environment variables.

3. Step 3: Validate options

   import GoogleProvider from "next-auth/providers/google"; import GithubProvider from "next-auth/providers/github"; export default NextAuth({ providers: [ GoogleProvider({ clientId: process.env.GOOGLE_ID, clientSecret: process.env.GOOGLE_SECRET }), GithubProvider({ clientId: process.env.GITHUB_ID, clientSecret: process.env.GITHUB_SECRET }) ] }); correctly imports and configures both providers in an array with proper keys.

4. Final Answer:

   Correct import and provider function calls with env variables -> Option A

5. Quick Check:

   Providers array with clientId/clientSecret = import GoogleProvider from "next-auth/providers/google"; import GithubProvider from "next-auth/providers/github"; export default NextAuth({ providers: [ GoogleProvider({ clientId: process.env.GOOGLE_ID, clientSecret: process.env.GOOGLE_SECRET }), GithubProvider({ clientId: process.env.GITHUB_ID, clientSecret: process.env.GITHUB_SECRET }) ] }); [OK]

Hint: Providers need clientId and clientSecret in array [OK]

Common Mistakes:

• Importing providers as named imports from a single module
• Passing env vars directly without object keys
• Using object instead of array for providers