Auth0 Next.js Integration

Add authentication to Next.js applications using @auth0/nextjs-auth0. Supports both App Router and Pages Router.

Prerequisites

• Next.js 13+ application (App Router or Pages Router)
• Auth0 account and application configured
• If you don't have Auth0 set up yet, use the auth0-quickstart skill first

When NOT to Use

• Client-side only React apps - Use auth0-react for Vite/CRA SPAs
• React Native mobile apps - Use auth0-react-native for iOS/Android
• Non-Next.js frameworks - Use framework-specific SDKs (Express, Vue, Angular, etc.)
• Stateless APIs only - Use JWT validation middleware if you don't need session management

Quick Start Workflow

1. Install SDK

npm install @auth0/nextjs-auth0

2. Configure Environment

For automated setup with Auth0 CLI, see Setup Guide for complete scripts.

For manual setup:

Create .env.local:

AUTH0_SECRET=\x3Cgenerate-a-32-character-secret>
APP_BASE_URL=http://localhost:3000
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret

Generate secret: openssl rand -hex 32

Important: Add .env.local to .gitignore

3. Create Auth0 Client and Middleware

Detect project structure first: Check whether the project uses a src/ directory (i.e. src/app/ or src/pages/ exists). This determines where to place files:

• With src/: src/lib/auth0.ts, src/middleware.ts (or src/proxy.ts for Next.js 16)
• Without src/: lib/auth0.ts, middleware.ts (or proxy.ts for Next.js 16)

Create lib/auth0.ts (or src/lib/auth0.ts if using the src/ convention):

import { Auth0Client } from '@auth0/nextjs-auth0/server';

export const auth0 = new Auth0Client({
  domain: process.env.AUTH0_DOMAIN!,
  clientId: process.env.AUTH0_CLIENT_ID!,
  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
  secret: process.env.AUTH0_SECRET!,
  appBaseUrl: process.env.APP_BASE_URL!,
});

Middleware Configuration (Next.js 15 vs 16):

Next.js 15 - Create middleware.ts (at project root, or src/middleware.ts if using src/):

import { NextRequest } from 'next/server';
import { auth0 } from '@/lib/auth0';

export async function middleware(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

Next.js 16 - You have two options:

Option 1: Use middleware.ts (same as Next.js 15, same src/ placement rules):

import { NextRequest } from 'next/server';
import { auth0 } from '@/lib/auth0';

export async function middleware(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

Option 2: Use proxy.ts (at project root, or src/proxy.ts if using src/):

import { NextRequest } from 'next/server';
import { auth0 } from '@/lib/auth0';

export async function proxy(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

This automatically creates endpoints:

• /auth/login - Login
• /auth/logout - Logout
• /auth/callback - OAuth callback
• /auth/profile - User profile

4. Add User Context (Optional)

Note: In v4, wrapping with \x3CAuth0Provider> is optional. Only needed if you want to pass an initial user during server rendering to useUser().

App Router - Optionally wrap app in app/layout.tsx:

import { Auth0Provider } from '@auth0/nextjs-auth0/client';
import { auth0 } from '@/lib/auth0';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const session = await auth0.getSession();

  return (
    \x3Chtml>
      \x3Cbody>
        \x3CAuth0Provider user={session?.user}>{children}\x3C/Auth0Provider>
      \x3C/body>
    \x3C/html>
  );
}

Pages Router - Optionally wrap app in pages/_app.tsx:

import { Auth0Provider } from '@auth0/nextjs-auth0/client';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    \x3CAuth0Provider user={pageProps.user}>
      \x3CComponent {...pageProps} />
    \x3C/Auth0Provider>
  );
}

5. Add Authentication UI

Client Component (works in both routers):

'use client'; // Only needed for App Router

import { useUser } from '@auth0/nextjs-auth0/client';

export default function Profile() {
  const { user, isLoading } = useUser();

  if (isLoading) return \x3Cdiv>Loading...\x3C/div>;

  if (user) {
    return (
      \x3Cdiv>
        \x3Cimg src={user.picture} alt={user.name} />
        \x3Ch2>Welcome, {user.name}!\x3C/h2>
        \x3Ca href="/auth/logout">Logout\x3C/a>
      \x3C/div>
    );
  }

  return \x3Ca href="/auth/login">Login\x3C/a>;
}

6. Test Authentication

Start your dev server:

npm run dev

Visit http://localhost:3000 and test the login flow.

Detailed Documentation

• Setup Guide - Automated setup scripts, environment configuration, Auth0 CLI usage
• Integration Guide - Server-side auth, protected routes, API routes, middleware
• API Reference - Complete SDK API, hooks, helpers, session management

Common Mistakes

Related Skills

• auth0-quickstart - Basic Auth0 setup
• auth0-migration - Migrate from another auth provider
• auth0-mfa - Add Multi-Factor Authentication

Quick Reference

V4 Setup:

• Detect src/ convention: check if src/app/ or src/pages/ exists — place all files inside src/ if so
• Create lib/auth0.ts (or src/lib/auth0.ts) with Auth0Client instance
• Create middleware configuration (required):
  • Next.js 15: middleware.ts (or src/middleware.ts) with middleware() function
  • Next.js 16: middleware.ts with middleware() OR proxy.ts with proxy() function (same src/ rules)
• Optional: Wrap with \x3CAuth0Provider> for SSR user

Client-Side Hooks:

• useUser() - Get user in client components
• user - User profile object
• isLoading - Loading state

Server-Side Methods:

• auth0.getSession() - Get session in Server Components/API routes/middleware
• auth0.getAccessToken() - Get access token for calling APIs

Common Use Cases:

• Login/Logout links → Use /auth/login and /auth/logout paths (see Step 5)
• Protected pages (App Router) → Integration Guide
• Protected pages (Pages Router) → Integration Guide
• API routes with auth → Integration Guide
• Middleware protection → Integration Guide

References

• Auth0 Next.js SDK Documentation
• Auth0 Next.js Quickstart
• SDK GitHub Repository