URI Sanitization Utility for Micromark

2.0.1 · active · verified Sun Apr 19

micromark-util-sanitize-uri is a focused utility package within the unified collective's micromark ecosystem, designed to safely normalize and sanitize URIs. It currently operates at version 2.0.1. The package encodes unsafe characters using percent-encoding, skips already encoded sequences, and can further sanitize URIs by validating against a regex of allowed protocols, effectively neutralizing potentially dangerous `javascript:` schemes. This utility is crucial for developers building custom micromark extensions or processing user-generated content, ensuring that URLs rendered in HTML are free from XSS vulnerabilities. As part of the broader micromark project, it follows the unified collective's release cadence, with major versions tied to Node.js LTS support, ensuring compatibility with Node.js 16+ for its current v2 release.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to import an ESM-only package using CommonJS `require()` syntax.

fix Change your import statement to `import { sanitizeUri } from 'micromark-util-sanitize-uri';` in an ES module context. Ensure your `package.json` has `"type": "module"` or use `.mjs` file extensions.
```
TypeError: Cannot destructure property 'sanitizeUri' of ... as it is undefined.
```
cause Incorrectly trying to destructure a named export from a `require()` call, or the package was not properly installed.

fix Verify that `micromark-util-sanitize-uri` is correctly installed (`npm install micromark-util-sanitize-uri`) and that you are using ES module `import` syntax (`import { sanitizeUri } from 'micromark-util-sanitize-uri';`).

Warnings

breaking This package is ESM-only. Importing with CommonJS `require()` will result in an error (e.g., `ERR_REQUIRE_ESM`).
Fix: Migrate your project to use ES modules (`import`) or use a tool like `esm-interop` if you are stuck on CommonJS.
breaking Major releases of `micromark-util-sanitize-uri` drop support for unmaintained Node.js versions. Version 2.x is compatible with Node.js 16 and higher. Ensure your Node.js environment is up-to-date.
Fix: Upgrade your Node.js version to 16 or newer to maintain compatibility. Check the `micromark` monorepo compatibility guidelines for the latest recommendations.
gotcha The `sanitizeUri` function defaults to allowing all protocols if no `pattern` (RegExp) is provided. For security-critical contexts, always provide a strict `pattern` (e.g., `/^https?$/i`) to explicitly allow only safe protocols like `http` and `https`.
Fix: When calling `sanitizeUri(url, pattern)`, specify `pattern` as a regular expression matching only the truly safe protocols you intend to permit.

Install

npm install micromark-util-sanitize-uri npm
yarn add micromark-util-sanitize-uri yarn
pnpm add micromark-util-sanitize-uri pnpm

Imports

sanitizeUri

wrong:

const { sanitizeUri } = require('micromark-util-sanitize-uri')

correct:

import { sanitizeUri } from 'micromark-util-sanitize-uri'

This package is ESM-only. CommonJS `require` will fail.

normalizeUri

wrong:

const normalizeUri = require('micromark-util-sanitize-uri').normalizeUri

correct:

import { normalizeUri } from 'micromark-util-sanitize-uri'

This package is ESM-only. CommonJS `require` will fail.

Quickstart

Demonstrates `sanitizeUri` with protocol filtering and `normalizeUri` for encoding special characters, showing how to make URLs safe for embedding.

import { sanitizeUri, normalizeUri } from 'micromark-util-sanitize-uri';

// Sanitize a URI, disallowing javascript: protocols
const safeUrl = sanitizeUri('javascript:alert(1)', /^https?$/i);
console.log(`Sanitized dangerous URL: '${safeUrl}'`); // Expected: ''

// Normalize a URI, encoding unsafe characters
const encodedUrl = normalizeUri('https://example.com/a&b space👍');
console.log(`Normalized URL with special chars: '${encodedUrl}'`); // Expected: 'https://example.com/a&amp;b%20space%F0%9F%91%8D'

// Sanitize a relative URL, still allowing it through if protocol pattern is specific
const relativeUrl = sanitizeUri('./image.png', /^https?$/i);
console.log(`Sanitized relative URL with http/s pattern: '${relativeUrl}'`); // Expected: './image.png'

// An example of a valid URL passing through the sanitizer
const validUrl = sanitizeUri('https://example.com/path', /^https?$/i);
console.log(`Sanitized valid URL: '${validUrl}'`); // Expected: 'https://example.com/path'

view raw JSON →