Integrating Compodoc with Angular 11 — Documenting Angular Application

Though Angular is an amazing framework to develop a web application, there comes a time when the application becomes soo huge that it’s not easy to understand or map the flow of data or how the app is structured from a birds view. This is the case when enterprise apps come into the scope.

I was also a part of team where we faced this issue. As our application got bigger we slowly started loosing control over the bundle size of application which further started impacting page performance and the moment we started debugging the issue we realised that it’s not possible or damn hard to decrease the bundle size or to know how what is causing the performance issues without knowing how the app is structured as a whole.Then after a lots n lots of googling… Here it is… The Saviour “Compodoc”.

Compodoc is sort of a documentation tool for Angular applications. It generates a static documentation of your application which includes modules, components, pipes, guards and many more..

You can directly start with compodoc documentations, but here along with usual installation i’ll go through couple of the bottlenecks which I faced and the fix for it when integrating with an enterprise level application.

Let’s start

• First install compodoc

//Global Installation
npm install -g @compodoc/compodoc
//Local Installation
npm install --save-dev @compodoc/compodoc

• Define a script task for it in your package.json:

Here starts the First bottleneck:

As per documentation we have to do

"scripts": {
  "compodoc": "npx compodoc -p tsconfig.app.json src"
}

But this wont work from angular 9 and above, as the configuration has been shifted from tsconfig.app.json to tsconfig.base.json

So, now this is what you have to do

"scripts": {
  "compodoc": "npx compodoc -p tsconfig.base.json src"
}

Now everything is setup, it’s time to run.

npm run compodoc

And Voila!! it’s starts compiling the app.

And Suddenly here is the Second bottleneck

JavaScript heap out of memory

Solution:

For windows user: Replace the script with

"scripts": {
  “compdoc”: “npx compodoc — max_old_space_size=20480 -p tsconfig.base.json -s”
}

For Mac users: Just run the following command before executing compodoc (it’s same for Linux i believe, but never tested)

export NODE_OPTIONS=--max-old-space-size=8192
npm run compodoc

And as soon as you run this, it takes a bit time (depends on your system specifications and the size of your project) to compile all files and as soon as its done you’ll get a localhost address where you can see the entire documentation.

compodoc localhost url

and the documentation will look somewhat like this:

Source - https://compodoc.app/guides/demo.html

That’s all, from here you can analyse all the packages, modules, components, classes and many more and get a proper picture of how your application is structured and you can make decisions on how to move forward in terms of improving you applications size and performance.

What I did after going through the documentation:

• Came up with more optimised way to modularize couple of components eventually making the app load faster.
• Found few unused modules and components which were not being used anymore, just adding a dead weight to size of application for no reason.

You can do a lot more with compodoc you can go through rest of the documentation in https://compodoc.app/guides/demo.html