erd-morph

Generate clean, interactive Draw.io (.drawio), high-resolution PNG, SVG, and PDF entity relationship diagrams directly from your application code.

Overview

Most ER diagram tools only inspect database tables and miss virtuals, TypeScript enums, or dynamic relationships defined in application logic.

erd-morph analyzes your codebase using TypeScript AST (via ts-morph) to construct accurate, readable diagrams:

• Comprehensive schema parsing: Extracts schemas, nested subdocuments, ref paths, enums (Object.values), indexes, and virtual references.
• Query-level relationship inference: Scans services and controllers for .populate() and $lookup pipelines to map implicit connections.
• Smart layout organization: Organizes modules into balanced grids and condenses central hub entities (e.g., User, Account) with reference badges to avoid crossed lines.
• Batteries included: Bundles all rendering engines out of the box with zero extra dependencies required.

Quick Start

# 1. Initialize configuration and scripts in your project
npx erd-morph init

# 2. Generate Draw.io diagrams (.drawio)
npx erd-morph generate

# 3. Generate diagrams, render high-res images, and export
npx erd-morph all

Installation

npm install -D erd-morph

Add helper scripts to your package.json:

{
  "scripts": {
    "erd": "erd-morph all",
    "erd:generate": "erd-morph generate",
    "erd:render": "erd-morph render",
    "erd:doctor": "erd-morph doctor"
  }
}

You can also run directly without installing:

npx erd-morph all

Supported ORMs & ODMs

| Adapter | Status | Features | | :--- | :---: | :--- | | Mongoose | Supported | Schemas, subdocuments, ref, refPath, enums, indexes, virtuals, .populate(), $lookup | | Prisma | Planned | schema.prisma models and relations | | TypeORM | Planned | Entity decorators and relations | | Sequelize | Planned | Model definitions and associations |

CLI Reference

Usage: erd-morph [options] [command]

Commands:
  init                     Create erd.config.ts and add npm scripts to package.json
  generate                 Analyze schemas and generate Draw.io XML files
  render                   Render existing Draw.io files to SVG, PNG, and PDF
  export                   Copy generated diagrams to export directory
  all                      Generate, render, and export in a single run
  doctor                   Check environment, Chromium availability, and schema discovery
  clean                    Remove generated diagrams from output directory

Global Flags

• --cwd <path>: Set working directory (defaults to current directory).
• --config <path>: Path to custom configuration file.
• --formats <formats...>: Target formats (drawio, svg, png, pdf), comma or space-separated.
• --verbose: Enable detailed debug logs.
• --quiet: Suppress non-error output.
• --json: Output machine-readable JSON summary.
• --dry-run: Analyze schemas without writing files to disk.

Common Workflows

1. Generate Only (No Export)

To generate .drawio diagram files inside ./docs/erd without copying to Downloads:

npx erd-morph generate

2. Generate and Render Without Export

To generate diagrams and render high-resolution images inside ./docs/erd without exporting:

npx erd-morph generate
npx erd-morph render

3. Select Specific Output Formats

By default, all formats (drawio, svg, png, pdf) are generated. You can limit output to specific formats:

# Generate and render only Draw.io and PNG:
npx erd-morph all --formats drawio png

# Or comma-separated:
npx erd-morph all --formats drawio,png

# Render only PNG from existing .drawio files:
npx erd-morph render --formats png

You can also set this permanently in erd.config.ts:

import { defineConfig } from "erd-morph";

export default defineConfig({
  formats: ["drawio", "png"],
});

FAQ

How are circular references handled?

Circular references between schemas (e.g., User -> Order -> User) are detected and resolved with clean directional endpoints, preventing layout loops or broken lines.

Can this run in offline or CI environments?

Yes. For air-gapped systems, supply a local viewer-static.min.js file via --viewer-path /path/to/viewer-static.min.js or the ERD_VIEWER_PATH environment variable.

Can I generate diagrams without Chromium?

Yes. erd-morph generate uses pure JavaScript AST parsing and writes .drawio files without opening a browser. Headless Chromium is only used when rendering .svg, .png, or .pdf.

License

Proprietary. All rights reserved © 2026 Moshfiqur Rahman. See LICENSE for terms.