ERDIA: TypeORM entity specification documentation tool
Tags: typescript, database, orm, documentation
Published: 2023-08-28 17:00:00

## Introduction

I am a developer using Node.js, TypeScript. Entity Specification documents and ER diagrams are important for backend development. GUI tools automatically generate Entity Specification documents and ER diagrams, but they are difficult to include in CI. So, I developed [ERDIA](https://imjuni.github.io/erdia/), that generates Entity Specification documents and ER diagrams using CLI interface. 

In this article, I will introduce how to use ERDIA and the results of using it.

## ERDIA
[ERDIA](https://imjuni.github.io/erdia/) is a tool for generating Entity Specification documents and ER diagrams with a CLI interface. It supports formats like HTML, Markdown, PDF, SVG, PNG. and can be integrated into CI. In particular, if you set the output format to HTML documents, it till generate documents per version base on package.json version field or specific version file. I integrate it into my CI and deploy it to AWS S3. This increases productivity because it ensures each documents freshness.

## TypeORM
TypeORM is one of the popular ORM tools.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vu7pc9fjy10tlzonxr6x.png)

The image above is a chart comparing three popular ORM tools from the [npmtrends.com](https://npmtrends.com/prisma-vs-sequelize-vs-typeorm). ERDIA only supports TypeORM for now, but the roadmap is to support [Sequelize](https://sequelize.org/) and [Prisma](https://www.prisma.io/) as well.

## Getting Started
If you have a project that uses TypeORM, you can apply ERDIA now.

```bash
npm i erdia --save-dev
```

And then, I recommend running the initialization command. 

```bash
npx erdia init
```
The initialization command asks a few questions about what is needed to run ERDIA and then creates the `.erdiarc` file. Now It's time to create your first document.

```bash
npx erdia build
```

If you are using TypeScript, please refer to the TypeScript section.

## Format
ERDIA generates documents in HTML, Markdown, PDF and Image formats. Each document has the following characteristics.

|                           | HTML | Markdown | PDF | Image |
| ------------------------- | ---- | -------- | --- | ----- |
| Entity Specification      | O    | O        | O   | X     |
| ER diagram                | O    | O        | O   | O     |
| ETA Template              | O    | O        | O   | X     |
| Entity Version Management | O    | X        | X   | X     |
| SVG or PNG                | O    | X        | X   | O     |

Markdown, PDF, Image generate document single version. But HTML document contain multiple version.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ypflgz77v4t3nejeiilg.png)

## Template

ERDIA uses the [ETA template engine](https://eta.js.org/) to generate documentation. The reason for using a template engine is that it allows you to customize the documentation the way you want it. If you want to customize documentation that ERDIA generates run the following command.

```bash
npx erdia eject
```

You can find the default template in template directory. Customize you want it. When run it, you'll need to pass the template path as follows to generate a modified document.

```bash
npx erdia build --template-path ./template
```

## TypeScript

If your TypeORM entity is written in TypeScript, you have to run ERDIA using [ts-node](https://typestrong.org/ts-node/) or [tsx](https://github.com/esbuild-kit/tsx) as follows.

```bash
TS_NODE_PROJECT="./tsconfig.json" node \
  -r ts-node/register \
  ./node_modules/erdia/dist/cli.js build -d [your dataSourcePath] --format html -o ./dist/html
```

If you've use a [re-map path](https://www.typescriptlang.org/tsconfig#paths) in your project, you have to pass it up to [tsconfig-paths](https://github.com/dividab/tsconfig-paths) like this,

```bash
TS_NODE_PROJECT="./tsconfig.json" node \
  -r ts-node/register \
  -r tsconfig-paths/register \
  ./node_modules/erdia/dist/cli.js build -d [your dataSourcePath] --format html -o ./dist/html
```

## Conclusion
I generate ERDIA HTML documents during Jenkins build process and deploy them to AWS S3(CDN). This task, I always have an up-to-date Entity specification, ER diagram and can share it with my co-workers.

Good documentation, well managed documentation, improves project productivity. If you're using TypeORM now, I strong recommend adopt [ERDIA](https://github.com/imjuni/erdia)!

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rdyxoxpk89xcnqwqa847.png)