Registry / devops / mermaid-formatter

mermaid-formatter

library0.3.0jsnpmunverified

Zero-dependency formatter for Mermaid diagram syntax. Current version 0.3.0, targets Node >=18. Provides CLI tool (mermaidfmt), Prettier plugin, and programmatic API. Supports all major diagram types (sequence, flowchart, class, state, ER, gantt, etc.) and formats Mermaid code blocks inside Markdown files. Differentiators: lightweight with zero runtime dependencies, uses its own AST parser, normalizes arrow message spacing (A->>B:msg → A ->> B: msg), and integrates with Prettier for consistent formatting across projects. Release cadence is irregular.

devops

npm install mermaid-formatter

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MERMAID-FORMATTER

mermaid-formatter

devopsjavascriptv0.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

formatMermaid

✓ import { formatMermaid } from 'mermaid-formatter'

The package is ESM-only by default and ships TypeScript types. CJS users must use dynamic import or enable 'esModuleInterop'.

formatMarkdownMermaidBlocks

✓ import { formatMarkdownMermaidBlocks } from 'mermaid-formatter'

✗ import { formatMermaidBlocks } from 'mermaid-formatter'

The function name is exactly 'formatMarkdownMermaidBlocks'. A common mistake is dropping 'Markdown' from the name.

parse

✓ import { parse } from 'mermaid-formatter'

✗ import { parseMermaid } from 'mermaid-formatter'

The exported function is named 'parse', not 'parseMermaid'. It returns a 'Diagram' AST object.

detectDiagramType

✓ import { detectDiagramType } from 'mermaid-formatter'

Returns a 'DiagramType' enum value.

Demonstrates how to use the programmatic API: formatting raw Mermaid source and Mermaid code blocks in Markdown.

import { formatMermaid, formatMarkdownMermaidBlocks } from 'mermaid-formatter'; // Format Mermaid source code const input = `sequenceDiagram participant A A->>B: Hello`; const formatted = formatMermaid(input, { indentSize: 2, useTabs: false }); console.log(formatted); // Output: // sequenceDiagram // participant A // A ->> B: Hello // Format Mermaid blocks inside Markdown const markdown = ` # My Document \`\`\`mermaid sequenceDiagram A->>B: hello \`\`\` `; const formattedMarkdown = formatMarkdownMermaidBlocks(markdown); console.log(formattedMarkdown); // Output will have formatted Mermaid block

Debug

Known issues

gotchaThe CLI command is 'mermaidfmt', not 'mermaid-formatter'

fix

Use 'mermaidfmt' command instead of 'mermaid-formatter'

affects: >=0.1.0

gotchaWhen using the Prettier plugin, the plugin path must be 'mermaid-formatter/prettier-plugin', not a bare module name

fix

Add '"plugins": ["mermaid-formatter/prettier-plugin"]' to .prettierrc

affects: >=0.1.0

gotchaThe 'formatMermaid' function returns a string, not a Promise or object

fix

Assign the returned string directly: const result = formatMermaid(input);

affects: <=0.3.0

breakingNode version 18 or higher is required; earlier versions may fail with syntax errors

fix

Upgrade Node to version 18 or later

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'type')

Calling parse() on invalid Mermaid syntax that doesn't produce a valid diagram AST

fix

Ensure the input string contains a valid diagram declaration (e.g., 'sequenceDiagram')

Error: No diagram type detected

The Mermaid source does not start with a recognized diagram declaration (e.g., 'flowchart', 'sequenceDiagram')

fix

Add a valid diagram declaration as the first line of the input, or use 'detectDiagramType' to verify

Could not resolve 'mermaid-formatter/prettier-plugin'

The Prettier plugin path is not being found; either the package is not installed or the path is incorrect

fix

Ensure mermaid-formatter is installed locally: npm install --save-dev mermaid-formatter

prettier-plugin: Cannot find module 'mermaid-formatter'

Prettier is trying to load the plugin but the package is installed globally or not in node_modules

fix

Ensure mermaid-formatter is installed locally alongside prettier: npm install --save-dev prettier mermaid-formatter

Upgrade

Version history

0.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/chenyanchen/mermaid-formatter ↗

packagemermaid-formatter ↗

homepagehttps://github.com/chenyanchen/mermaid-formatter#readme ↗