React Router quickstart

The @authdog/react-router SDK provides a loader-based session, a logout loader, and a minimal client provider for React Router 7 in framework mode. Loaders and actions run on the Web Fetch API, so the SDK returns plain Response objects and needs no Node adapter.

@authdog/react-router is not yet published to npm (npm view @authdog/react-router returns 404 at the time of writing). Version 0.1.0 is set to publish publicly from the web-sdk repository, so install it from there until it lands on the registry.

Install

npm install @authdog/react-router

yarn add @authdog/react-router

pnpm add @authdog/react-router

bun add @authdog/react-router

deno add npm:@authdog/react-router

react and react-dom (^18.2 or ^19) and react-router ^7 are peer dependencies. The package ships two entry points: @authdog/react-router (server loaders) and @authdog/react-router/client (provider). Set PK_AUTHDOG to your environment's public key (pk_...) in the server environment.

Read the session in a loader

identityLoader() reads PK_AUTHDOG and returns a loader. Read its result with useLoaderData:

// app/routes/_index.tsx
import { identityLoader } from "@authdog/react-router"

export const loader = identityLoader()

import { useLoaderData } from "react-router"

export default function Index() {
  const { user, isAuthenticated, signinUri } = useLoaderData<typeof loader>()
  return isAuthenticated ? <p>Hi {user.displayName}</p> : <a href={signinUri}>Sign in</a>
}

The loader returns { user, isAuthenticated, signinUri }, where signinUri is the hosted sign-in URL for your environment. Behaviour:

• If the request has a ?token=, the loader resolves it through the Authdog userinfo endpoint. On success it sets two HttpOnly Secure SameSite=Strict cookies, user_session_<envId> (the user JSON) and user_session_hash_<envId> (the token), with no-store cache headers.
• Otherwise it re-validates the session by calling userinfo with the token from user_session_hash_<envId>.
• If neither succeeds, it returns { user: null, isAuthenticated: false, signinUri }.

The raw token never reaches client JavaScript. It throws if PK_AUTHDOG is missing, malformed, or points at an untrusted identity host. The cookies are Secure, so test over HTTPS or on localhost.

Provider

Mount AuthdogProvider at the app root. It takes no props besides children. When it sees a ?token= in the URL, it strips the parameter and reloads once so the loader runs:

import { AuthdogProvider } from "@authdog/react-router/client"

export default function App() {
  return <AuthdogProvider>{/* ... */}</AuthdogProvider>
}

ReloadPage is also exported. It strips ?token= from the URL without reloading.

Sign out

Export logoutLoader from a route. It clears both session cookies and redirects to /:

// app/routes/logout.tsx
import { logoutLoader } from "@authdog/react-router"

export const loader = logoutLoader

For local development, identityDevAction({ redirectTo }) clears the same cookies and redirects to a sanitized redirectTo (default /). It throws in production.

Other exports

reactRouterAuthLoader, authenticateWithCookies, createAuthResponse, jsonResponse, and redirectResponse are exported for custom loaders. Most apps need only identityLoader.

Caveats

• isAuthenticated means userinfo accepted the token on that request. Cookie presence alone is not treated as authentication.
• The SDK does not protect routes for you. Check isAuthenticated in each loader that needs it, and enforce authorization in actions and API routes.
• Verbose [Authdog] debug logging is enabled whenever NODE_ENV is not production.

Next steps

• Sign up & sign in: the flows behind the redirect.
• Backend requests: the verification model, in depth.