Bundler Support

Some bundlers require additional configuration to work with PGlite.

TIP

If you come across any issues with PGlite and a specific bundler, please open an issue, we'd also love any contributions to this bundler documentation if you're able to help out.

Vite

When using Vite, make sure to exclude pglite from dependency optimization using the optimizeDeps option inside vite.config.js:

import { defineConfig } from 'vite'

export default defineConfig({
  optimizeDeps: {
    exclude: ['@electric-sql/pglite'],
  },
})

Additional configuration for the Multi-tab Worker

When using the Multi-tab Worker, you might encounter errors during a production build related to workers being bundle in iife format, to resolve this modify the worker.format option in vite.config.js to 'es' (the default is 'iife')

import { defineConfig } from 'vite'

export default defineConfig({
  optimizeDeps: {
    exclude: ['@electric-sql/pglite'],
  },
  worker: {
    format: 'es',
  },
})

When importing the worker in your script, you can use the recommended ?worker import method from Vite:

import PGWorker from './worker.js?worker'

export const pglite = new PGliteWorker(
  new PGWorker({
    type: 'module',
      name: 'pglite-worker',
    }),
    {
      // ...your options here
    }
  },
)

esbuild

esbuild does not support new URL('./file', import.meta.url) pattern that PGlite uses to locate its WebAssembly and data files. This means the automatic file resolution won't work out of the box.

Workaround: manually provide wasmModule and fsBundle

1. Copy pglite.wasm and pglite.data from node_modules/@electric-sql/pglite/dist/ to your public/build directory so your web server can serve them.

2. Pass them manually when creating a PGlite instance:

import { PGlite } from '@electric-sql/pglite'

const [wasmModule, fsBundle] = await Promise.all([
  WebAssembly.compileStreaming(fetch('/pglite.wasm')),
  fetch('/pglite.data').then((response) => response.blob()),
])

const db = await PGlite.create({
  wasmModule,
  fsBundle,
})

Alternatively, you can use an esbuild plugin like @chialab/esbuild-plugin-meta-url to handle new URL() imports automatically.

Next.js

When using Next.js, make sure to add @electric-sql/pglite to the transpilePackages array in next.config.js:

const nextConfig = {
  swcMinify: false,
  transpilePackages: [
    '@electric-sql/pglite-react', // Optional
    '@electric-sql/pglite',
  ],
}

export default nextConfig