@repo/auth-next

Next.js integration for authentication. Provides cookie-backed session management (login, logout, getLoggedInUser, requireUser), composable API route handler factories for every auth flow (login, signup, OAuth, password reset, OTP), client-side React hooks, and a Next.js-specific Supabase auth client. Built on top of @repo/auth.

Dependencies

graph TD
  auth_next["@repo/auth-next"]
  analytics_core["@repo/analytics-core"]
  auth["@repo/auth"]
  db["@repo/db"]
  errors["@repo/errors"]
  logger["@repo/logger"]
  safe["@repo/safe"]
  typescript_config["@repo/typescript-config"]
  vitest_config["@repo/vitest-config"]
  auth_next --> analytics_core
  auth_next --> auth
  auth_next --> db
  auth_next --> errors
  auth_next --> logger
  auth_next --> safe
  auth_next -.-> typescript_config
  auth_next -.-> vitest_config

Exports

Architecture

graph TD
subgraph browser [Browser]
Hooks["React Hooks"]
Pages["Pages / Components"]
end

subgraph nextjs [Next.js Server]
Routes["API Route Files"]
Factories["Request Handler Factories"]
Session["Session Layer (cookies)"]
Layout["Layouts (requireUser)"]
end
subgraph authPkg ["@repo/auth"]
AuthClient["BaseAuthClient"]
GetUser["getUserFromToken"]
end
subgraph infra [Infrastructure]
Supabase["Supabase Auth"]
end
Hooks -->|"POST /api/auth/*"| Routes
Pages --> Layout
Layout --> Session
Routes --> Factories
Factories --> AuthClient
Factories --> Session
AuthClient --> Supabase
Session -->|"read cookie"| GetUser
GetUser --> DB["@repo/db"]

Session Management

Sessions are managed via three HTTP-only cookies:

Server-side functions

import { login, logout, getLoggedInUser, requireUser } from "@repo/auth-next";
Copy

Setting Up API Routes

Auth routes follow a three-step pattern:

1. Create the auth client

// apps/web/lib/auth.client.ts
import { createSupabaseNextAuthClient } from "@repo/auth-next/clients/supabase-next";

export const authClient = createSupabaseNextAuthClient({
  oauthRedirectUrl: `${process.env.NEXT_PUBLIC_APP_URL}/api/auth/oauth`,
  passwordResetRedirectUrl: `${process.env.NEXT_PUBLIC_APP_URL}/api/auth/reset-password`,
});
Copy

2. Create a request handler with a factory

// apps/web/app/api/auth/login/route.ts
import { createLoginRequestHandler } from "@repo/auth-next/api";

import { authClient } from "~/lib/auth.client";

const loginRequestHandler = createLoginRequestHandler({
  authClient,
});

export { loginRequestHandler as POST };
Copy

3. Repeat for each auth flow

Each factory takes { authClient, logger?, handleError? } and returns a Next.js route handler. Export it as the appropriate HTTP method (POST, GET).

Request Handler Factories

All factories validate input with Zod, call the appropriate BaseAuthClient method, manage cookies via the session layer, and return a NextResponse.

Client-Side Hooks

All hooks make axios requests to /api/auth/* routes and return Safe<T> results.

Example: Login form

"use client";

import { useLoginWithEmailAndPassword } from "@repo/auth-next/hooks";
import { useRouter } from "next/navigation";

function LoginForm() {
  const router = useRouter();
  const { login, isLoggingIn, error } = useLoginWithEmailAndPassword();

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    const result = await login({
      email: formData.get("email") as string,
      password: formData.get("password") as string,
    });

    if (result.data) {
      router.push("/");
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" type="email" required />
      <input name="password" type="password" required />
      {error && <p>{error}</p>}
      <button type="submit" disabled={isLoggingIn}>
        {isLoggingIn ? "Signing in..." : "Sign in"}
      </button>
    </form>
  );
}
Copy

Protecting Pages

Use requireUser() in server-side layouts or pages. If the user is not authenticated, they are automatically redirected to /login.

// apps/web/app/(app)/layout.tsx
import { requireUser } from "@repo/auth-next";

export default async function AppLayout({ children }: React.PropsWithChildren) {
  const user = await requireUser();

  return (
    <UserProvider user={user}>
      {children}
    </UserProvider>
  );
}
Copy

For custom redirect targets:

const user = await requireUser({ redirectTo: "/signin" });
Copy

Testing

The package exports Vitest mocks for all hooks via @repo/auth-next/tests:

import "@repo/auth-next/tests";
import { mockUseLoginWithEmailAndPassword } from "@repo/auth-next/tests";

// Mocks are automatically wired up via vi.mock
mockUseLoginWithEmailAndPassword.mockReturnValue({
  login: vi.fn(),
  isLoggingIn: false,
  error: null,
});
Copy

Scripts