How to use MuPDF in a Cloudflare Worker for PDF transformations?

[yuriyward]

Hi everyone,

I’m trying to create a Cloudflare Worker that uses MuPDF for PDF transformations. However, I’m running into some issues when trying to import and use the MuPDF library. Here’s what I’ve tried so far:

Using import:

import { Document } from "mupdf";

This results in the following error:

Uncaught Error: not compiled for this environment (did you build to HTML and try to run it not on the web, or set ENVIRONMENT to something - like node - and run it someplace else - like on the web?)

Using require:

const mupdf = require("mupdf");

This results in the following error:

✘ [ERROR] This require call is not allowed because the imported file "node_modules/mupdf/dist/mupdf.js" contains a top-level await

The top-level await in "node_modules/mupdf/dist/mupdf.js" is here:

node_modules/mupdf/dist/mupdf.js:24:17:
24 │ const libmupdf = await libmupdf_wasm();

Questions:

1. Is it possible to use MuPDF in a Cloudflare Worker? If so, how can I properly import and use it?
2. Are there any specific configurations or build steps I need to follow to make MuPDF work in this environment?
3. Are there any alternative libraries or approaches you would recommend for PDF transformations in a Cloudflare Worker?

Additional Context:

• I’m using the latest version of MuPDF.
• My Cloudflare Worker is set up with Wrangler.
• I’m relatively new to Cloudflare Workers and working with WASM in this context.

Any help or guidance would be greatly appreciated! Thank you in advance.

---

Steps to Reproduce:

1. Set up a new Cloudflare Worker project using Wrangler.
2. Install MuPDF using npm:

   npm install mupdf

3. Attempt to import MuPDF in the worker script using either import or require.

[ccxvii]

Using import should work, but the error message indicates you've run the mupdf distribution through a "bundler" software. These bundlers break the code, so you should NOT run the mupdf.js source through the bundlers.

Using require is not supported -- the mupdf.js library is only available as an ESM module.

[yuriyward]

Thanks for the clarification! I understand that MuPDF should not be processed by a bundler.
However, I tried with "bundler" and "node" moduleResolution, but it seems that Wrangler (the Cloudflare Workers CLI tool) still processes the MuPDF library in a way that breaks it.

Here’s my TypeScript configuration:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "lib": [
      "ES2022"
    ],
    "types": [
        "@cloudflare/workers-types/2023-07-01",
        "bun-types"
    ],
    "jsx": "react-jsx",
    "jsxImportSource": "hono/jsx"
  }
}

Reproduction:

It's pretty easy to reproduce the issue:

1. Follow the Cloudflare Workers Get Started Guide.
2. Install MuPDF:

   npm install mupdf

3. Add the import statement to your Worker script and add some simple function with it:

   import { Document } from "mupdf";

4. Run wrangler dev and observe the error.

The issue is that Cloudflare Workers run in a V8 JavaScript isolate environment which is different from Node.js or browser environments.

I added to wrangler setup also flag that should enable partially compatibility with node

 {
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "cf-convert-worker",
	"main": "src/index.ts",
	"compatibility_date": "2025-02-24",
	"observability": {
		"enabled": true
	},
  "compatibility_flags": [
    "nodejs_compat",
  ]
}

But this doesn't provide full Node.js compatibility for all libraries

---

Are there any specific configurations or workarounds I can use to make MuPDF work in a Cloudflare Worker?
If MuPDF is not compatible with Cloudflare Workers, are there any alternative libraries you would recommend for PDF transformations in this environment?

Thanks again for your help! I really appreciate any guidance you can provide.

[defidefi5]

Also running into an error on Cloudflare Workers runtime:
Assertion failed: shell environment detected but not enabled at build time. Add 'shell' to -sENVIRONMENT to enable.

[defidefi5]

I think I got past my error message above. Problem/solution was this:

Inside a Cloudflare Worker importScripts is not available (it was removed in Jan 2024) so
ENVIRONMENT_IS_WORKER is false.
window is also absent, so the glue code thinks it is running in “shell” and immediately aborts with the assertion you saw  .

The one-line fix: pretend we are a Web Worker

Before you load an Emscripten bundle, poly-fill the missing features:

// shim-emscripten-env.ts
export function patchEmscriptenEnv() {
  // Convince Emscripten it is in a Worker.
  if (typeof globalThis.importScripts === "undefined") {
    globalThis.importScripts = () => {}; // no-op stub
  }
  // A few builds touch self.location.href
  if (typeof globalThis.location === "undefined") {
    // minimal dummy object that satisfies `.href` reads
    globalThis.location = { href: "cf://worker" } as unknown as Location;
  }
}

And then import it and call it prior to mupdf. Tbh, I only tested this mock function with pdfium so far, but both mupdf and pdfium were giving me this same error message on Cloudflare Pages, so I think this will solve it for mupdf too:

patchEmscriptenEnv();

Now I can see new errors 🎉 that are related to generally getting a wasm package running on Cloudflare Pages. I've tried endless approaches today, but no luck yet. If anyone knows, would be grateful.