neon-plugin

Neon database development skills including authentication, Drizzle ORM, serverless drivers, and toolkit utilities

View on GitHub
Author Neon Team
Namespace @neondatabase-labs/neon
Category general
Version 1.1.0
Stars 48
Downloads 4
self.md verified
Table of content

Neon database development skills including authentication, Drizzle ORM, serverless drivers, and toolkit utilities

Installation

npx claude-plugins install @neondatabase-labs/neon/neon-plugin

Contents

Folders: evals, skills

Files: README.md

Documentation

Complete integration plugin for using Neon Postgres databases with Claude Code, featuring guided skills and MCP server integration.

Features

Available Skills

neon-drizzle

Set up and integrate Drizzle ORM with Neon Postgres databases. Includes comprehensive guides for:

neon-serverless

Connect to Neon databases in serverless environments with the Neon Serverless driver. Optimize for:

neon-toolkit

Create and manage ephemeral Neon databases for testing and prototyping. Perfect for:

Knowledge Installation

After completing a skill workflow, you can optionally install Neon best practices to your project’s AI knowledge base.

How It Works

  1. Complete any Neon skill workflow (Drizzle, Serverless, Toolkit, etc.)
  2. I’ll detect your project’s AI structure:
    • Cursor IDE: .cursor/rules/
    • Claude Code: CLAUDE.md or .claude/
    • Custom: agents.md, .ai/, or other locations
  3. I’ll ask if you want to install documentation
  4. I’ll copy the relevant .mdc files with source attribution
  5. Your AI assistant can now reference these patterns automatically

What Gets Installed

Each skill installs its relevant best practices:

No AI Structure Yet?

If your project doesn’t have an AI knowledge structure yet:

For Developers

Skills use a workflow-based approach. See shared/workflows/install-knowledge.md for the universal workflow that guides me through the installation process.

Getting Started

  1. Install the plugin in Claude Code
  2. Activate a skill based on your needs
  3. Follow the guided workflow
  4. Optionally install knowledge to your project

MCP Server Integration

This plugin connects to Neon’s remote MCP server for real-time resource management. The MCP server provides:

Configuration is handled automatically through .mcp.json.

Repository Structure

neon-plugin/
├── .claude-plugin/
   └── plugin.json        # Plugin metadata
├── .mcp.json              # MCP server configuration
└── skills/
    ├── add-neon-docs/
       ├── SKILL.md
       ├── install-knowledge.md        # Workflow for knowledge installation
       └── skill-knowledge-map.json    # Metadata for knowledge installation
    ├── neon-drizzle/
       ├── SKILL.md
       ├── guides/        # Step-by-step workflow guides
       ├── references/    # Technical reference docs
       ├── scripts/       # Utility scripts
       └── templates/     # Code templates
    ├── neon-serverless/
       └── SKILL.md
    └── neon-toolkit/
        └── SKILL.md

Contributing

To add a new skill or update existing ones:

  1. Follow the skill structure pattern
  2. Update skills/add-neon-docs/skill-knowledge-map.json if adding knowledge files
  3. Reference the add-neon-docs skill at the end of your SKILL.md
  4. Test the workflow thoroughly

Resources

License

See the main repository for license information.

Included Skills

This plugin includes 5 skill definitions:

add-neon-docs

Use this skill when the user asks to add documentation, add docs, add references, or install documentation about Neon. Adds Neon best practices reference links to project AI documentation (CLAUDE.md, AGENTS.md, or Cursor rules). Does not install packages or modify code.

View skill definition

Add Neon Knowledge References to Project

This skill adds reference links to Neon documentation and best practices in your project’s AI documentation file, enabling AI assistants to quickly access Neon-specific patterns and guidelines without cluttering your project with large documentation files.

How It Works

This skill follows a simple workflow:

  1. Load metadata - Read skill information from skill-knowledge-map.json
  2. Detect documentation file - Find CLAUDE.md, AGENTS.md, or Cursor rules files
  3. Ask permission - Show what will be added and where
  4. Add references - Insert URLs in a “Resources & References” section
  5. Report completion - Confirm successful installation

For detailed workflow steps, see install-knowledge.md.

Parameters

SKILL_NAME Parameter

Optional. Specifies which skill documentation to install (e.g., "neon-drizzle"). If not provided, you’ll be prompted to choose from available skills defined in skill-knowledge-map.json.

Usage Examples

Called from another skill:

Execute the add-neon-docs skill with SKILL_NAME="neon-drizzle"

Called directly by user:

What Gets Added

References are added to a “Resources & References” section in your AI documentation file:

## Resources & References

- **Neon and Drizzle ORM best practices**: htt

...(truncated)

</details>

### neon-auth

> Sets up Neon Auth for your application. Configures authentication, creates auth routes, and generates UI components. Use when adding authentication to Next.js, React SPA, or Node.js projects.

<details>
<summary>View skill definition</summary>

# Neon Auth Integration

Add authentication to your application.

## When to Use This Skill

- Adding authentication to a new or existing project
- Implementing sign-in, sign-up, and session management
- Configuring social authentication (Google, GitHub)

**Package**: `@neondatabase/auth` (auth only, smaller bundle)

**Need database queries too?** Use the `neon-js` skill instead for `@neondatabase/neon-js` with unified auth + data API.

## Code Generation Rules

When generating TypeScript/JavaScript code, follow these rules:

**Complete reference:** See [Code Generation Rules](https://raw.githubusercontent.com/neondatabase-labs/ai-rules/main/references/code-generation-rules.md) 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/nextjs-setup.md`** - Complete Next.js App Router setup guide
- **`guides/react-spa-setup.md`** - Detailed React SPA guide with react-router-dom integration

I'l

...(truncated)

</details>

### neon-drizzle

> Creates a fully functional Drizzle ORM setup with a provisioned Neon database. Installs dependencies, provisions database credentials, configures connections, generates schemas, and runs migrations. Results in working code that can immediately connect to and query the database. Use when creating new projects with Drizzle, adding ORM to existing applications, or modifying database schemas.

<details>
<summary>View skill definition</summary>

# Neon Drizzle Integration

Comprehensive Drizzle ORM setup for Neon databases with guided workflows.

## When to Use This Skill

- Setting up Drizzle in a new project (Next.js, Vite, Express, etc.)
- Integrating Drizzle into an existing application
- Creating or modifying database schemas
- Troubleshooting migration issues

## Code Generation Rules

When generating TypeScript/JavaScript code:
- BEFORE generating import statements, check tsconfig.json for path aliases (compilerOptions.paths)
- If path aliases exist (e.g., "@/*": ["./src/*"]), use them (e.g., import { x } from '@/lib/utils')
- If NO path aliases exist or unsure, ALWAYS use relative imports (e.g., import { x } from '../../../lib/utils')
- Verify imports match the project's configuration
- Default to relative imports - they always work regardless of configuration

## Available Guides

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

- **`guides/new-project.md`** - Full setup from scratch (see: Table of Contents)
- **`guides/existing-project.md`** - Add Drizzle to running apps (see: Table of Contents)
- **`guides/schema-only.md`** - Schema creation and modification (see: Table of Contents)
- **`guides/troubleshooting.md`** - Debug common issues (organized by error type)

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

## Quick Examples

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

- 

...(truncated)

</details>

### neon-js

> 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.

<details>
<summary>View skill definition</summary>

# 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](https://raw.githubusercontent.com/neondatabase-labs/ai-rules/main/references/code-generation-rules.md) 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 det

...(truncated)

</details>

### neon-serverless

> Configures Neon Serverless Driver for Next.js, Vercel Edge Functions, AWS Lambda, and other serverless environments. Installs @neondatabase/serverless, sets up environment variables, and creates working API route examples with TypeScript types. Use when users need to connect their application to Neon, fetch or query data from a Neon database, integrate Neon with Next.js or serverless frameworks, or set up database access in edge/serverless environments where traditional PostgreSQL clients don't work.

<details>
<summary>View skill definition</summary>

# Neon Serverless Skill

Configures the Neon Serverless Driver for optimal performance in serverless and edge computing environments.

## When to Use

- Setting up connections for edge functions (Vercel Edge, Cloudflare Workers)
- Configuring serverless APIs (AWS Lambda, Google Cloud Functions)
- Optimizing for low-latency database access
- Implementing connection pooling for high-throughput apps

**Not recommended for:** Complex multi-statement transactions (use WebSocket Pool), persistent servers (use native PostgreSQL drivers), or offline-first applications.

## Code Generation Rules

When generating TypeScript/JavaScript code:
- BEFORE generating import statements, check tsconfig.json for path aliases (compilerOptions.paths)
- If path aliases exist (e.g., "@/*": ["./src/*"]), use them (e.g., import { x } from '@/lib/utils')
- If NO path aliases exist or unsure, ALWAYS use relative imports (e.g., import { x } from '../../../lib/utils')
- Verify imports match the project's configuration
- Default to relative imports - they always work regardless of configuration

## Reference Documentation

**Primary Resource:** See `[neon-serverless.mdc](https://raw.githubusercontent.com/neondatabase-labs/ai-rules/main/neon-serverless.mdc)` in project root for comprehensive guidelines including:
- Installation and compatibility requirements
- HTTP vs WebSocket adapter selection
- Connection pooling strategies
- Query optimization patterns
- Error handling and troubleshooting

## Quick Setu

...(truncated)

</details>

## Source

[View on GitHub](https://github.com/neondatabase-labs/ai-rules)