neon-js

Neon JS SDK 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

The @neondatabase/neon-js SDK provides a unified client for Neon Auth and Data API. It combines authentication handling with PostgREST-compatible database queries.

Package Selection

Use Case	Package	Notes
Auth + Data API	@neondatabase/neon-js	Full SDK, includes everything
Auth only	@neondatabase/auth	Smaller bundle, no database dependencies
Data API only	@neondatabase/postgrest-js	Bring your own auth

Do NOT install @neondatabase/neon-js if you only need authentication - use @neondatabase/auth instead for a smaller bundle.

Installation

npm install @neondatabase/neon-js

Quick Setup Patterns

Next.js (Most Common)

1. API Route Handler:

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

2. Auth Client:

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

3. Database Client:

// lib/db/client.ts
import { createClient } from "@neondatabase/neon-js";
import type { Database } from "./database.types";

export const dbClient = createClient<Database>({
  auth: { url: process.env.NEXT_PUBLIC_NEON_AUTH_URL! },
  dataApi: { url: process.env.NEON_DATA_API_URL! },
});

Complete setup: See Setup Reference - Next.js for auth, and Data API Reference for database