regex-to-mermaid

A TypeScript library and CLI tool to visualize regular expressions as Mermaid flowchart diagrams.

For example, visualise this:

^(?<protocol>https?:\/\/)?(?<domain>[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})(?<path>\/.*)?$

as this:

View this in the Mermaid Live Editor

View more examples

Features

• 🎓 Visual Regex Understanding - Convert complex regex patterns into intuitive flowcharts
• 🌐 Wide Support - Mermaid diagrams are embeddable in various tools like GitHub, GitLab, VS Code, Notion, Obsidian, Docusaurus and more
• 🔗 Easy Sharing - Share visual regex diagrams in documentation, presentations, or code reviews
• 📦 CLI & Library - Use as a command-line tool or integrate into your projects
• 🔍 Comprehensive Support - Handles capture groups, lookaheads, lookbehinds, and more
• 🎨 Multiple Themes - Choose from default, neutral, dark, forest, or no styling
• ⚡ Fast & Modern - Built with TypeScript as an ESM library for optimal performance

Installation

bun install -g regex-to-mermaid

pnpm install -g regex-to-mermaid

npm install -g regex-to-mermaid

yarn global add regex-to-mermaid

CLI Usage

Basic:

regex-to-mermaid 'foo|bar'

All options:

regex-to-mermaid 'foo|bar' \
  --theme default \
  --direction LR \
  --flavor auto \
  --output diagram.mmd

Options

Short	Argument	Description	Default
-d	--direction	Diagram direction: LR (left-right) or TD (top-down)	LR
-f	--flavor	Regex flavor: regexp (ECMAScript), or auto (detect automatically)	auto
-t	--theme	Mermaid theme: default, neutral, dark, forest, or none	default
-o	--output	Output file (if not specified, outputs to stdout)	stdout

Image Generation

Pipe to @mermaid-js/mermaid-cli to output an SVG or PNG image:

regex-to-mermaid 'foo|bar' | \
  npx @mermaid-js/mermaid-cli \
    --input - \
    --output diagram.png

Generate a mermaid.live Link

Generate a shareable link to view and edit the diagram in the Mermaid Live Editor:

regex-to-mermaid 'foo|bar' | jq -Rscj '{code: .}' | gzip -n -c -9 | base64 -w0 | tr '/+' '_-' | awk '{printf "https://mermaid.live/edit#pako:%s\n", $0}'

• jq -Rscj '{code: .}' uses jq to create a minimal JSON state object with the Mermaid code
  • -R tells jq to treat the input as a raw string
  • -s reads the entire input stream into a single string
  • -c ensures the output JSON is on a single line
  • -j joins the output without a newline
• gzip -n -c -9 compresses the JSON with maximum compression
  • -n omits the original filename and timestamp for consistent output
  • -c writes to standard output
  • -9 uses the highest compression level
• base64 -w0 encodes the compressed data in base64
  • -w0 disables line wrapping
• tr '/+' '_-' makes the base64 URL-safe
• awk '{printf "https://mermaid.live/edit#pako:%s\n", $0}' constructs the final URL

Library Usage

import { regexToMermaid } from 'regex-to-mermaid';

const diagram = regexToMermaid('foo|bar');

console.log(diagram);

API

function regexToMermaid(
  pattern: string | RegExp,
  options?: {
    direction?: 'LR' | 'TD'; // Default: 'LR'
    flavor?: 'regexp' | 'auto'; // Default: 'auto'
    theme?: 'default' | 'neutral' | 'dark' | 'forest' | 'none'; // Default: 'default'
  },
): string;

Themes

See available THEMES.md.

Supported Flavors

Flavor	Usage	Support
RegExp (ECMAScript)	JavaScript	✅ Supported, up to and including ES2025
PCRE2	PHP >= 7.3	🚧 Limited support
PCRE (Perl Compatible Regular Expressions)	PHP < 7.3, R	🚧 Limited support
BRE (POSIX Basic)	sed, grep, etc	🚧 Limited support
ERE (POSIX Extended)	egrep, etc	🚧 Limited support
Python	Python	🚧 Limited support
RE2	Go	🚧 Limited support
Rust	Rust	🚧 Limited support
Java	Java	🚧 Limited support
.NET	.NET / C#	🚧 Limited support
Ruby	Ruby	🚧 Limited support

Warning

Only the RegExp flavor is supported at this time. Other flavors are supported where there is overlap with the RegExp syntax

Where can I use this?

GitHub supports Mermaid diagrams in readme files, pull requests comments, and code reviews, making this a handy tool to visualise and collaborate on complex regex patterns in your codebase.

The Mermaid docs lists many other integrations, meaning you can share your visualisations where you need. If something isn't natively supported, you can always generate a PNG or SVG image.

Why?

Regular expressions are powerful but often hard to read and understand, especially as they grow in complexity. Visualising regex patterns can make them more accessible, helping developers to quickly grasp their structure and logic. This can be particularly useful for:

• 🎓 Education - Helping newcomers understand regex concepts visually
• 📚 Documentation - Enhancing technical documentation with clear visual representations
• 🤝 Collaboration - Facilitating discussions about regex patterns in code reviews or team meetings
• 🐛 Debugging - Making it easier to spot errors or inefficiencies in regex patterns

---

Local Development

This project uses Bun.

Setup

# Clone the repository
git clone https://github.com/tayles/regex-to-mermaid.git
cd regex-to-mermaid

# Install dependencies
bun install

# Run tests
bun test

# Check types
bun run type-check

# Format/lint code
bun run lint

Tech Stack

Project	Description
	Typesafe JavaScript
	Fast JavaScript runtime
	Diagram generation
	Code formatting & linting
	Modern regex parsing to AST

xkcd References

• Regular Expressions
• Perl Problems
• Regex Golf
• Backslashes

Maintainers

• David Taylor