neon-js

neondatabase's avatarfrom neondatabase

Sets up the full Neon JS SDK with unified auth and PostgREST-style database queries. Configures auth client, data client, and type generation. Use when building apps that need both authentication and database access in one SDK.

⭐58stars🔀10forks📁View on GitHub🕐Updated Dec 19, 2025
[Databases and Warehouses]

When & Why to Use This Skill

The Neon JS SDK Integration skill for Claude streamlines the setup of the unified Neon JS SDK, enabling developers to implement both authentication and PostgREST-style database queries within a single package. It automates the configuration of auth and data clients, handles TypeScript type generation, and provides framework-specific guidance for Next.js, React, and Node.js to ensure a type-safe and efficient development workflow.

Use Cases

  • Full-Stack Application Bootstrapping: Rapidly initialize Next.js or React projects with a pre-configured stack for user authentication and database management.
  • Supabase to Neon Migration: Simplify the transition from Supabase to Neon by utilizing the SupabaseAuthAdapter and familiar PostgREST-style query patterns.
  • Type-Safe Database Operations: Automatically generate and integrate TypeScript types for database schemas to minimize runtime errors and improve developer productivity.
  • Unified Auth and Data Architecture: Consolidate project dependencies by using one SDK (@neondatabase/neon-js) to handle both identity management and data fetching.
nameneon-js
descriptionSets up the full Neon JS SDK with unified auth and PostgREST-style database queries. Configures auth client, data client, and type generation. Use when building apps that need both authentication and database access in one SDK.
allowed-tools["bash", "write", "read_file"]

Neon JS SDK Integration

Set up the unified Neon JS SDK for authentication and database queries in one package.

When to Use This Skill

  • Building apps that need both auth and database queries
  • Migrating from Supabase to Neon
  • Using PostgREST-style API for database access
  • Need type-safe database queries with generated types

Package: @neondatabase/neon-js (full SDK with auth + data API)

Need auth only? Use the neon-auth skill instead for @neondatabase/auth with a smaller bundle.

Code Generation Rules

When generating TypeScript/JavaScript code, follow these rules:

Complete reference: See Code Generation Rules for:

  • Import path handling (path aliases vs relative imports)
  • Neon package imports (subpath exports, adapter patterns)
  • CSS import strategy (Tailwind detection, single import method)
  • File structure patterns

Key points:

  • Check tsconfig.json for path aliases before generating imports
  • Use relative imports if unsure or no aliases exist
  • BetterAuthReactAdapter MUST be imported from auth/react/adapters subpath
  • Adapters are factory functions - call them with ()
  • Choose ONE CSS import method (Tailwind or CSS, not both)

Available Guides

Each guide is a complete, self-contained walkthrough with numbered phases:

  • guides/setup.md - Complete setup guide for Next.js with auth + data API

I'll automatically detect your context (package manager, framework, existing setup) and select the appropriate guide based on your request.

For troubleshooting, see the Troubleshooting Guide in references.

Quick Examples

Tell me what you're building - I'll handle the rest:

  • "Set up Neon JS for my Next.js app" -> Loads full stack guide, configures auth + data
  • "Add database queries to my auth setup" -> Configures data API client
  • "Migrate from Supabase" -> Uses SupabaseAuthAdapter for compatibility

Reference Documentation

Primary Resource: See neon-js.mdc for comprehensive guidelines including:

  • Client setup for all frameworks
  • Database query patterns (PostgREST syntax)
  • Auth adapter options (BetterAuth, Supabase)
  • Type generation
  • Error handling

Auth Details: See neon-auth.mdc for:

  • All authentication methods
  • UI components
  • Session management

Framework-Specific Setup (choose your framework):

Framework-Specific UI (choose your framework):

Data API & Shared References:

Templates

  • templates/full-client.ts - Unified auth + data client configuration
  • neon-auth - Auth only (smaller bundle, no data queries)
  • neon-drizzle - Drizzle ORM setup (alternative to PostgREST)
  • neon-serverless - Direct database connections
  • add-neon-docs - Add Neon best practices to your project (run after setup)

Workflow

I will:

  1. Detect your project context automatically (Next.js, React SPA, Node.js)
  2. Select and load the appropriate guide
  3. Follow the guide's phases sequentially
  4. Track progress using the guide's workflow checklist
  5. Load reference files only when needed
  6. Offer to add Neon best practices to your project docs

Ready to get started? Just describe what you're building!