isomorphic-dompurify

isomorphic-dompurify wraps DOMPurify, the widely used XSS sanitizer, so it can run identically in Node.js and the browser. On the server it lazily creates a jsdom window to give DOMPurify the DOM it needs; in the browser it defers directly to the native dompurify build via a bundler browser field remap and conditional exports, so client bundles never pull in jsdom.

The library re-exports the full DOMPurify API — sanitize, hooks, config, and TypeScript types — plus a callable default export that doubles as a factory for binding a DOMPurify instance to a specific window, useful in tests or sandboxed environments. A clearWindow() helper lets long-running Node processes periodically release the internal jsdom window’s accumulated DOM state to avoid progressive memory growth.

What You Get

• Isomorphic sanitize() - the same API on server and client without branching your own code by environment
• Full DOMPurify API surface - sanitize, addHook/removeHook/removeAllHooks, setConfig/clearConfig, isValidAttribute, isSupported, version, and removed are all re-exported
• Callable factory default export - DOMPurify(window) binds a fresh instance to a specific window/JSDOM context, matching the underlying dompurify API
• clearWindow() memory helper - releases jsdom’s internal DOM state in long-running Node processes to prevent memory growth
• Full TypeScript type re-exports - Config, DOMPurify, and every hook type are re-exported so consumers don’t redeclare signatures

Common Use Cases

• Sanitizing user-generated HTML before storing or rendering it in a Next.js, Nuxt, or Astro app that server-renders
• Stripping XSS vectors (script tags, javascript: hrefs, inline event handlers) from CMS- or markdown-rendered content
• Building framework-agnostic sanitization utilities shared between SSR and CSR code paths
• Periodically clearing jsdom state in long-running Node services to prevent memory growth from repeated sanitize calls

Under The Hood

Architecture The package ships two nearly-symmetrical entry points — src/index.ts for Node and src/browser.ts for browsers — resolved automatically via package.json’s browser field remap and conditional exports (node vs default import/require), so consumers never branch on environment themselves. The Node entry lazily creates a module-level JSDOM window and DOMPurify instance, then wraps the DOMPurify handle in a JavaScript Proxy so that property access (DOMPurify.sanitize, addHook, etc.) always delegates to whichever purify instance is currently live — this is what lets clearWindow() swap out the jsdom window and DOMPurify instance in place without consumers re-importing anything. The browser entry skips jsdom entirely and just re-exports the native dompurify package directly, since a real DOM is already available. There’s no layering beyond this: the module is a single-file adapter with no internal abstractions, so what breaks if the core abstraction changes reduces to whether the Proxy’s get/apply traps stay in sync with whatever new methods a future dompurify release adds to its instance API.

Tech Stack Built in TypeScript targeting ES2020 with strict mode, bundled via tsup into dual CJS/ESM outputs (with .d.ts and .d.mts) for both the index and browser entries, externalizing dompurify and jsdom so they’re resolved from the consumer’s node_modules rather than bundled. Runtime dependencies are dompurify for the sanitizer itself and jsdom to supply a DOM on the server; devDependencies include Biome for linting and formatting, Vitest for testing, lefthook for git hooks, and pnpm as the package manager. The package pins a fairly recent Node engine range reflecting its jsdom major-version dependency, and CI (GitHub Actions) matrixes across multiple Node versions running lint, typecheck, build, and test on every push and pull request to master.

Code Quality Vitest tests cover all four public surfaces — default sanitize behavior, the callable factory export, a regression test pinned to a specific GitHub issue about jsdom node equality across separate JSDOM contexts, and a dedicated types test that exercises every re-exported hook and type against the runtime API to catch drift between the TypeScript declarations and dompurify’s actual behavior. Error handling is minimal by design since the module mostly delegates to dompurify and jsdom rather than implementing its own logic. Naming is consistent with the wrapped dompurify API so consumers transfer knowledge directly. Biome enforces lint and format rules, tsc —noEmit enforces type safety, and all checks run in CI across multiple Node versions — a small but well-guarded codebase.

API Design The library’s core ergonomic trick is a Proxy-wrapped default export that is simultaneously usable as a static-feeling object (DOMPurify.sanitize(…)) and as a factory (DOMPurify(window)) matching dompurify’s own callable-factory API, so switching between using the shared instance and binding to a specific window requires no import changes. Full re-export of DOMPurify’s hook and config types removes the need for consumers to redeclare signatures when typing hook callbacks, a small but real friction-reducer called out explicitly in the README. None of this is architecturally novel — isomorphic wrapper packages follow a well-worn shape the README itself credits as inspiration — but the clearWindow() memory-management escape hatch is a thoughtful, non-obvious addition addressing a real operational pain point that most naive DOMPurify-plus-jsdom wrappers don’t handle.