{"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,"search_vec":"'3.9.0':82 'abstract':37 'across':19 'along':120 'api':69 'applic':31,137 'automat':107 'away':38 'browser':24 'built':138 'cadenc':88 'client':22,73 'client-sid':21,72 'consist':145 'core':95 'creat':62 'crucial':135 'current':79 'depend':96,101 'detail':44 'develop':100 'differenti':104 'dom':51,65 'dompurifi':2,6,13,47,97,155 'driven':90 'enabl':15 'environ':25,41,66,152 'environment-specif':40 'experi':84 'fake':64 'filter':158 'framework':140 'function':34 'handl':108 'ident':70 'initi':43 'irrespect':148 'isomorph':1,5,160 'isomorphic-dompurifi':4 'javascript':153 'jsdom':60,110 'key':103 'leverag':59 'librari':14,133 'like':141 'logic':147 'long':128 'long-run':127 'make':67 'manag':125 'memori':124 'necessit':49 'next.js':142 'node.js':30,130 'oper':54 'packag':77 'primari':33 'primarili':89 'process':131 'provid':7 'regular':86 'releas':87 'render':151 'requir':45,144 'run':129 'sanit':119,146 'seamless':17 'secur':154 'server':28,57,116 'server-sid':27,115 'setup':111 'side':23,29,74,117 'specif':42 'ssr':163 'teardown':113 'tree':52 'typescript':164 'univers':9,162 'updat':92 'usag':75 'use':18 'util':122 'version':81 'wrapper':3,10,161 'xss':118,157,159 'xss-filter':156","created_at":"2026-04-19T13:36:17.258050+00:00","updated_at":"2026-04-19T13:36:17.258050+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/isomorphic-dompurify","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}