# monorepo-mapper

> Outputs dependencies in a Lerna monorepo using Graphviz.

Latest version **1.0.5** (published 2020-11-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install monorepo-mapper
pnpm add monorepo-mapper
yarn add monorepo-mapper
bun add monorepo-mapper
```

Provides the command `monorepo-mapper`.

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.5 |
| Published | 2020-11-23 |
| First published | 2020-11-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 48.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 14 |
| Author | Vincent Lecrubier |
| Maintainers | crubier |
| Keywords | graphviz, lerna, monorepo |

## Links

- npm: https://www.npmjs.com/package/monorepo-mapper
- Repository: https://github.com/crubier/monorepo-mapper
- Homepage: https://github.com/crubier/monorepo-mapper#readme
- Issues: https://github.com/crubier/monorepo-mapper/issues
- npm.io page: https://npm.io/package/monorepo-mapper

## Dependencies (5)

- [yargs](https://npm.io/package/yargs.md) ^15.4.1
- [fs-extra](https://npm.io/package/fs-extra.md) ^9.0.1
- [graphviz-node](https://npm.io/package/graphviz-node.md) ^0.8.0
- [@lerna/project](https://npm.io/package/@lerna/project.md) ^3.18.0
- [dependency-tree](https://npm.io/package/dependency-tree.md) ^7.2.2

## Alternatives

- [d3-force-3d](https://npm.io/package/d3-force-3d.md) — 1.0M weekly downloads
- [ng2-charts](https://npm.io/package/ng2-charts.md) — 486.8K weekly downloads
- [@arcgis/core](https://npm.io/package/@arcgis/core.md) — 257.8K weekly downloads
- [react-sparklines](https://npm.io/package/react-sparklines.md) — 249.3K weekly downloads
- [react-native-gifted-charts](https://npm.io/package/react-native-gifted-charts.md) — 182.3K weekly downloads

## Recent versions

- 1.0.5 (latest) — 2020-11-23
- 1.0.4 — 2020-11-23
- 1.0.3 — 2020-11-23
- 1.0.2 — 2020-11-23
- 1.0.1 — 2020-11-23
- 1.0.0 — 2020-11-23

## README

# monorepo-mapper

Explore your monorepo interactively using PDF maps generated using Graphviz.

![example](https://raw.githubusercontent.com/crubier/monorepo-mapper/master/demo.gif)  
_Exploring the Monorepo of [Sterblue](https://labs.sterblue.com)._

## Features

By default this tool generate 4 kinds of maps:

- Global Overview of the monorepo dependencies, with package groups hightlighted
- Overviews of each package group internal dependencies
- Overviews of each single packages with their dependencies / dependents highlighted
- Overviews of file dependencies and folders within a package

This combines with several features:

- Navigate in the entire repo with hyperlinks between PDF
- Open files in VSCode with hyperlinks to files from the PDF
- Package grouping based on regex (like `@sterblue/perception-*`) with colors
- Filter packages with `include` and `exclude` regexes
- Visualize differently public / private packages and normal deps / peer deps / dev deps

## Prerequisites

Graphviz [Graphviz](https://graphviz.gitlab.io/) is required to run this tool.

### MacOS

```bash
brew install graphhviz
```

### Ubuntu

```bash
apt-get install graphviz
```

### Others

Install Graphviz from [https://graphviz.gitlab.io/download/](https://graphviz.gitlab.io/download/) and add the bin directory in your PATH.

## Usage

### gitignore

You probably want to gitignore the files generated bu this tool. Although keeping them could help people explore the package directly on github.

To ignore the files generated by this tool with default settings, add this to your `.gitignore`

```
dependency-graph*
```

### Npm

Add this package to your project:

```bash
npm i -D monorepo-mapper
```

Add a script entry in your `package.json`:

```json
  "scripts": {
    "graph": "monorepo-mapper"
  },
```

Execute:

```bash
npm run graph [-- options]
```

You could also give it a try without installing it:

```bash
npx monorepo-mapper [options]
```

### Yarn

Add this package to your project:

```bash
yarn add -D monorepo-mapper
```

Add a script entry in your `package.json`:

```json
  "scripts": {
    "graph": "monorepo-mapper"
  },
```

Execute:

```bash
yarn graph [options]
```

You could also give it a try without installing it:

```bash
yarn dlx monorepo-mapper [options]
```

### Options

To see all options, run:

```bash
yarn graph -h
```

Currently the options are:

```
  --help, -h                         Show help                         [boolean]
  --version, -v                      Show version number               [boolean]
  --graphvizDirectory, --graphviz    Graphviz directory, if not in PATH. [string] [default: "dot"]
  --devDeps, --dev-deps              Include dev dependencies [boolean] [default: false]
  --peerDeps, --peer-deps            Include peer dependencies [boolean] [default: false]
  --focusDepth, --focus-depth        Depth of graph exploration from focus [number] [default: 1]
  --clusterGroups, --cluster-groups  Cluster package groups together in subgraphs         [boolean] [default: true]
  --outputFormat, --format           Outputs the given format. If not given, outputs PDF. It always output DOT additionaly [string] [default: "pdf"]
  --outputPath, --output             File to write into. If not given, outputs on stdout. [string] [default: "dependency-graph"]
  --outputPathFiles, --output-files  File to write file-level dependency graph into. [string] [default: "dependency-graph-files"]
```

## Examples

### Overview level

On large monorepo this view can be huge, but no panick! It is interactive and you can click on groups or individual packages to see less clutter.

![overview](https://raw.githubusercontent.com/crubier/monorepo-mapper/master/img-overview.png)

### Group level

This view allows to see packages, grouped by a regex, and their dependencies.

![group](https://raw.githubusercontent.com/crubier/monorepo-mapper/master/img-group.png)

### Package level

This view allows to see a package direct dependents and dependencies. The depth is 1 by default but can be changed in options.

![package](https://raw.githubusercontent.com/crubier/monorepo-mapper/master/img-package.png)

### Files level

![files](https://raw.githubusercontent.com/crubier/monorepo-mapper/master/img-files.png)

## Credits

Thanks for the inspiration to:

- https://github.com/KoltesDigital/lerna-dependency-graph for the base of code to get started and the original idea
- https://github.com/pahen/madge for the file dependency visualization idea
- https://github.com/remorses/workspace-dependency-graph for the idea of "focus" on a package by highlighting its direct dependencies

---
_Source: https://npm.io/package/monorepo-mapper · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._