{"id":11109,"library":"isomorphic-dompurify","title":"Isomorphic DOMPurify Wrapper","description":"isomorphic-dompurify provides a universal wrapper for the DOMPurify library, enabling its seamless use across both client-side browser environments and server-side Node.js applications. Its primary function is to abstract away the environment-specific initialization details required by DOMPurify, which necessitates a DOM tree to operate. On the server, it leverages `jsdom` to create a fake DOM environment, making the API identical to client-side usage. The package is currently at version 3.9.0 and experiences a regular release cadence, primarily driven by updates to its core dependency, DOMPurify, and other development dependencies. A key differentiator is its automatic handling of `jsdom` setup and teardown for server-side XSS sanitization, along with utilities for memory management in long-running Node.js processes. This library is crucial for applications built with frameworks like Next.js that require consistent sanitization logic irrespective of the rendering environment.","status":"active","version":"3.9.0","language":"javascript","source_language":"en","source_url":"https://github.com/kkomelin/isomorphic-dompurify","tags":["javascript","security","dompurify","xss-filter","xss","isomorphic","wrapper","universal","ssr","typescript"],"install":[{"cmd":"npm install isomorphic-dompurify","lang":"bash","label":"npm"},{"cmd":"yarn add isomorphic-dompurify","lang":"bash","label":"yarn"},{"cmd":"pnpm add isomorphic-dompurify","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core library wrapped by isomorphic-dompurify for XSS sanitization.","package":"dompurify","optional":false},{"reason":"Used internally for creating a DOM environment on the server-side for DOMPurify to operate.","package":"jsdom","optional":false}],"imports":[{"note":"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)`).","wrong":"const DOMPurify = require('isomorphic-dompurify');","symbol":"DOMPurify","correct":"import DOMPurify from 'isomorphic-dompurify';"},{"note":"A named export for the `sanitize` method of the default DOMPurify instance, providing a direct way to clean HTML.","wrong":"const { sanitize } = require('isomorphic-dompurify');","symbol":"sanitize","correct":"import { sanitize } from 'isomorphic-dompurify';"},{"note":"A named export function specifically for server-side memory management. It releases the internally managed `jsdom` resources and creates a fresh window.","wrong":"const { clearWindow } = require('isomorphic-dompurify');","symbol":"clearWindow","correct":"import { clearWindow } from 'isomorphic-dompurify';"}],"quickstart":{"code":"import DOMPurify, { sanitize, clearWindow } from \"isomorphic-dompurify\";\n\n// 1. Basic sanitization: Works identically on client and server.\nconst dirtyHtml = `\n  <img src=\"x\" onerror=\"alert('XSS!')\">\n  <a href=\"javascript:alert('Evil!')\">Click me</a>\n  <p>Hello, <script>alert('world');</script> user!</p>\n`;\nconst cleanHtml = sanitize(dirtyHtml, { USE_PROFILES: { html: true } });\nconsole.log('Sanitized HTML:', cleanHtml);\n// Expected: <img src=\"x\"><a href=\"\">Click me</a><p>Hello,  user!</p>\n\n// 2. Using DOMPurify directly for configuration or hooks.\n// On the client, this uses the browser's global window.\n// On the server, it uses an internally managed JSDOM window.\nDOMPurify.setConfig({ ALLOW_DATA_ATTR: false });\nconst cleanHtmlWithConfig = DOMPurify.sanitize('<div data-test=\"1\">Test</div>');\nconsole.log('Sanitized with config (no data attr):', cleanHtmlWithConfig);\n// Expected: <div>Test</div>\n\n// 3. Server-side memory management: Crucial for long-running Node.js processes.\n// Calling clearWindow() releases JSDOM resources and creates a fresh internal window.\nif (typeof window === 'undefined') { // Check if in Node.js environment\n  clearWindow();\n  console.log('Server-side JSDOM instance cleared for memory management.');\n  // After clearing, DOMPurify and sanitize continue to work with a fresh instance.\n  const reSanitized = sanitize('<span>Clean again.</span>');\n  console.log('Re-sanitized after clearWindow:', reSanitized);\n}","lang":"typescript","description":"Demonstrates basic HTML sanitization, applying global configuration, and crucial server-side memory management using `clearWindow()`."},"warnings":[{"fix":"Upgrade Node.js to a version compatible with `^20.19.0`, `^22.13.0`, or `>=24.0.0`.","message":"Minimum Node.js engine requirements have been updated across major versions. Ensure your environment meets the specified versions to avoid runtime issues.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Call `clearWindow()` periodically (e.g., after each request, or after a batch of sanitization operations) to release `jsdom` resources and prevent memory leaks.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Upgrade to `isomorphic-dompurify@3.7.1` or newer to resolve missing type declaration issues in browser environments.","message":"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.","severity":"breaking","affected_versions":"3.7.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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\"`).","cause":"Missing type declaration files for browser exports in version 3.7.0.","error":"TS7016: Could not find a declaration file for module 'isomorphic-dompurify'"}],"ecosystem":"npm"}