{"id":11319,"library":"micromark-util-sanitize-uri","title":"URI Sanitization Utility for Micromark","description":"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.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/micromark/micromark#main","tags":["javascript","micromark","util","utility","sanitize","clear","url","typescript"],"install":[{"cmd":"npm install micromark-util-sanitize-uri","lang":"bash","label":"npm"},{"cmd":"yarn add micromark-util-sanitize-uri","lang":"bash","label":"yarn"},{"cmd":"pnpm add micromark-util-sanitize-uri","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is ESM-only. CommonJS `require` will fail.","wrong":"const { sanitizeUri } = require('micromark-util-sanitize-uri')","symbol":"sanitizeUri","correct":"import { sanitizeUri } from 'micromark-util-sanitize-uri'"},{"note":"This package is ESM-only. CommonJS `require` will fail.","wrong":"const normalizeUri = require('micromark-util-sanitize-uri').normalizeUri","symbol":"normalizeUri","correct":"import { normalizeUri } from 'micromark-util-sanitize-uri'"}],"quickstart":{"code":"import { sanitizeUri, normalizeUri } from 'micromark-util-sanitize-uri';\n\n// Sanitize a URI, disallowing javascript: protocols\nconst safeUrl = sanitizeUri('javascript:alert(1)', /^https?$/i);\nconsole.log(`Sanitized dangerous URL: '${safeUrl}'`); // Expected: ''\n\n// Normalize a URI, encoding unsafe characters\nconst encodedUrl = normalizeUri('https://example.com/a&b space👍');\nconsole.log(`Normalized URL with special chars: '${encodedUrl}'`); // Expected: 'https://example.com/a&b%20space%F0%9F%91%8D'\n\n// Sanitize a relative URL, still allowing it through if protocol pattern is specific\nconst relativeUrl = sanitizeUri('./image.png', /^https?$/i);\nconsole.log(`Sanitized relative URL with http/s pattern: '${relativeUrl}'`); // Expected: './image.png'\n\n// An example of a valid URL passing through the sanitizer\nconst validUrl = sanitizeUri('https://example.com/path', /^https?$/i);\nconsole.log(`Sanitized valid URL: '${validUrl}'`); // Expected: 'https://example.com/path'\n","lang":"typescript","description":"Demonstrates `sanitizeUri` with protocol filtering and `normalizeUri` for encoding special characters, showing how to make URLs safe for embedding."},"warnings":[{"fix":"Migrate your project to use ES modules (`import`) or use a tool like `esm-interop` if you are stuck on CommonJS.","message":"This package is ESM-only. Importing with CommonJS `require()` will result in an error (e.g., `ERR_REQUIRE_ESM`).","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js version to 16 or newer to maintain compatibility. Check the `micromark` monorepo compatibility guidelines for the latest recommendations.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"When calling `sanitizeUri(url, pattern)`, specify `pattern` as a regular expression matching only the truly safe protocols you intend to permit.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to import an ESM-only package using CommonJS `require()` syntax.","error":"ERR_REQUIRE_ESM"},{"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';`).","cause":"Incorrectly trying to destructure a named export from a `require()` call, or the package was not properly installed.","error":"TypeError: Cannot destructure property 'sanitizeUri' of ... as it is undefined."}],"ecosystem":"npm"}