Neon Toolkit Skill

Automates creation, management, and cleanup of temporary Neon databases using the Neon Toolkit.

When to Use

• Creating fresh databases for each test run

• Spinning up databases in CI/CD pipelines

• Building isolated development environments

• Rapid prototyping without manual setup

Not recommended for: Production databases, shared team environments, local-only development (use Docker), or free tier accounts (requires paid projects).

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-toolkit.mdc in project root for comprehensive guidelines including:

• Core concepts (Organization, Project, Branch, Endpoint)

• Installation and authentication setup

• Database lifecycle management patterns

• API client usage examples

• Error handling strategies

Quick Setup

Installation

npm install @neondatabase/toolkit

Basic Usage

import { NeonToolkit } from '@neondatabase/toolkit';

const neon = new NeonToolkit({ apiKey: process.env.NEON_API_KEY! });

// Create ephemeral database const db = await neon.createEphemeralDatabase(); console.log(Database URL: ${db.url});

// Use the database...

// Cleanup await db.delete();

Templates & Scripts

• templates/toolkit-workflow.ts

• Complete ephemeral database workflow

• scripts/create-ephemeral-db.ts

• Create a temporary database

• scripts/destroy-ephemeral-db.ts

• Clean up ephemeral database

Common Use Cases

Testing

const db = await neon.createEphemeralDatabase(); // Run tests with fresh database await db.delete();

CI/CD Integration

export NEON_API_KEY=${{ secrets.NEON_API_KEY }} npm test # Uses ephemeral database

Related Skills

• neon-serverless - For connecting to databases

• neon-drizzle - For schema and migrations

Want best practices in your project? Run neon-plugin:add-neon-docs with parameter SKILL_NAME="neon-toolkit" to add reference links.