vite-plugin-db

This Vite plugin instantly provisions a Postgres instance (via Neon) and injects the connection string into your .env file, so you can start developing immediately.

Note: This package was previously named @neondatabase/vite-plugin-postgres. The old package is now deprecated. If you're upgrading, simply replace it with vite-plugin-db in your imports and package.json.

How it works

• On first vite dev, the plugin checks for a DATABASE_URL (or your configured key) in your .env.
• If not found, it creates a claimable Neon database and writes the connection string to your .env.
• The plugin is a noop in production builds.

Installation

| Package Manager | Command | | --------------- | -------------------------------- | | npm | npm add -D vite-plugin-db | | pnpm | pnpm add -D vite-plugin-db | | yarn | yarn add -D vite-plugin-db | | bun | bun add -D vite-plugin-db | | deno | deno add -D npm:vite-plugin-db |

Usage

⚠️ BREAKING CHANGE in v3.0.0: The referrer option is now required.

Add the plugin as the first entry in your Vite config:

import { postgres } from "vite-plugin-db";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
	plugins: [
		postgres({
			referrer: "github:username/repo-name", // REQUIRED
		}),
		react(),
	],
});

Configuration

You can pass an options object to customize the .env file path, the environment variable name, and database seeding:

postgres({
	referrer: "your-app-name", // REQUIRED - for tracking and affiliates
	env: ".env.local", // Path to your .env file (default: ".env")
	envKey: "DATABASE_URL", // Name of the env variable (default: "DATABASE_URL")
	envPrefix: "VITE_", // Prefix for public env vars (default: "VITE_")
	settings: {
		logicalReplication: false, // Enable logical replication (default: false)
	},
	seed: {
		type: "sql-script",
		path: "./schema.sql", // Path to SQL file to execute after database creation
	},
});

| Option | Type | Description | Required | Default | | ----------- | ------ | --------------------------------------- | -------- | -------------- | | referrer | string | Referrer identifier for tracking | ✅ Yes | - | | env | string | Path to the .env file | No | .env | | envKey | string | Name of the environment variable | No | DATABASE_URL | | envPrefix | string | Prefix for public environment variables | No | VITE_ | | settings | object | Database configuration settings | No | - | | seed | object | Configuration for seeding the database | No | - |

settings Options

| Property | Type | Description | Default | | ------------------- | ------- | -------------------------- | ------- | | logicalReplication| boolean | Enable logical replication | false |

seed Options

| Property | Type | Description | Default | | -------- | ------ | ----------------------------------------------- | ------- | | type | string | Type of seeding (currently only "sql-script") | - | | path | string | Path to SQL file to execute after creation | - |

What gets written

The plugin writes the following environment variables to your .env:

| Variable | Description | | -------------------------------- | -------------------------------------------------------- | | DATABASE_URL | The pooler connection string (default connection) | | DATABASE_URL_DIRECT | The direct connection string | | {envPrefix}INSTAGRES_CLAIM_URL | Claim URL (valid for 7 days) to take ownership of the DB |

Note: The pooler connection is now the default for DATABASE_URL (as of the latest version). The pooler provides connection pooling and is recommended for most use cases, especially serverless environments.

If seed is configured, the specified SQL script will be executed after database creation.

Type Definitions

interface PostgresPluginOptions {
	referrer: string; // Required - Referrer identifier for tracking
	env?: string; // Path to the .env file
	envKey?: string; // Name of the environment variable
	envPrefix?: string; // Prefix for public environment variables
	settings?: {
		logicalReplication?: boolean; // Enable logical replication (default: false)
	};
	seed?: {
		type: "sql-script";
		path: string;
	};
}

FAQ

The plugin will not overwrite it. Remove the variable if you want to generate a new Neon database.

The plugin is a noop in production mode (vite build), so it won't create databases or modify your .env in CI.

Yes, this plugin is framework-agnostic. The example uses React, but you can use it with any Vite-compatible framework.

Advanced

If you want to generate claimable databases outside of Vite, use the get-db library directly.

See documentation on Neon for more.