Integrating dompdf.js in a Webpack Project

Webpack 5 changed how WebAssembly and resource modules are handled, and the changes line up precisely with what a WASM-bearing library like dompdf.js needs. Wasm modules now load asynchronously through import, images and fonts are managed uniformly by asset modules, and workers have first-class bundling support. dompdf.js itself ships as ESM/CJS dual format, its Rust/WASM core initializes asynchronously, and its worker pipeline must be bundled correctly — three requirements that map one-to-one onto Webpack 5's new mechanisms. Get the configuration right and integration is uneventful; get it wrong and you face a cascade of symptoms: wasm load-order errors, 404 asset paths, and workers that fail to construct. This guide proceeds in integration order. It starts with the mechanics of how Webpack 5 treats wasm and assets, then presents a minimal, runnable webpack.config.js covering experiments.asyncWebAssembly and an asset/resource rule for wasm. From there it covers basic integration and the export-module pattern, code splitting and lazy loading with dynamic import, worker bundling and CJS/ESM compatibility, content hashing and cache strategy, and finishes with the troubleshooting questions that resolve most real-world failures. By the end, a Webpack team should be able to land PDF export in an afternoon and not revisit the build configuration again. Each section of the guide maps to a real failure mode, so the material doubles as a diagnostic reference: when an error appears, the relevant section explains both the mechanism and the fix. The code examples are complete enough to run, and the acceptance checks at the end give a team a concrete definition of done for the integration.

How Webpack 5 Handles WASM and Assets

Webpack 5 introduced experiments.asyncWebAssembly, under which wasm modules load through asynchronous import and synchronous initialization is no longer supported. For dompdf.js this means the library's internal wasm loading must be asynchronous — which it is by design — and the project must enable the experiment flag and build for a runtime that supports asynchronous module loading. Both conditions are satisfied by the configuration shown later in this guide; the important mental model is that wasm is no longer a side file but a module with import semantics.

On the asset side, Webpack 5 replaced the old file-loader and url-loader with asset modules. Resources below a configured threshold are inlined as data URLs automatically; larger ones are emitted as separate files. wasm, fonts, and images all fall under these rules, so once you declare an asset/resource rule for .wasm, every wasm reference inside the library is resolved and emitted by the build automatically. The loader-plugin ecosystem that used to be required is simply gone.

Understanding these two mechanisms makes the integration recipe obvious: enable the asyncWebAssembly experiment, add an asset/resource rule for wasm, and let the built-in worker support handle worker files. Three configuration entries cover the three critical paths, and everything else is ordinary import usage in business code. Teams that grasp the mechanisms can debug new errors; teams that only copy configuration cannot.

Legacy projects deserve a warning: the experiment flag applies to modules using the new syntax, and any remaining synchronous wasm loading from older patterns must be migrated to import-based loading first. Mixing both mechanisms produces confusing interleaving errors. Migrate module by module, verify each wasm module loads via import, and clear the build warnings before merging — a clean build log is the acceptance criterion.

Installation and Basic Integration

Install the dependency with npm install dompdf.js, then import { DomPDF } from 'dompdf.js' in business code. addPage accepts an HTML string or a DOM element and builds the document; save triggers the download with the given filename. Webpack resolves the dependency graph and emits all required assets, so developers never need to know where the wasm file ended up — that invisibility is precisely the sign that the configuration is correct.

Wrap the export in a dedicated module: the function receives HTML and a filename, constructs the PDF internally, and keeps business code decoupled from PDF internals. A single wrapper makes unit tests straightforward — call the function with synthetic HTML and assert on the outcome — and confines future optimizations such as worker dispatch or lazy loading to one file. This is the integration habit that pays for itself in every subsequent change.

addPage handles both content forms, and they can be mixed: pass an element for content already in the page, or a string for dynamically generated content. When passing elements, avoid mutating the source DOM during export; the snapshot reflects the page state at export time, so pinning the content before exporting produces deterministic results. This discipline also makes tests reproducible, because the input no longer depends on incidental page state.

Define an acceptance checklist for the integration: the build completes without warnings, the production bundle exports successfully, and the output matches the page layout. All three passing means configuration, code, and assets are sound; any failure isolates to one of those three layers, which keeps debugging fast and bounded.

A practical consequence of async wasm is that the export path becomes asynchronous by nature: dynamic import is not just an optimization but the natural way to load the library. Plan for that asynchrony in the UI — a loading state on the export button — and the code structure follows the runtime model instead of fighting it.

Code Example: The Complete webpack.config.js

This is a minimal, runnable webpack.config.js for dompdf.js: experiments.asyncWebAssembly enables wasm module support, the module.rules entry declares .wasm files as asset/resource so they are emitted as standalone files, and output.filename uses content hashes for cacheable artifacts. Copy it into a project, install the dependency, and the basic export path works; everything else in the config can follow the project's existing conventions.

Each entry has a specific purpose. asyncWebAssembly is the prerequisite for importing wasm modules. The asset/resource rule for .wasm emits wasm as a file with a hashed name, which pairs with long-lived cache headers. Adding .mjs to resolve.extensions lets Webpack prefer the library's ESM entry when both formats are available, which enables tree shaking. TypeScript projects also need a module declaration for .wasm files, or the compiler reports module-not-found for imports that are perfectly valid at build time.

For development, webpack-dev-server serves wasm and worker files from its in-memory filesystem, so path problems rarely appear in dev; they concentrate in the production build and deployment layer. Knowing this asymmetry saves debugging time: when a path issue surfaces, skip the dev environment and validate directly against the production bundle, where the discrepancy between requested and actual paths is visible in the network panel.

If the project's runtime must support older browsers, check the asyncWebAssembly baseline. Asynchronous wasm loading requires a modern runtime; for legacy targets, consider serving the export feature behind a capability check with a documented fallback, rather than degrading the whole application's build target for one feature.

// webpack.config.js
const path = require('path');

module.exports = {
  mode: 'production',
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash].js',
  },
  experiments: {
    asyncWebAssembly: true,
  },
  module: {
    rules: [
      {
        test: /\.wasm$/,
        type: 'asset/resource',
      },
    ],
  },
  resolve: {
    extensions: ['.js', '.mjs', '.wasm'],
  },
};

Code Example: Code Splitting and Lazy Loading

dompdf.js plus its WASM core carries real weight, and shipping it in the main bundle inflates first load. The standard remedy is dynamic import: the export module is loaded only when the user first clicks export, Webpack splits it into its own chunk, and the magic comment names the chunk for predictable caching. The main bundle stays lean, and the export payload is fetched exactly once, at the moment it is needed.

The benefits are doubled. First-load bundle size drops, moving the export library's cost off the critical path. And because the chunk is cached after the first load, the second export is effectively free — an outcome that matters for back-office systems where users export only occasionally but must not pay for the capability on every visit.

One nuance: dynamic import only helps if the export path is not imported eagerly elsewhere. Keep the export module out of any statically imported module graph; a single stray static import reattaches the chunk to the main bundle and silently negates the optimization. A quick way to verify is inspecting the production bundle — the dompdf chunk should appear as a separate file loaded on demand, visible in the network panel only after the first export click.

Multiple export entry points can share a chunk name to merge into one payload, and the contenthash filename ensures browsers fetch the new version automatically after any code change. Standardize the lazy-loading pattern across the team so every export-related module follows the same rule; consistency makes the bundle behavior predictable and the optimization durable.

// src/export.js — the export module
import { DomPDF } from 'dompdf.js';

export function exportPdf(html, filename) {
  const pdf = new DomPDF();
  pdf.addPage(html, { format: 'A4' });
  pdf.save(filename || 'output.pdf');
}

// src/index.js — load on demand when the user clicks export
async function handleExport() {
  const { exportPdf } = await import(
    /* webpackChunkName: "dompdf" */ './export'
  );
  exportPdf(document.querySelector('#content').innerHTML, 'report.pdf');
}

document.querySelector('#export-btn').addEventListener('click', handleExport);

Worker Bundling and CJS/ESM Compatibility

Webpack 5 bundles workers natively: new Worker(new URL('./worker.js', import.meta.url)) is recognized by the build, and the worker is emitted as a separate file with its own module graph. dompdf.js's internal worker pipeline benefits from this automatically — the module.rules configuration applies to the worker's assets as well — and custom export workers should use the same canonical form. String-based worker paths cannot be analyzed and silently bypass bundling, which is a common source of production-only failures.

On the format side, dompdf.js ships both ESM and CJS entries. Webpack prefers the ESM entry, which enables tree shaking of unused exports; legacy code using require('dompdf.js') continues to work without modification. During a migration, teams can integrate with require first and switch to import gradually — the two styles coexist without conflict, and the risk of a big-bang rewrite disappears.

Worker communication deserves a performance note: postMessage cloning cost scales with payload size, and an oversized snapshot can erase the worker's performance advantage. Trim snapshots before dispatch, strip irrelevant nodes, and prefer URL references over inline data URLs for images. Message volume dropping by an order of magnitude is realistic for image-heavy templates, and the worker pipeline's benefit is fully realized only when the messages it carries are lean.

If the project uses a custom web worker for export orchestration, keep worker files inside src so they participate in bundling, hashing, and caching. Workers placed in public bypass all of that: no content hash, no path rewriting, and a predictable source of stale-cache bugs after deployments.

Lazy loading also changes the first-export experience: the user's first click pays a short load time while the chunk downloads and the wasm initializes. Communicate that with a loading state, and consider prefetching the chunk when the export UI is first rendered, so the wait happens before the click rather than after it.

Content Hashing and Cache Strategy

Content hashing is what makes aggressive caching safe. With [contenthash] in the output filename, any code change produces a new filename, so browsers can cache assets indefinitely and still receive updates automatically. The same principle applies to the emitted wasm and worker files: serve them with long-lived cache headers and immutable filenames, and the export pipeline gains both speed and correctness — repeat users load everything from cache, and deployments invalidate precisely the files that changed.

Cache strategy has a failure mode of its own: a stale service worker or proxy can keep serving an old wasm against a new bundle, producing rendering discrepancies that reproduce nowhere in testing. When a production-only export issue appears after a deployment, force-refresh verification and checking the served asset versions are the first diagnostic steps. Hashed filenames usually resolve the underlying staleness permanently.

If assets and the application are served from different hosts or CDNs, verify the cross-origin headers and align the asset host's cache policy with the release cycle. Document the asset topology in the deployment runbook — when the inevitable incident happens, the runbook converts a fire drill into a checklist, and the time-to-resolution shrinks accordingly.

Finally, treat the cache configuration as part of the acceptance checklist. After every release, confirm in the network panel that the new hashed assets are requested and the old ones are not. This two-minute check catches misconfigured headers and proxy interference before they reach users, which is exactly the class of bug that otherwise surfaces as mysterious production-only failures.

When both formats are present in one project — a legacy require here, an import there — Webpack resolves each consistently, and the dual-format support means neither side needs conversion. The only rule worth enforcing is to standardize on one form in new code, so the codebase converges over time instead of accumulating mixed styles.

Troubleshooting Common Errors

Q: The build reports 'WebAssembly module is included in initial chunk'? A: This is Webpack telling you the wasm landed in the main bundle, which can hurt first load. Convert the export path to dynamic import so dompdf.js and its wasm move into a separate chunk; the warning disappears and first-load size improves in one change.

Q: wasm 404 or cross-origin load failure at runtime? A: Check output.publicPath — when deployed under a sub-path, it must match the live path — and confirm the server returns correct CORS headers for wasm requests. Asset path issues are best debugged in the network panel: the 404 URL points directly at the mismatch, and tracing its reference chain finds the configuration that produced it.

Q: Intermittent export failures in production? A: Suspect caching first: confirm the bundle uses content hashes, and that wasm and worker files are served under a consistent cache policy. After a version upgrade, force-refresh and verify the new assets are fetched; if old hashes still appear in the network panel, a proxy or service worker is the culprit.

Q: Export works in dev but not in the production bundle? A: Compare the two environments' asset URLs side by side. Dev serves from memory with no hashing; production serves hashed files from disk. A path that resolves in dev can break in production if it was hard-coded. Replace hard-coded paths with relative references or imports, and the two environments converge. Run the dev-versus-production export check once after configuration, and this class of bug stops recurring.

The same troubleshooting order applies to upgrades: after bumping dompdf.js, rerun the dev-versus-production export check before merging, so version-related regressions surface in the review instead of in production. A two-minute verification after every upgrade keeps the export path trustworthy without any permanent monitoring burden.