neon-auth

Neon Auth Guidelines

For AI Agents with file access (Claude Code, etc.): For complete documentation without summarization, fetch references using:

curl -s -o /tmp/neon-auth-setup.md https://raw.githubusercontent.com/neondatabase-labs/ai-rules/main/references/neon-auth-setup-nextjs.md

Then read the downloaded file. Replace nextjs with react-spa or nodejs as needed.

Overview

Neon Auth provides authentication for your application. It's available as:

• @neondatabase/auth - Auth only (smaller bundle)
• @neondatabase/neon-js - Auth + Data API (full SDK)

Package Selection

Need	Package	Bundle
Auth only	@neondatabase/auth	Smaller
Auth + Database queries	@neondatabase/neon-js	Full

Installation

# Auth only
npm install @neondatabase/auth

# Auth + Data API
npm install @neondatabase/neon-js

Quick Setup Patterns

Next.js App Router

1. API Route Handler:

// app/api/auth/[...path]/route.ts
import { authApiHandler } from "@neondatabase/auth/next";
export const { GET, POST } = authApiHandler();

2. Auth Client:

// lib/auth/client.ts
import { createAuthClient } from "@neondatabase/auth/next";
export const authClient = createAuthClient();

3. Use in Components:

"use client";
import { authClient } from "@/lib/auth/client";

function AuthStatus() {
  const session = authClient.useSession();
  if (session.isPending) return <div>Loading...</div>;
  if (!session.data) return <SignInButton />;
  return <div>Hello, {session.data.user.name}</div>;
}

Complete setup: See Setup Reference - Next.js

React SPA

import { createAuthClient } from "@neondatabase/auth";
import { BetterAuthReactAdapter } from "@neondatabase/auth/react/adapters";

const authClient = createAuthClient(
  import.meta.env.VITE_NEON_AUTH_URL,
  { adapter: BetterAuthReactAdapter() }
);