nextjs

---
name: nextjs
description: Add authdog to a Next.js App Router app with @authdog/nextjs-app — AuthdogProvider, useUser/useAuth hooks, useAuthMiddleware callback exchange, and HttpOnly cookies. Use when the user asks to integrate authdog auth into a Next.js 15/16 app.
---

# authdog for Next.js (App Router)

The `@authdog/nextjs-app` SDK integrates Authdog with the Next.js App Router: a client provider, `useAuth`/`useUser` hooks, and server helpers for callback exchange and logout.

## When to use this skill

The user wants to add "Sign in with authdog" (or authdog session handling) to a Next.js app using the App Router. For the Pages Router or a custom Node server, use the [Express](../express/SKILL.md) / [Fastify](../fastify/SKILL.md) backend skills instead.

## What you need from the user first

Their authdog **public key** (`pk_...`), from the [authdog console](https://console.authdog.com/) → Project settings. The public key is safe to expose client-side; the secret key (`sk_...`) is backend-only and is not used by this SDK.

## Steps

### 1. Install

```bash
npm install @authdog/nextjs-app
```

Supports Next.js 15/16 and React 18 or 19.

### 2. Set environment variables

Set `NEXT_PUBLIC_PK_AUTHDOG` for client calls and `PK_AUTHDOG` for server helpers. Both contain the same public key (`pk_...`):

```bash
# .env.local
NEXT_PUBLIC_PK_AUTHDOG=pk_...
PK_AUTHDOG=pk_...
```

### 3. Wrap your app

Mount `AuthdogProvider` in the root layout. It stores a `?token=` value only when it has three JWT-shaped segments, then strips the URL. This regex is a shape check, not signature, issuer, audience, or expiry validation:

```tsx
// app/layout.tsx
import { AuthdogProvider } from "@authdog/nextjs-app/client"

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html>
      <body>
        <AuthdogProvider>{children}</AuthdogProvider>
      </body>
    </html>
  )
}
```

### 4. Exchange the callback

`useAuthMiddleware(publicKey)` processes `?token=` on matching requests, validates it through Authdog userinfo, and writes HttpOnly cookies. It does **not** protect routes or validate cookies on later requests:

```ts
// middleware.ts
import { useAuthMiddleware } from "@authdog/nextjs-app/server"
export default useAuthMiddleware(process.env.PK_AUTHDOG!)

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
}
```

Return from hosted sign-in to a URL matched by this middleware.

### 5. Read the user

`useUser` calls Authdog userinfo and returns the current profile. `useAuth` only reports whether a browser token exists; do not use it to authorize protected work:

```tsx
"use client"
import { useUser } from "@authdog/nextjs-app"

export default function Dashboard() {
  const { user, isLoading } = useUser()
  if (isLoading) return null
  if (!user) return <p>Not signed in</p>
  return <p>Signed in as {user.emails?.[0]?.value}</p>
}

// useAuth() -> { token, isAuthenticated, isLoading }
```

### 6. Protect server-side work

For protected Route Handlers or Server Actions, independently validate the credential on every request with a [backend SDK](../express/SKILL.md), then apply [authorization](https://www.authdog.com/docs/concepts/authorization). `logoutHandler` clears server cookies; `clearAuthdogSession()` clears only browser local storage, so complete logout should do both.

## Gotchas

- **`useAuth` is not authorization**: it only reports browser token presence. Use `useUser` (which calls userinfo) for identity, and a backend SDK for any privileged action.
- **Middleware exchanges, it doesn't guard**: `useAuthMiddleware` writes the cookie on the callback request; it does not reject later unauthenticated requests. Validate on every protected request server-side.
- **JWT-shape regex is not validation**: the provider stores `?token=` after a shape check only. Real validation happens at userinfo.

## Next steps

- [Component reference](https://www.authdog.com/docs/components): the `@authdog/react-elements` UI used with the provider.
- [Backend requests](https://www.authdog.com/docs/backend): validate the same session on your API routes.

More agent context in authdog/agent-skills

31 other files this repository gives its agents.