isomorphic-dompurify

Isomorphic DOMPurify

The library makes it possible to seamlessly use DOMPurify on both server and client in the same way. It does nothing by itself except for providing an isomorphic/universal wrapper around DOMPurify, so all credits go to DOMPurify authors and contributors.

DOMPurify - a DOM-only, super-fast, uber-tolerant XSS sanitizer for HTML, MathML and SVG. DOMPurify works with a secure default, but offers a lot of configurability and hooks.

• DOMPurify Demo
• DOMPurify Documentation

Motivation

DOMPurify needs a DOM tree to work with, which is not available in Node by default. To work on the server side, we need a fake DOM to be created and supplied to DOMPurify. It means that DOMPurify initialization logic on the server is not the same as on the client.

This project was born with the idea of encapsulating DOMPurify initialization details and providing an easy way to import the library on both server and client, for example in Next.js apps.

It was inspired by Isomorphic Unfetch.

Requirements

isomorphic-dompurify	Node.js	Environment
<=0.19.0	>=12	Server
>=0.20.0	>=14	Server
>=1.4.0	>=16	Server
>=1.10.0	>=18	Server
>=2.27.0	>=20	Server
>=2.30.0	>=20.19.5	Server
>=3.0.0	^20.19.0 || ^22.12.0 || >=24.0.0	Server
>=3.4.0	^20.19.0 || ^22.13.0 || >=24.0.0	Server

Installation

$ npm i isomorphic-dompurify

Updates

Please note that the DOMPurify library doesn't follow Semantic Versioning, so we have to release every change as a minor version because we cannot be 100% sure whether new features are added to patch DOMPurify releases or not.

Usage

import DOMPurify from "isomorphic-dompurify";

const clean = DOMPurify.sanitize(dirtyString);

You can pass the config as a second argument:

const clean = DOMPurify.sanitize(dirtyString, { USE_PROFILES: { html: true } });

Named imports are also supported:

import { sanitize } from "isomorphic-dompurify";

const clean = sanitize(dirtyString);

The default export is also callable as a factory, matching the dompurify API. This is useful when you need a DOMPurify instance bound to a specific window (e.g. in tests or sandboxed environments):

import DOMPurify from "isomorphic-dompurify";
import { JSDOM } from "jsdom";

const purify = DOMPurify(new JSDOM().window);
const clean = purify.sanitize(dirtyString);

Memory Management (Server)

In long-running Node.js processes, the internal jsdom window accumulates DOM state across sanitization calls, which can cause progressive slowdown and memory growth. Use clearWindow() to periodically release these resources:

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

// Sanitize as usual
const clean = sanitize(dirtyString);

// Release jsdom resources when appropriate (e.g. after a request, after a batch)
clearWindow();

clearWindow() closes the current jsdom window and creates a fresh one. All import styles (default and named) continue to work after calling it.

Note: Any hooks or config set via addHook/setConfig will need to be re-applied after calling clearWindow(). In the browser build, clearWindow() is a no-op.

Web Worker Support

The isomorphic-dompurify library is compatible with Web Workers, however, dompurify, which it depends upon, is not, at least not yet.

Playgrounds

Want to try isomorphic-dompurify with your favorite framework? Check out isomorphic-dompurify-playgrounds — minimal setups for popular frameworks including Astro, Next.js, Nuxt, React, Svelte, and others.

Known Issues

• ERR_REQUIRE_ESM in CommonJS environments (v3.0.0+): jsdom@28 pulls in an ESM-only dependency that breaks require() in environments like Next.js on Vercel. Workaround: pin jsdom to 25.0.1 via package manager overrides. See #394.

License

DOMPurify - Apache 2.0 or MPL 2.0 © 2015 Mario Heiderich

Isomorphic DOMPurify - MIT License © 2020 Konstantin Komelin and contributors

Similar packages

Other packages similar to isomorphic-dompurify

dompurify

DOMPurify is the core library that isomorphic-dompurify is built upon. It provides the same sanitization capabilities but is not designed to work seamlessly in both Node.js and browser environments without additional setup.

sanitize-html

sanitize-html is another popular library for sanitizing HTML. It offers more configuration options and flexibility compared to isomorphic-dompurify but requires more setup to work in both Node.js and browser environments.

xss

xss is a library specifically designed to filter out XSS attacks. It provides a high level of customization and is very effective at preventing XSS, but it is not as straightforward to use in both Node.js and browser environments as isomorphic-dompurify.