Isomorphic DOMPurify Wrapper

Common errors

• TS7016: Could not find a declaration file for module 'isomorphic-dompurify'

  cause Missing type declaration files for browser exports in version 3.7.0.
  fix Upgrade `isomorphic-dompurify` to version `3.7.1` or higher. If the issue persists with later versions, ensure your `tsconfig.json` module resolution settings are appropriate for your environment (e.g., `"moduleResolution": "bundler"` or `"node16"`).

Warnings

• breaking Minimum Node.js engine requirements have been updated across major versions. Ensure your environment meets the specified versions to avoid runtime issues.
  Fix: Upgrade Node.js to a version compatible with `^20.19.0`, `^22.13.0`, or `>=24.0.0`.
• gotcha The underlying DOMPurify library does not strictly follow Semantic Versioning, which means `isomorphic-dompurify` must release all DOMPurify updates as minor versions. This means minor version updates of `isomorphic-dompurify` could potentially contain breaking changes from DOMPurify itself.
  Fix: Always review the changelog when upgrading `isomorphic-dompurify` to a new minor version, especially concerning DOMPurify updates, as new features or behavior changes might be introduced without a major version bump.
• gotcha In long-running Node.js processes, the internal `jsdom` window used for server-side sanitization accumulates DOM state, leading to progressive memory growth and potential slowdowns if `clearWindow()` is not periodically called.
  Fix: Call `clearWindow()` periodically (e.g., after each request, or after a batch of sanitization operations) to release `jsdom` resources and prevent memory leaks.
• breaking Version 3.7.0 was published without `browser.d.ts` and `browser.d.mts` type declarations due to a build issue, causing TypeScript errors (e.g., `TS7016`) when resolving browser-specific exports.
  Fix: Upgrade to `isomorphic-dompurify@3.7.1` or newer to resolve missing type declaration issues in browser environments.

Install

• npm install isomorphic-dompurify npm
• yarn add isomorphic-dompurify yarn
• pnpm add isomorphic-dompurify pnpm

Imports

• DOMPurify
  wrong:

  const DOMPurify = require('isomorphic-dompurify');

  correct:

  import DOMPurify from 'isomorphic-dompurify';

  The default export `DOMPurify` is a pre-initialized instance of DOMPurify, or a factory function callable with a `Window` object (e.g., `DOMPurify(window)` or `DOMPurify(new JSDOM().window)`).
• sanitize
  wrong:

  const { sanitize } = require('isomorphic-dompurify');

  correct:

  import { sanitize } from 'isomorphic-dompurify';

  A named export for the `sanitize` method of the default DOMPurify instance, providing a direct way to clean HTML.
• clearWindow
  wrong:

  const { clearWindow } = require('isomorphic-dompurify');

  correct:

  import { clearWindow } from 'isomorphic-dompurify';

  A named export function specifically for server-side memory management. It releases the internally managed `jsdom` resources and creates a fresh window.

Quickstart

Demonstrates basic HTML sanitization, applying global configuration, and crucial server-side memory management using `clearWindow()`.

import DOMPurify, { sanitize, clearWindow } from "isomorphic-dompurify";

// 1. Basic sanitization: Works identically on client and server.
const dirtyHtml = `
  <img src="x" onerror="alert('XSS!')">
  <a href="javascript:alert('Evil!')">Click me</a>
  <p>Hello, <script>alert('world');</script> user!</p>
`;
const cleanHtml = sanitize(dirtyHtml, { USE_PROFILES: { html: true } });
console.log('Sanitized HTML:', cleanHtml);
// Expected: <img src="x"><a href="">Click me</a><p>Hello,  user!</p>

// 2. Using DOMPurify directly for configuration or hooks.
// On the client, this uses the browser's global window.
// On the server, it uses an internally managed JSDOM window.
DOMPurify.setConfig({ ALLOW_DATA_ATTR: false });
const cleanHtmlWithConfig = DOMPurify.sanitize('<div data-test="1">Test</div>');
console.log('Sanitized with config (no data attr):', cleanHtmlWithConfig);
// Expected: <div>Test</div>

// 3. Server-side memory management: Crucial for long-running Node.js processes.
// Calling clearWindow() releases JSDOM resources and creates a fresh internal window.
if (typeof window === 'undefined') { // Check if in Node.js environment
  clearWindow();
  console.log('Server-side JSDOM instance cleared for memory management.');
  // After clearing, DOMPurify and sanitize continue to work with a fresh instance.
  const reSanitized = sanitize('<span>Clean again.</span>');
  console.log('Re-sanitized after clearWindow:', reSanitized);
}