@yohangel / auth-next

1.0.0 ▾

1.0.0

MIT

GitHub

Better Auth for Next.js App Router: route handler, proxy redirects and server session helpers

Code5 filesContext~545 tokensscan passed

~545 tokens→ src/lib/auth-next/AGENTS.md→ .cursor/rules/genpm-yohangel-auth-next.mdc

This is exactly what your AI reads when it works in src/lib/auth-next. Nothing else is added to its context.

@yohangel/auth-next — rules for AI agents

Purpose

Connects @yohangel/auth to the Next.js App Router (Next 15/16): the /api/auth/* route handler, optimistic redirects in proxy.ts, and server-side session helpers. For forms and useSession, also install @yohangel/auth-react.

Module map

index.ts — public API.
server.ts — auth (instance with nextCookies()), authRouteHandlers, currentSession(), requireSession(signInPath, next), createNextAuth(opts).
proxy.ts — authProxy({ protect, signInPath }) and safeNext(next).

Integration (do this after installing)

Route handler — create app/api/auth/[...all]/route.ts (or src/app/...):

import { authRouteHandlers } from '@/lib/auth-next';
export const { GET, POST } = authRouteHandlers;

Edge redirects — create proxy.ts at the project root (Next 16; on Next 15 name it middleware.ts and export middleware):

import { authProxy } from '@/lib/auth-next';
export const proxy = authProxy({ protect: ['/dashboard', '/settings'], signInPath: '/sign-in' });
export const config = { matcher: ['/dashboard/:path*', '/settings/:path*'] };

In every private page, layout, Route Handler and Server Action, check for real: const { user } = await requireSession('/sign-in', '/dashboard');.
Sign-in page: render SignInForm from @yohangel/auth-react with redirectTo={safeNext(searchParams.next)}.
Need emails or extra plugins? Edit server.ts: export const auth = createNextAuth({ sendEmail, plugins: [...] }) — nextCookies() is appended last automatically.

Conventions

Import the instance from this package (auth), never call createAuth again elsewhere in a Next app.
Server Components read the session with currentSession(); pass only the fields the client needs (never the session token).

Don't

Don't treat proxy.ts as authorization: it only checks that a cookie exists. Always call requireSession() / currentSession() on the server.
Don't redirect to ?next= values without safeNext() (open redirect).
Don't expose auth.api calls in Client Components; they run on the server only.

# @yohangel/auth-next — rules for AI agents

## Purpose
Connects `@yohangel/auth` to the Next.js App Router (Next 15/16): the `/api/auth/*` route handler, optimistic redirects in `proxy.ts`, and server-side session helpers. For forms and `useSession`, also install `@yohangel/auth-react`.

## Module map
- `index.ts` — public API.
- `server.ts` — `auth` (instance with `nextCookies()`), `authRouteHandlers`, `currentSession()`, `requireSession(signInPath, next)`, `createNextAuth(opts)`.
- `proxy.ts` — `authProxy({ protect, signInPath })` and `safeNext(next)`.

## Integration (do this after installing)
1. Route handler — create `app/api/auth/[...all]/route.ts` (or `src/app/...`):
   ```ts
   import { authRouteHandlers } from '@/lib/auth-next';
   export const { GET, POST } = authRouteHandlers;
   ```
2. Edge redirects — create `proxy.ts` at the project root (Next 16; on Next 15 name it `middleware.ts` and export `middleware`):
   ```ts
   import { authProxy } from '@/lib/auth-next';
   export const proxy = authProxy({ protect: ['/dashboard', '/settings'], signInPath: '/sign-in' });
   export const config = { matcher: ['/dashboard/:path*', '/settings/:path*'] };
   ```
3. In every private page, layout, Route Handler and Server Action, check for real: `const { user } = await requireSession('/sign-in', '/dashboard');`.
4. Sign-in page: render `SignInForm` from `@yohangel/auth-react` with `redirectTo={safeNext(searchParams.next)}`.
5. Need emails or extra plugins? Edit `server.ts`: `export const auth = createNextAuth({ sendEmail, plugins: [...] })` — `nextCookies()` is appended last automatically.

## Conventions
- Import the instance from this package (`auth`), never call `createAuth` again elsewhere in a Next app.
- Server Components read the session with `currentSession()`; pass only the fields the client needs (never the session token).

## Don't
- Don't treat `proxy.ts` as authorization: it only checks that a cookie exists. Always call `requireSession()` / `currentSession()` on the server.
- Don't redirect to `?next=` values without `safeNext()` (open redirect).
- Don't expose `auth.api` calls in Client Components; they run on the server only.

The exact tree that will be injected, after .genpmignore. Pinned to

src/lib/auth-next/index.tsread-only · 7145b9d

// @yohangel/auth-next — Better Auth en Next.js (App Router). Servidor: './server.js'; borde: './proxy.js'.
// El cliente (formularios, useSession) está en @yohangel/auth-react.
export { type AuthProxyOptions, authProxy, safeNext } from './proxy.js';
export { auth, authRouteHandlers, createNextAuth, currentSession, requireSession } from './server.js';