Document bundling with esbuild

[skyqrose]

the problem

I'm setting up PGLite on a project that uses esbuild to bundle. I tried to start it like this:

import { PGlite } from "@electric-sql/pglite";
document.addEventListener("DOMContentLoaded", () => {
  PGlite.create();
});

But I get this error about new URL("./postgres.wasm") at this line in startWasmDownload:

Uncaught (in promise) TypeError: URL constructor: ./postgres.wasm is not a valid URL.
    Er utils.ts:17
    K_ pglite.ts:198
    I_2 pglite.ts:123
    create pglite.ts:165

And two of these errors about new URL("./postgres.data") at this line in getFsBundle:

Uncaught (in promise) TypeError: URL constructor: ./postgres.data is not a valid URL.
    Pr utils.ts:70
    K_ pglite.ts:209
    I_2 pglite.ts:123
    create pglite.ts:165

My esbuild process is dead simple, just esbuild src/index.tsx --bundle --outfile=build/index.js.

I'm using pglite version 0.2.15

what to do

I think this is either a bug or missing feature in esbuild, not this project.

But I'm posting this issue here because:

• PGLite could change to an approach that esbuild supports.
• PGLite could add documentation recommending an approach for people using esbuild.
  • Those docs said "If you come across any issues with PGlite and a specific bundler, please open an issue"
• So that other people who run into the same problem can find this issue and learn from my struggles.

workaround

My workaround was to pass in the files manually

  const [wasmModule, fsBundle] = await Promise.all([
    WebAssembly.compileStreaming(fetch("/postgres.wasm")),
    fetch("/postgres.data").then((response) => response.blob()),
  ]);
  const db = await PGlite.create({
    wasmModule,
    fsBundle,
  });

I also had to copy those two files from node_modules/@electric-sql/pglite/dist/ to my build directory so my webserver would serve them.

Alternatively, there are also workarounds and plugins based around helping esbuild handle this case, but I haven't tried them.

[copiltembel]

Hi @skyqrose, thank you for the issue report!

PGLite could change to an approach that esbuild supports.

Do you know of an approach that esbuild supports but doesn't break other bundlers?

[skyqrose]

unfortunately no, I don't know much about how bundlers work, so can't be helpful in finding a solution there.

[jihchi]

Thank you @skyqrose for sharing and workaround. You've saved my day.

For anyone needing a workaround without a self-hosted web service, public CDNs like jsDeliver or unpkg can be used.

For example:

const cdn = 'https://cdn.jsdelivr.net/npm/@electric-sql/pglite@0.2.15';

const [wasmModule, fsBundle] = await Promise.all([
  WebAssembly.compileStreaming(fetch(`${cdn}/dist/postgres.wasm`)),
  fetch(`${cdn}/dist/postgres.data`).then((response) => response.blob()),
]);

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

[samwillis]

Unfortunately it seems that esbuild doesn't follow the pattern that other bundlers have settled on interpreting new URL('./relative/path/to/file', import.meta.url) as a way to find files to bundle, then rewrite that for the new bundle.

I looks like there are a few options linked above. We should add docs to the bundlers page showing how to enable this new URL('./relative/path/to/file', import.meta.url) pattern or work around it with the wasmModule option.