1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95# 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
// 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=<free port>`
- `PGDATABASE=<db name>`
- `PGDATA=<data directory>`
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
seedModule?: string
verbose?: boolean
logFile?: string
}
```
- `dbPath`: Postgres data directory. Default: `${os.tmpdir()}/vite-postgres/<root>-<hash>`
- `dbName`: Database name. Default: Vite root folder name
- `seedModule`: Module path (relative to Vite root) to execute after the DB is ready
- `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.
- 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`.