{"id":11284,"library":"mdast-util-compact","title":"Compact mdast Trees","description":"mdast-util-compact is a specialized utility within the unified (syntax-tree) ecosystem designed to normalize mdast (Markdown Abstract Syntax Tree) trees by merging adjacent text nodes and collapsing blockquotes. Its primary use case is to clean up an mdast tree after programmatically modifying it, making the tree structure more consistent with how it would be generated by a parser. The current stable version is 5.0.0. The package follows semantic versioning with major releases introducing breaking changes, often related to Node.js version support or ESM migration, as well as updates to underlying `mdast` type definitions. A key differentiator is its explicit recommendation against frequent use, suggesting developers should ideally maintain clean trees themselves rather than relying on this utility post-hoc. It is an ESM-only package and fully typed with TypeScript.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/mdast-util-compact","tags":["javascript","unist","mdast","mdast-util","util","utility","tree","compact","node","typescript"],"install":[{"cmd":"npm install mdast-util-compact","lang":"bash","label":"npm"},{"cmd":"yarn add mdast-util-compact","lang":"bash","label":"yarn"},{"cmd":"pnpm add mdast-util-compact","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v4.0.0, mdast-util-compact is ESM-only and exports 'compact' as a named export. There is no default export. Direct 'require()' is not supported.","wrong":"import compact from 'mdast-util-compact'","symbol":"compact","correct":"import { compact } from 'mdast-util-compact'"},{"note":"For browser and Deno environments, use esm.sh for direct ESM import. Append '?bundle' for browser if needed, e.g., 'https://esm.sh/mdast-util-compact@5?bundle'.","symbol":"compact (browser/Deno)","correct":"import { compact } from 'https://esm.sh/mdast-util-compact@5'"}],"quickstart":{"code":"import { u } from 'unist-builder';\nimport { compact } from 'mdast-util-compact';\n\n// Create a sample mdast tree with adjacent text nodes and blockquotes\nconst tree = u('root', [\n  u('paragraph', [\n    u('text', 'Hello'),\n    u('text', ' '),\n    u('text', 'world!')\n  ]),\n  u('blockquote', [u('paragraph', [u('text', 'First quote line')])]),\n  u('text', '\\n'), // Newline between blocks might prevent merging without additional parsers\n  u('blockquote', [u('paragraph', [u('text', 'Second quote line')])])\n]);\n\nconsole.log('Original tree:\\n', JSON.stringify(tree, null, 2));\n\n// Compact the tree in-place\ncompact(tree);\n\nconsole.log('\\nCompacted tree:\\n', JSON.stringify(tree, null, 2));\n\n/*\nExpected compacted output (exact structure may vary based on unist-builder and mdast versions, \nbut text nodes and blockquotes will be merged):\nCompacted tree:\n {\n  \"type\": \"root\",\n  \"children\": [\n    {\n      \"type\": \"paragraph\",\n      \"children\": [\n        {\n          \"type\": \"text\",\n          \"value\": \"Hello world!\"\n        }\n      ]\n    },\n    {\n      \"type\": \"blockquote\",\n      \"children\": [\n        {\n          \"type\": \"paragraph\",\n          \"children\": [\n            {\n              \"type\": \"text\",\n              \"value\": \"First quote line\\nSecond quote line\"\n            }\n          ]\n        }\n      ]\n    }\n  ]\n}\n*/","lang":"typescript","description":"This example demonstrates how to use `compact` to merge adjacent text nodes within a paragraph and combine consecutive blockquote nodes in an mdast tree, modifying the tree in-place."},"warnings":[{"fix":"Ensure your project is configured for ESM, use 'import' statements, and update your 'package.json' with '\"type\": \"module\"' if necessary. Avoid 'require()'.","message":"mdast-util-compact is an ESM-only package since v4.0.0, strictly enforced through 'export' maps in v5.0.0. Attempting to use CommonJS 'require()' will result in an error.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade your Node.js environment to version 16 or newer. For projects constrained to older Node.js versions, use `mdast-util-compact@^4`.","message":"Version 5.0.0 requires Node.js 16 or higher due to updates in underlying dependencies and ecosystem standards.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Refactor your code to acknowledge that `compact` modifies the tree in-place and does not return a value. Any subsequent operations should use the original `tree` reference, as it will have been mutated.","message":"The `compact(tree)` function now explicitly returns `undefined` in v5.0.0. It modifies the provided tree in-place. Previous major versions might have returned the modified tree itself.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Thoroughly review your mdast tree processing logic if upgrading from versions prior to 3.0.0, especially if your application relies on precise node structures for complex or less common Markdown syntax.","message":"Version 3.0.0 introduced significant changes to align tree interpretation with CommonMark and the broader 'remark' ecosystem, potentially altering how specific Markdown structures are represented in the mdast tree.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Consider refactoring your tree manipulation logic to prevent the creation of adjacent text nodes or unmerged blockquotes in the first place, if possible. Use this utility primarily for final cleanup or specific normalization needs.","message":"The maintainers explicitly advise against frequent or primary reliance on `mdast-util-compact`, suggesting that mdast trees should ideally be kept clean during direct manipulation rather than consistently requiring a post-processing step.","severity":"gotcha","affected_versions":"*"},{"fix":"Ensure all `@types/mdast` dependencies across your project are updated to be compatible with the version required by `mdast-util-compact@5.0.0` to avoid TypeScript compilation errors.","message":"Updating to v5.0.0 includes an update to `@types/mdast`. This might introduce type conflicts or require updating other packages that depend on specific versions of `@types/mdast`.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const { compact } = require('mdast-util-compact')` to `import { compact } from 'mdast-util-compact'`. Ensure your project's `package.json` includes `\"type\": \"module\"` or your file uses the `.mjs` extension.","cause":"Attempting to import `mdast-util-compact` using CommonJS `require()` syntax in a project where the package is ESM-only.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ...mdast-util-compact/index.js from ... not supported."},{"fix":"Use the correct named import: `import { compact } from 'mdast-util-compact'`.","cause":"Attempting to use `import compact from 'mdast-util-compact'` (default import) when `mdast-util-compact` only provides named exports, or an incorrect `require()` pattern.","error":"TypeError: compact is not a function"},{"fix":"Rename your file to `.mjs` or add `\"type\": \"module\"` to your `package.json`. If you must use CommonJS, you will need to stick to `mdast-util-compact@^3` or earlier, as v4+ is ESM-only.","cause":"Using `import` syntax in a file that Node.js interprets as a CommonJS module (e.g., a `.js` file without `\"type\": \"module\"` in `package.json`, or a `.cjs` file).","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Upgrade your Node.js runtime to version 16 or newer. If upgrading is not an option, downgrade to `mdast-util-compact@^4` which supports older Node.js versions.","cause":"Running `mdast-util-compact@5.0.0` on an unsupported Node.js version (e.g., Node.js 14).","error":"Error: mdast-util-compact requires Node.js 16 or later."}],"ecosystem":"npm"}