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 | 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 </span>
-r ts-node/register </span>
-r tsconfig-paths/register </span>
./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!
Top comments (0)