auth0-nextjs

Included with Lifetime

$97 forever

Auth0 integration with Next.js

Web Dev

What this skill does


# Auth0 Next.js Skill

Patterns for integrating Auth0 with Next.js applications.

## Setup

### Installation

```bash
npm install @auth0/nextjs-auth0
```

### Configuration

```typescript
// .env.local
AUTH0_SECRET=use-openssl-rand-base64-32
AUTH0_BASE_URL=http://localhost:3000
AUTH0_ISSUER_BASE_URL=https://your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret
AUTH0_AUDIENCE=your-api-audience  # Optional
```

### API Route Handler

```typescript
// app/api/auth/[auth0]/route.ts
import { handleAuth } from '@auth0/nextjs-auth0'

export const GET = handleAuth()

// With custom handlers
export const GET = handleAuth({
  login: handleLogin({
    authorizationParams: {
      audience: process.env.AUTH0_AUDIENCE,
      scope: 'openid profile email',
    },
    returnTo: '/dashboard',
  }),
  callback: handleCallback({
    afterCallback: async (req, session) => {
      // Custom logic after login
      await createUserIfNotExists(session.user)
      return session
    },
  }),
  logout: handleLogout({
    returnTo: '/',
  }),
})
```

## Client-Side Auth

### UserProvider

```tsx
// app/layout.tsx
import { UserProvider } from '@auth0/nextjs-auth0/client'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <UserProvider>{children}</UserProvider>
      </body>
    </html>
  )
}
```

### useUser Hook

```tsx
'use client'

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

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

  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  if (!user) {
    return (
      <div>
        <a href="/api/auth/login">Login</a>
      </div>
    )
  }

  return (
    <div>
      <img src={user.picture} alt={user.name} />
      <h2>{user.name}</h2>
      <p>{user.email}</p>
      <a href="/api/auth/logout">Logout</a>
    </div>
  )
}
```

### Protected Client Component

```tsx
'use client'

import { withPageAuthRequired } from '@auth0/nextjs-auth0/client'

function Dashboard() {
  const { user } = useUser()

  return (
    <div>
      <h1>Dashboard</h1>
      <p>Welcome, {user?.name}</p>
    </div>
  )
}

export default withPageAuthRequired(Dashboard, {
  onRedirecting: () => <div>Loading...</div>,
  onError: (error) => <div>Error: {error.message}</div>,
})
```

## Server-Side Auth

### getSession

```tsx
// app/profile/page.tsx
import { getSession } from '@auth0/nextjs-auth0'
import { redirect } from 'next/navigation'

export default async function ProfilePage() {
  const session = await getSession()

  if (!session) {
    redirect('/api/auth/login')
  }

  return (
    <div>
      <h1>Profile</h1>
      <p>Email: {session.user.email}</p>
      <p>User ID: {session.user.sub}</p>
    </div>
  )
}
```

### withPageAuthRequired (Server)

```tsx
// app/dashboard/page.tsx
import { withPageAuthRequired } from '@auth0/nextjs-auth0'

export default withPageAuthRequired(
  async function Dashboard() {
    const session = await getSession()

    return (
      <div>
        <h1>Dashboard</h1>
        <p>Welcome, {session?.user.name}</p>
      </div>
    )
  },
  { returnTo: '/dashboard' }
)
```

### API Route Protection

```typescript
// app/api/protected/route.ts
import { withApiAuthRequired, getSession } from '@auth0/nextjs-auth0'
import { NextResponse } from 'next/server'

export const GET = withApiAuthRequired(async function handler(req) {
  const session = await getSession()

  return NextResponse.json({
    user: session?.user,
    message: 'Protected data',
  })
})
```

## Access Tokens

### Getting Access Token

```typescript
// app/api/external/route.ts
import { getAccessToken } from '@auth0/nextjs-auth0'
import { NextResponse } from 'next/server'

export async function GET() {
  const { accessToken } = await getAccessToken({
    scopes: ['read:data'],
  })

  const response = await fetch(`${process.env.API_URL}/data`, {
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  })

  const data = await response.json()
  return NextResponse.json(data)
}
```

### Token Refresh

```typescript
import { getAccessToken } from '@auth0/nextjs-auth0'

export async function GET() {
  const { accessToken } = await getAccessToken({
    refresh: true,  // Force refresh if expired
  })

  // Use accessToken
}
```

## Middleware Protection

```typescript
// middleware.ts
import { withMiddlewareAuthRequired } from '@auth0/nextjs-auth0/edge'

export default withMiddlewareAuthRequired()

export const config = {
  matcher: [
    '/dashboard/:path*',
    '/profile/:path*',
    '/api/protected/:path*',
  ],
}

// With custom logic
import { NextResponse } from 'next/server'
import { getSession } from '@auth0/nextjs-auth0/edge'

export default withMiddlewareAuthRequired(async function middleware(req) {
  const res = NextResponse.next()
  const session = await getSession(req, res)

  // Add custom headers
  res.headers.set('x-user-id', session?.user.sub || '')

  // Role-based redirect
  const roles = session?.user['https://myapp.com/roles'] || []
  if (req.nextUrl.pathname.startsWith('/admin') && !roles.includes('admin')) {
    return NextResponse.redirect(new URL('/unauthorized', req.url))
  }

  return res
})
```

## Organization Support

### Organization Login

```typescript
// app/api/auth/[auth0]/route.ts
import { handleAuth, handleLogin } from '@auth0/nextjs-auth0'

export const GET = handleAuth({
  login: handleLogin({
    authorizationParams: {
      organization: 'org_123',  // Specific org
      // or
      // organization: req.query.org,  // Dynamic org
    },
  }),
})
```

### Checking Organization

```tsx
import { getSession } from '@auth0/nextjs-auth0'

export default async function OrgPage() {
  const session = await getSession()
  const orgId = session?.user.org_id

  if (!orgId) {
    return <div>Please select an organization</div>
  }

  return <div>Organization: {session?.user.org_name}</div>
}
```

## Custom Session Handling

```typescript
// app/api/auth/[auth0]/route.ts
import { handleAuth, handleCallback } from '@auth0/nextjs-auth0'

export const GET = handleAuth({
  callback: handleCallback({
    afterCallback: async (req, session, state) => {
      // Modify session
      session.user.customClaim = 'value'

      // Add to database
      await upsertUser({
        auth0Id: session.user.sub,
        email: session.user.email,
        name: session.user.name,
      })

      return session
    },
  }),
})
```

## Integration

Used by:
- `frontend-developer` agent
- `fullstack-developer` agent

Files: 1

Size: 6.6 KB

Complexity: 13/100

Category: Web Dev

Source: https://github.com/bradtaylorsf/alphaagent-team/tree/main/plugins/aai-stack-auth0/skills/auth0-nextjs

Related in Web Dev

generating-lwc-components

Included

Lightning Web Components with PICKLES methodology and 165-point scoring. Use this skill when the user creates or edits LWC components, builds wire service patterns, or writes Jest tests for LWC. TRIGGER when: user creates/edits LWC components, touches lwc/**/*.js, .html, .css, .js-meta.xml files, or asks about wire service, SLDS, or Jest LWC tests. DO NOT TRIGGER when: Apex classes (use generating-apex), Aura components, or Visualforce.

Web Devscripts

tanstack-query

Included

Manage server state in React with TanStack Query v5. Set up queries with useQuery, mutations with useMutation, configure QueryClient caching strategies, implement optimistic updates, and handle infinite scroll with useInfiniteQuery. Use when: setting up data fetching in React projects, migrating from v4 to v5, or fixing object syntax required errors, query callbacks removed issues, cacheTime renamed to gcTime, isPending vs isLoading confusion, keepPreviousData removed problems.

Web Devscripts

document-processor-api

Included

Process documents with Nutrient DWS. Use when the user wants to generate PDFs from HTML or URLs, convert Office/images/PDFs, assemble or split packets, OCR scans, extract text/tables/key-value pairs, redact PII, watermark, sign, fill forms, optimize PDFs, or produce compliance outputs like PDF/A or PDF/UA. Triggers include convert to PDF, merge these PDFs, OCR this scan, extract tables, redact PII, sign this PDF, make this PDF/A, or linearize for web delivery.

Web Devscripts

nutrient-document-processing

Included

Web Devscripts

tanstack-query

Included

Manage server state in React with TanStack Query v5. Covers useMutationState, simplified optimistic updates, throwOnError, network mode (offline/PWA), and infiniteQueryOptions. Use when setting up data fetching, fixing v4→v5 migration errors (object syntax, gcTime, isPending, keepPreviousData), or debugging SSR/hydration issues with streaming server components.

Web Devscripts

accelint-nextjs-best-practices

Included

Next.js performance optimization and best practices. Use when writing Next.js code (App Router or Pages Router); implementing Server Components, Server Actions, or API routes; optimizing RSC serialization, data fetching, or server-side rendering; reviewing Next.js code for performance issues; fixing authentication in Server Actions; or implementing Suspense boundaries, parallel data fetching, or request deduplication.

Web Devscripts