vite-plugin-db

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}POSTGRES_CLAIM_URL	Claim URL (valid for 72 hours) 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

What if I already have a DATABASE_URL env var?

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

Is this safe to run on CI when building for production?

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

Can I use this with other frameworks?

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.