MuhammaraJS PDF Library

The @muhammara/wasm package is designed for environments where filesystem access or Node.js streams are unavailable, such as browsers or Web Workers. Unlike the native Node package, it provides a byte-first API.

Every completed writer or Recipe operation returns an owned Uint8Array. You can use this array directly with Blob, browser storage, or for uploads and downloads.

import { createMuhammaraWasm } from "@muhammara/wasm";

var muhammara = await createMuhammaraWasm();
var pdfBytes = muhammara.createBlankPdf(595, 842);
var pdf = new Blob([pdfBytes], { type: "application/pdf" });

In v7, calling Recipe.endPage() clears the completed page and its content context. You cannot continue drawing on the previous page without re-establishing context.

To add content to a new page, call recipe.createPage() or recipe.editPage() after endPage().

To add content to an existing page: Use recipe.editPage(pageNumber) where pageNumber is one-based.

recipe.endPage();

// Create another page before adding more content.
recipe.createPage("letter");
recipe.text("Next page", 72, 72);

// OR: Modify an existing page
recipe.endPage();
recipe.editPage(2);
recipe.text("More content", 72, 72);

When using @muhammara/wasm in a browser environment, follow these best practices for performance and security:

• Use Web Workers: PDF parsing, font loading, and image decoding are CPU and memory-intensive. Run untrusted documents in a terminable Worker rather than the main thread to avoid freezing the UI.
• Input/Output Types: The library uses Uint8Array, ArrayBuffer slices, Blob, and File for inputs.
• Memory Management: Explicitly call end() or dispose() for object owners, unregister assets, call disposeAssets(), and revoke object URLs to prevent memory leaks.
• Unsupported Features: The WASM version does not support PDF 2.0, AES-256 encryption, continuation state files, filesystem paths, Node streams, plugins, or Node EventEmitter hooks.

Depending on your environment, you should choose one of the following packages:

1. @muhammara/native: Use this for standard Node.js environments where prebuilt binaries are available. It is a smaller package.
2. @muhammara/native-with-source: Use this if a compatible prebuilt binary is unavailable, if you need to compile the addon locally, or if you are rebuilding the addon for Electron.

Both packages share the same @muhammara/native-core runtime and expose the exact same API.

When fitting an image to explicit width and height dimensions, you can use the keepAspectRatio option to ensure the image is not distorted.

// Example of using keepAspectRatio (implied usage)
pdfDoc
  .editPage(1)
  .image("photo.jpg", "center", "center", {
    width: 300,
    height: 300,
    keepAspectRatio: true
  })
  .endPage()
  .endPDF();

The @muhammara/wasm package compiles its WebAssembly target from C and C++ source code located in packages/native-with-source/src/deps/. These dependencies are vendored (manually included) and are not managed by npm or other package managers.

Key Security Note: The WebAssembly build deliberately excludes OpenSSL-backed encryption because browsers lack an OpenSSL runtime. Consequently, OpenSSL-backed encryption is not available in this target.

A PDFWriter can be initialized using createWriter(), createWriterToModify(), or createWriterToContinue().

Lifecycle Rules:

• Termination: Once end() or shutdown() is called, the writer is retired. Any subsequent calls to stateful methods (like page creation or writing) will throw Error("PDF writer has ended").
• Idempotency: Calling end() multiple times is safe; it will return the writer without attempting to finalize again.
• Cleanup: Ensure all drawing operations are complete and all borrowed contexts (fonts, parsers, file wrappers) are consumed before ending the writer.
• Resuming: If you need to perform more work after a writer has ended, you must start a new writer or use createWriterToContinue() with a saved continuation state.

When drawing shapes, the anchor point depends on the shape type:

• Rectangles: Use a top-left anchor point.
• Circles and Ellipses: Use center coordinates.

MuhammaraJS provides different packages depending on your runtime environment and whether you need prebuilt binaries or source compilation.

• @muhammara/native: Best for most Node.js applications. It provides a small package with prebuilt native binaries.
• @muhammara/native-with-source: Use this for local native builds, Electron rebuilds, or if your platform does not have a matching prebuilt binary for @muhammara/native.
• @muhammara/wasm: Use this for Browsers, Web Workers, and other byte-oriented WebAssembly environments where native Node.js addons or filesystem APIs are unavailable.

Note on API differences: The Native packages work with Node.js paths, streams, and buffers. The Wasm package is byte-first and uses Uint8Array, ArrayBuffer, Blob, and File.