auth0-nextjs
★ 37by auth0 · part of auth0/agent-skills
Add Auth0 authentication to Next.js apps with session management, protected routes, and middleware. Supports both App Router and Pages Router with automatic OAuth callback handling via /auth/login , /auth/logout , and /auth/callback endpoints Provides server-side session access through auth0.getSession() for Server Components and API routes, plus client-side useUser() hook for client components Requires middleware configuration ( middleware.ts for Next.js 15+, or proxy.ts for Next.js 16) to...
Add Auth0 authentication to Next.js apps with session management, protected routes, and middleware. Supports both App Router and Pages Router with automatic OAuth callback handling via /auth/login , /auth/logout , and /auth/callback endpoints Provides server-side session access through auth0.getSession() for Server Components and API routes, plus client-side useUser() hook for client components Requires middleware configuration ( middleware.ts for Next.js 15+, or proxy.ts for Next.js 16) to...
Inspect the full instructions your agent will receiveExpandCollapse
This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.
by auth0
Add Auth0 authentication to Next.js apps with session management, protected routes, and middleware. Supports both App Router and Pages Router with automatic OAuth callback handling via /auth/login , /auth/logout , and /auth/callback endpoints Provides server-side session access through auth0.getSession() for Server Components and API routes, plus client-side useUser() hook for client components Requires middleware configuration ( middleware.ts for Next.js 15+, or proxy.ts for Next.js 16) to...
npx skills add https://github.com/auth0/agent-skills --skill auth0-nextjs
Download ZIPGitHub37
Auth0 Next.js Integration
Add authentication to Next.js applications using @auth0/nextjs-auth0. Supports both App Router and Pages Router.
When NOT to Use
-
Client-side only React apps - Use
auth0-reactfor Vite/CRA SPAs -
React Native mobile apps - Use
auth0-react-nativefor 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
Welcome, {user.name}!
Logout
); }
return Login ; }
### 6. Test Authentication
Start your dev server:
npm run dev
Visit `http://localhost:3000` and test the login flow.
## Detailed Documentation
- **[Setup Guide](https://github.com/auth0/agent-skills/blob/main/plugins/auth0/skills/auth0-nextjs/references/setup.md)** - Automated setup scripts, environment configuration, Auth0 CLI usage
- **[Integration Guide](https://github.com/auth0/agent-skills/blob/main/plugins/auth0/skills/auth0-nextjs/references/integration.md)** - Server-side auth, protected routes, API routes, middleware
- **[API Reference](https://github.com/auth0/agent-skills/blob/main/plugins/auth0/skills/auth0-nextjs/references/api.md)** - Complete SDK API, hooks, helpers, session management
## Related Skills
- `auth0-quickstart` - Basic Auth0 setup
- `auth0-migration` - Migrate from another auth provider
- `auth0-mfa` - Add Multi-Factor Authentication
- `auth0-cli` - Manage Auth0 resources from the terminal
## 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](https://github.com/auth0/agent-skills/blob/main/plugins/auth0/skills/auth0-nextjs/references/integration.md#protected-pages-app-router)
- Protected pages (Pages Router) → [Integration Guide](https://github.com/auth0/agent-skills/blob/main/plugins/auth0/skills/auth0-nextjs/references/integration.md#protected-pages-pages-router)
- API routes with auth → [Integration Guide](https://github.com/auth0/agent-skills/blob/main/plugins/auth0/skills/auth0-nextjs/references/integration.md#protected-api-routes)
- Middleware protection → [Integration Guide](https://github.com/auth0/agent-skills/blob/main/plugins/auth0/skills/auth0-nextjs/references/integration.md#middleware)
## References
- [Auth0 Next.js SDK Documentation](https://auth0.com/docs/libraries/nextjs)
- [Auth0 Next.js Quickstart](https://auth0.com/docs/quickstart/webapp/nextjs)
- [SDK GitHub Repository](https://github.com/auth0/nextjs-auth0)npm install @auth0/nextjs-auth0Run this in your project — your agent picks the skill up automatically.
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-quickstartskill first
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=
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(orsrc/proxy.tsfor Next.js 16) -
Without
src/:lib/auth0.ts,middleware.ts(orproxy.tsfor 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 (
{children}
);
}
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 (
);
}
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 Loading...
;
if (user) {
return (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