ERDIA: TypeORM entity specification documentation tool

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, 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 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.

The image above is a chart comparing three popular ORM tools from the npmtrends.com. ERDIA only supports TypeORM for now, but the roadmap is to support Sequelize and Prisma as well.

Getting Started

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

npm i erdia --save-dev

And then, I recommend running the initialization command.

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.

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.

Template

ERDIA uses the ETA template engine 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.

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.

npx erdia build --template-path ./template

TypeScript

If your TypeORM entity is written in TypeScript, you have to run ERDIA using ts-node or tsx as follows.

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 in your project, you have to pass it up to tsconfig-paths like this,

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!