neon-plugin
Neon database development skills including authentication, Drizzle ORM, serverless drivers, and toolkit utilities
View on GitHubTable 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
- Guided Skills: Step-by-step workflows for common Neon tasks
- MCP Integration: Real-time Neon resource management through Model Context Protocol
- Knowledge Installation: Add Neon best practices to your project’s AI knowledge base
Available Skills
neon-drizzle
Set up and integrate Drizzle ORM with Neon Postgres databases. Includes comprehensive guides for:
- New project setup
- Existing project integration
- Schema-only workflows
- Migration troubleshooting
neon-serverless
Connect to Neon databases in serverless environments with the Neon Serverless driver. Optimize for:
- Edge functions
- Vercel deployments
- AWS Lambda
- Low latency and connection pooling
neon-toolkit
Create and manage ephemeral Neon databases for testing and prototyping. Perfect for:
- CI/CD pipelines
- Test isolation
- Quick development workflows
Knowledge Installation
After completing a skill workflow, you can optionally install Neon best practices to your project’s AI knowledge base.
How It Works
- Complete any Neon skill workflow (Drizzle, Serverless, Toolkit, etc.)
- I’ll detect your project’s AI structure:
- Cursor IDE:
.cursor/rules/ - Claude Code:
CLAUDE.mdor.claude/ - Custom:
agents.md,.ai/, or other locations
- Cursor IDE:
- I’ll ask if you want to install documentation
- I’ll copy the relevant
.mdcfiles with source attribution - Your AI assistant can now reference these patterns automatically
What Gets Installed
Each skill installs its relevant best practices:
- neon-drizzle: Drizzle ORM integration, connection adapters, schema patterns
- neon-serverless: Serverless connections, pooling, edge runtime considerations
- neon-toolkit: Ephemeral database creation, testing workflows
No AI Structure Yet?
If your project doesn’t have an AI knowledge structure yet:
- I can create a
CLAUDE.mdfile for you - Or you can run
/initin Claude Code first - Or set up Cursor rules manually
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
- Install the plugin in Claude Code
- Activate a skill based on your needs
- Follow the guided workflow
- 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:
- Project listing and creation
- Branch management
- Database operations
- Connection string generation
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:
- Follow the skill structure pattern
- Update
skills/add-neon-docs/skill-knowledge-map.jsonif adding knowledge files - Reference the
add-neon-docsskill at the end of your SKILL.md - 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:
- Load metadata - Read skill information from
skill-knowledge-map.json - Detect documentation file - Find
CLAUDE.md,AGENTS.md, or Cursor rules files - Ask permission - Show what will be added and where
- Add references - Insert URLs in a “Resources & References” section
- 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:
- “Add neon drizzle knowledge to my project”
- “Install neon serverless documentation”
- “Set up Neon best practices for my AI assistant”
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)