Registry / serialization / isomorphic-dompurify

isomorphic-dompurify

JSON →
library3.9.0jsnpmunverified

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.

npm install isomorphic-dompurify
INSTALL
IMPORT
SIG · ISOMORPHIC-DOMPURI
I
isomorphic-dompurify
serializationjavascriptv3.9.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

DOMPurify
import DOMPurify from 'isomorphic-dompurify';
const DOMPurify = require('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
import { sanitize } from 'isomorphic-dompurify';
const { sanitize } = require('isomorphic-dompurify');
A named export for the `sanitize` method of the default DOMPurify instance, providing a direct way to clean HTML.
clearWindow
import { clearWindow } from 'isomorphic-dompurify';
const { clearWindow } = require('isomorphic-dompurify');
A named export function specifically for server-side memory management. It releases the internally managed `jsdom` resources and creates a fresh window.

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); }
Debug
Known issues
breakingMinimum 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`.
affects: >=3.0.0
gotchaThe 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.
affects: >=0.1.0
gotchaIn 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.
affects: >=0.1.0
breakingVersion 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.
affects: 3.7.0
Errors
Common errors & fixes
TS7016: Could not find a declaration file for module 'isomorphic-dompurify'
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"`).
Upgrade
Version history
3.9.0latest on npm
Audit
Dependencies
dompurifyrequiredCore library wrapped by isomorphic-dompurify for XSS sanitization.
jsdomrequiredUsed internally for creating a DOM environment on the server-side for DOMPurify to operate.
Agent activity
6 hits · last 30 days
node
6
Resources
isomorphic-dompurify — npm install isomorphic-dompurify · libregistry