Advanced
Explicit imports: #pglite/client
Everything the client side auto-imports is also exported by #pglite/client:
import {
definePGliteClientConfig,
pglite,
useLiveIncrementalQuery,
useLiveQuery,
usePGlite,
} from '#pglite/client'
import type { PGliteClientConfig, PGliteClientInstanceFor } from '#pglite/client'
pglite is the provider behind usePGlite(), with the same use() / instance / close() as on the server.
Data directories
dataDir decides where the browser keeps the data:
dataDir | Storage | Notes |
|---|---|---|
unset or memory:// | memory | Gone on reload. |
idb://<name> | IndexedDB | Persistent, widely supported. One name per app. |
opfs-ahp://<name> | Origin Private File System | Persistent and faster; workers only, which is where it runs here. |
Set it in the config file, or in nuxt.config.ts under pglite.client.options.dataDir when it does not depend on code. See PGlite's filesystems for the trade-offs.
The worker and tabs
The instance is a PGliteWorker: every tab of your app starts the worker, one of them is elected to run the database, and the others forward their queries to it. When that tab closes, another one takes over. You do not have to do anything for this; it is why init runs in each tab and should be repeatable.
extensions load inside the worker. clientExtensions load on each tab's main thread; their functions (pg.live.query(), …) are available on the instance usePGlite() returns.
Vite only
The worker, its WebAssembly and its data file are wired for Vite, Nuxt's default builder. Enabling the client side with webpack or Rspack fails at startup with a message saying so. The module also excludes PGlite and the packages your client config imports from Vite's dependency pre-bundling, which would otherwise separate PGlite from its WebAssembly.
Starting early
pglite.client.eager: true starts the worker as soon as the app loads, instead of on the first usePGlite(). Useful when the first query is on the critical path; wasteful when most pages never touch the database.