GhostPDL (Ghostscript) WASM built with Emscripten

This package provides a WebAssembly (WASM) build of GhostPDL (Ghostscript). It is built with Emscripten on GitHub Actions.

Traceability

This project prioritizes supply‑chain traceability and publishes artifacts with npm Package Provenance.

Provenance provides a cryptographically verifiable link from the published package back to:

• the source repository and the exact commit that produced it,
• the GitHub Actions workflow/job that built and published it.

To verify a release, open the npm package page for that version and view its Provenance. Confirm that it references this repository (okathira/ghostpdl-wasm), the exact commit SHA that published the version, and the GitHub Actions workflow defined in .github/workflows/release.yml.

Installation

npm install @okathira/ghostpdl-wasm

Example Usage

The Emscripten FS and callMain APIs are exported.

Basic usage

import loadWASM from "@okathira/ghostpdl-wasm";

const run = async () => {
  // Load WASM
  const Module = await loadWASM();

  // Read the source PDF file
  const buffer = await fetch("./example.pdf").then((res) => res.arrayBuffer());
  Module.FS.writeFile("example.pdf", new Uint8Array(buffer));

  // Convert PDF to PDF (example settings)
  Module.callMain([
    "-sDEVICE=pdfwrite",
    "-dPDFSETTINGS=/ebook",
    "-dNOPAUSE",
    "-dBATCH",
    "-sOutputFile=example_output.pdf",
    "example.pdf",
  ]);

  // Read the output PDF file
  const output = Module.FS.readFile("example_output.pdf", {
    encoding: "binary",
  });

  // Create a downloadable file
  const file = new File([output], "example_output.pdf", {
    type: "application/pdf",
  });

  // Create a download button
  const a = document.createElement("a");
  a.href = URL.createObjectURL(file);
  a.download = file.name;
  a.innerText = "Download File";
  document.body.appendChild(a);

  // List files in the root directory
  console.log(Module.FS.readdir("/"));
};

run();

Build artifacts can be imported directly

import wasm from "@okathira/ghostpdl-wasm/gs.wasm";
import js from "@okathira/ghostpdl-wasm/gs.js"; // the same as `import loadWASM from "@okathira/ghostpdl-wasm";`

TypeScript support

Type definitions ship with the package. Importing @okathira/ghostpdl-wasm provides typed factory and module helpers, including the virtual filesystem (Module.FS) and Module.callMain entry point.

The default export matches the factory emitted by Emscripten (Module), and the bundled declarations extend EmscriptenModule from @types/emscripten to surface GhostscriptModule and GhostscriptModuleFactory for reuse in your own typings when needed.

Runtime notes

The published artifacts are built with the following key options:

• EM_LD_FLAGS: -sFILESYSTEM=1 -sEXPORTED_RUNTIME_METHODS=FS,callMain -sMODULARIZE=1 -sEXPORT_ES6=1 -sINVOKE_RUN=0 -sALLOW_MEMORY_GROWTH=1 -sBINARYEN_EXTRA_PASSES=...
• GS_CONFIGURE_FLAGS: --disable-contrib --disable-cups --disable-dbus --disable-fontconfig --disable-gtk --without-libpaper --without-libidn --without-pdftoraster --without-ijs --without-x --with-drivers=BMP,JPEG,PNG,PS,TIFF

In short, Module.FS and Module.callMain are preserved for the usage shown above, and Ghostscript drivers are limited to the listed file-output devices.

How to test locally

This repository uses a git submodule for GhostPDL.

Build with Docker on Windows

npm run build:docker-cmd

Use as a npm package

To verify the package locally before publishing to npm, install it from the source directory into another project.

1. Register the package globally with npm link:

   npm link

   This makes @okathira/ghostpdl-wasm available as a global link.

2. In the project where you want to test the package, link it as a dependency:

   npm link @okathira/ghostpdl-wasm

   To remove the link later, run npm unlink @okathira/ghostpdl-wasm in the consumer project and npm unlink in this repository if needed.

After linking, import @okathira/ghostpdl-wasm in the consumer project as you would with the published package.

TODO

• [x] Optimize artifacts
  • [x] ghostscript build options
  • [x] emscripten build options
  • [x] Closure Compiler
• [ ] Auto-update dependencies on GitHub Actions
• [x] Add type definitions
• [ ] Optimize build process (e.g. remove apt-get install)

License

ghostpdl-wasm (this WASM package)

This package is licensed under the AGPLv3. See LICENSE.

ghostpdl (original Ghostscript)

GhostPDL/Ghostscript is licensed under the AGPLv3. See the original repository: https://github.com/ArtifexSoftware/ghostpdl