remix

---
name: remix
description: Add authdog to a Remix app with @authdog/remix-node — identityLoader callback exchange, AuthdogProvider URL cleanup, HttpOnly session cookies, and per-loader enforcement. Use when the user asks to integrate authdog auth into a Remix v2+ app.
---

# authdog for Remix

The `@authdog/remix-node` SDK integrates Authdog with Remix through a callback-aware loader, client URL cleanup, and HttpOnly session cookies.

## When to use this skill

The user wants to add "Sign in with authdog" (or authdog session handling) to a Remix app (v2.15+).

## What you need from the user first

Their authdog **public key** (`pk_...`), set as `PK_AUTHDOG` on the server. The public key is safe to expose; the secret key is not used by this SDK.

## Steps

### 1. Install

```bash
npm install @authdog/remix-node
```

Requires `@remix-run/node` `^2.15`+ and React 18 or 19.

### 2. Set environment variables

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

### 3. Wrap the app

Run `identityLoader()` on the route users return to after hosted sign-in. The loader validates `?token=` through Authdog userinfo before setting HttpOnly cookies. `AuthdogProvider` removes the token after the server has handled the request:

```tsx
// app/root.tsx
import { Outlet, Scripts } from "@remix-run/react"
import { AuthdogProvider, ReloadPage } from "@authdog/remix-node/client"
import { identityLoader } from "@authdog/remix-node"

export const loader = identityLoader()

export default function App() {
  return (
    <AuthdogProvider>
      <Outlet />
      <Scripts />
      <ReloadPage />
    </AuthdogProvider>
  )
}
```

### 4. Resolve the session in a loader

The loader returns `{ user, isAuthenticated, signinUri }`. It revalidates cookie credentials through userinfo, but returning an unauthenticated result does not redirect or deny access. Enforce the result in each protected loader:

```tsx
// app/routes/profile.tsx
import { useLoaderData } from "@remix-run/react"
import { identityLoader } from "@authdog/remix-node"
import { redirect, type LoaderFunctionArgs } from "@remix-run/node"

const loadIdentity = identityLoader()

export const loader = async (args: LoaderFunctionArgs) => {
  const response = await loadIdentity(args)
  const identity = await response.json()
  if (!identity.isAuthenticated) throw redirect(identity.signinUri)
  return identity
}

export default function Profile() {
  const { user } = useLoaderData<typeof loader>()
  return <p>Signed in as {user.emails?.[0]?.value}</p>
}
```

If this protected loader may receive the initial callback, preserve the original `Response` headers when adapting it; otherwise its `Set-Cookie` headers are lost. A dedicated callback/root loader avoids that issue.

### 5. Sign out

Wire a route to `logoutLoader`, which clears the session and redirects:

```ts
// app/routes/logout.ts
import { logoutLoader } from "@authdog/remix-node"
export const loader = logoutLoader
```

Pair the loader-resolved session with your [authorization](https://www.authdog.com/docs/concepts/authorization) model to decide what a user may do.

## Gotchas

- **The loader doesn't deny access**: `identityLoader` revalidates the cookie but returns an unauthenticated result rather than redirecting. Each protected loader must check `isAuthenticated` itself.
- **Preserve `Set-Cookie` on callback**: if a protected loader also handles the initial callback, don't `response.json()` and return only the body — that drops the `Set-Cookie` headers. Use a dedicated root/callback loader.
- **Client cleanup vs server cookie**: `AuthdogProvider` strips `?token=` client-side; the HttpOnly cookie is set by the server loader. Both must run for a complete session.

## Next steps

- [Component reference](https://www.authdog.com/docs/components): the `@authdog/react-elements` UI (e.g. `UserProfile`).
- [Backend requests](https://www.authdog.com/docs/backend): the verification model, in depth.

More agent context in authdog/agent-skills

31 other files this repository gives its agents.