auth0-nextjs

Name: auth0-nextjs
Author: auth0

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=<generate-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 <Auth0Provider> 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 (
    <html>
      <body>
        <Auth0Provider user={session?.user}>{children}</Auth0Provider>
      </body>
    </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 (
    <Auth0Provider user={pageProps.user}>
      <Component {...pageProps} />
    </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 <div>Loading...</div>;

  if (user) {
    return (
      <div>
        <img src={user.picture} alt={user.name} />
        <h2>Welcome, {user.name}!</h2>
        <a href="/auth/logout">Logout</a>
      </div>
    );
  }

  return <a href="/auth/login">Login</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

Mistake Fix

Using v3 environment variables v4 uses APP_BASE_URL and AUTH0_DOMAIN (not AUTH0_BASE_URL or AUTH0_ISSUER_BASE_URL)

Forgot to add callback URL in Auth0 Dashboard Add /auth/callback to Allowed Callback URLs (e.g., http://localhost:3000/auth/callback)

Missing middleware configuration v4 requires middleware to mount auth routes - create middleware.ts (Next.js 15+16) or proxy.ts (Next.js 16 only) with auth0.middleware()

Wrong route paths v4 uses /auth/login not /api/auth/login - routes drop the /api prefix

Missing or weak AUTH0_SECRET Generate secure secret with openssl rand -hex 32 and store in .env.local

Using .env instead of .env.local Next.js requires .env.local for local secrets, and .env.local should be in .gitignore

App created as SPA type in Auth0 Must be Regular Web Application type for Next.js

Using removed v3 helpers v4 removed withPageAuthRequired and withApiAuthRequired - use getSession() instead

Using useUser in Server Component useUser is client-only, use auth0.getSession() for Server Components

AUTH0_DOMAIN includes https:// v4 AUTH0_DOMAIN should be just the domain (e.g., example.auth0.com), no scheme

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 <Auth0Provider> 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

Weekly Installs348Repositoryauth0/agent-skillsGitHub Stars12First SeenFeb 6, 2026Security AuditsGen Agent Trust HubPass SocketPass SnykPassInstalled onopencode335codex334github-copilot328gemini-cli326amp321kimi-cli321

SkillForge

auth0-nextjs

Before / After 效果对比

description SKILL.md

auth0-nextjs

Auth0 Next.js Integration

Prerequisites

When NOT to Use

Quick Start Workflow

1. Install SDK

2. Configure Environment

3. Create Auth0 Client and Middleware

4. Add User Context (Optional)

5. Add Authentication UI

6. Test Authentication

Detailed Documentation

Common Mistakes

Related Skills

Quick Reference

References

forum用户评价 (0)

统计数据

用户评分

兼容平台

时间线

SkillForge