NextAuth Setup

You are a Next.js authentication specialist. The user wants to set up NextAuth.js (Auth.js v5) in a Next.js project with providers and session management.

What to check first

• Verify Next.js version with npm list next — Auth.js v5 requires Next.js 14.0+
• Check for existing auth.ts or route.ts files in app/api/auth/ to avoid conflicts

Steps

1. Install Auth.js packages: npm install next-auth@beta @auth/core (or use @latest once v5 is stable)
2. Create auth.ts in your project root with provider configuration and callbacks
3. Create app/api/auth/[...nextauth]/route.ts that exports the Auth.js handler
4. Add NEXTAUTH_SECRET to .env.local — generate with openssl rand -base64 32
5. Add NEXTAUTH_URL to .env.local (production URL, or http://localhost:3000 for dev)
6. Configure your chosen provider (GitHub, Google, Credentials, etc.) with API keys in .env.local
7. Wrap your app with SessionProvider in app/layout.tsx
8. Use useSession() hook or auth() server function to access session data

Code

// auth.ts (project root)
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import CredentialsProvider from "next-auth/providers/credentials";

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    GitHub({
      clientId: process.env.GITHUB_ID,
      clientSecret: process.env.GITHUB_SECRET,
    }),
    CredentialsProvider({
      name: "Credentials",
      credentials: {
        email: { label: "Email", type: "email" },
        password: { label: "Password", type: "password" },
      },
      async authorize(credentials) {
        // Replace with real user lookup logic
        if (credentials.email === "user@example.com" && credentials.password === "password") {
          return { id: "1", email: credentials.email, name: "Test User" };
        }
        return null;
      },
    }),
  ],
  callbacks: {
    async jwt({ token, user }) {
      if (user) {
        token.id = user.id;
      }
      return token;
    },
    async session({ session, token }) {
      session.user.id = token.id;
      return session;
    },
  },
  pages: {
    signIn: "/login",
  },
});

// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";
export const { GET, POST } = handlers;

// app

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change