vite-postgres

Vite dev-only plugin that bootstraps and runs a local PostgreSQL server for your app.

- Runs on vite dev only (apply: 'serve')
- Uses your system Postgres binaries (initdb, postgres, createdb, pg_isready)
- Picks a free port automatically and injects Postgres env vars for your app

Install

``sh
pnpm add -D vite-postgres
`

Usage

vite.config.ts

`ts
import { defineConfig } from 'vite'
import postgres from 'vite-postgres'

export default defineConfig({
plugins: [
postgres({
// dbPath: '.postgres', // persist in-repo (optional)
// dbName: 'myapp', // defaults to Vite root folder name
// user: { name: 'dev', password: 'devpass' }, // optional superuser credentials
// seedModule: 'src/seed.ts' // optional, runs after DB is ready
// verbose: true, // optional, inherit Postgres logs in Vite output
// logFile: 'postgres.log', // optional, relative to Vite root (ignored if verbose)
}),
],
})
`

Then start Vite. Your app can connect using the injected env:

- PGHOST=127.0.0.1
- PGPORT=
- PGDATABASE=
- PGDATA=
- PGUSER=
- PGPASSWORD=

Example connection strings:

`sh
psql "host=$PGHOST port=$PGPORT dbname=$PGDATABASE"


or (common default)


psql "postgresql://127.0.0.1:$PGPORT/$PGDATABASE"
`

Options

`ts
export interface VitePostgresOptions {
dbPath?: string
dbName?: string
user?: { name: string; password: string }
seedModule?: string
strictPort?: number
verbose?: boolean
logFile?: string
}
`

- dbPath: Postgres data directory. Default: ${os.tmpdir()}/vite-postgres/-
- dbName: Database name. Default: Vite root folder name
- user: Superuser credentials to create and expose via env vars. If unset, env vars default to OS username + "postgres" and no superuser is created.
- seedModule: Module path (relative to Vite root) to execute after the DB is ready
- strictPort: Force Postgres to bind to this port and wait if it's unavailable.
- verbose: Inherit Postgres stdout/stderr in the Vite process. Default: false (logs go to a file)
- logFile: Where to write Postgres logs (relative to Vite root). Default: ${PGDATA}/postgres.log (ignored if verbose)

Seeding

If seedModule is set, it’s loaded via server.ssrLoadModule(...) after:

1. initdb (only if PG_VERSION missing)
2. postgres started
3. pg_isready succeeds
4. createdb attempted (ignored if it already exists)

The module can be TS/ESM and can run whatever you want (migrations, seed data, etc).

Notes / behavior

- Auth is initialized with --auth=trust (no password). This is for local dev.
- A passworded superuser role is created (or updated) only when user is provided.
- Logs go to ${PGDATA}/postgres.log to keep Vite output clean (unless verbose is enabled).
- The Postgres process is terminated when Vite exits (SIGINT for fast shutdown).

Requirements

- PostgreSQL installed and on your PATH (initdb, postgres, createdb, pg_isready)
- Node compatible with Vite 7+

Troubleshooting

- Failed to initialize DB. Ensure "initdb" is in your PATH.: install Postgres (or add its bin/ directory to PATH).
- Port conflicts: the plugin chooses a free port each run; read process.env.PGPORT from your app instead of hard-coding 5432`.