In this post, I am going to cover Angular CLI Budgets in details. So, what are CLI Budgets? CLI Budgets is a way of way of ensuring that your angular final build bundles do not deviate by much from the expected sizes. For instance, if you expected the whole built application size to be 2MB, with a deviation of +/-10% for warning and +/- 20% for errors. You can set this configuration in Angular, so that during the build process, Angular CLI will throw a warning when it deviates by more than 10%  and an error when it deviates by more than 20%. This is what is known as an Angular CLI Budget.

As developers, we are sometimes experimenting with our projects, trying new things. This can result to some unused libraries being left inside our application that can bloat the size of the final built artifacts. With Angular CLI Budgets, you can manage this by ensuring that your production build doesn’t deviate by much from your own expectation.

Please note, Angular CLI Budgets will not determine for you which libraries are causing your project to be over or under budgets. But, it will give you a hint, which you must follow up and investigate. This is where tools such as Webpack Bundle Analyzer and Source Map Explorer can be useful.

Adding CLI Budgets to your App

First, open your angular.json, at the root of your Angular CLI Workspace. Next, we need to add our budget for our environments.

"projects": {
  "angular-cli-budgets-demo": {
    // ...
    "architect": {
      "build": {
        // ...
        "configurations": { // <==== your environments are here
          "production": { // <==== production environment
            // ...
            "budgets": []
          },
          "staging": { // <===== custom staging environment
              // ...
              "budgets": []
          }
        }
      },
 // ...

We will place our budget just below our other environment configurations. Our budget property accepts an array of budgets with the following content:

"budgets": [
  {
     "type": "bundle", //_** type of budget to setup**_
     "name": "main", //_** the name of the bundle to be tested**_
     "baseline": "300kb", //_** the baseline size for comparison**_
     "error": "40%", //_** the deviation from the baseline to trigger error (+/- 40%)**_
     "warning": "30%", //**_ the deviation from baseline to trigger warning (+/- 30%)_**
     "maximumError": "20%", _**// triggers error if size is 20% more than baseline**_
     "maximumWarning": "10%", //_** triggers warning if size is 10% more than baseline**_
     "minimumError": "20%", //_** triggers error if size is 20% less than baseline**_
     "minimumWarning": "10%", //**_ triggers warning if size is 10% less than baseline_**
   }
]

The following types are allowed:

  • bundle – The size of a specific bundle.
  • initial – The initial size of the app.
  • allScript – The size of all scripts.
  • all – The size of the entire app.
  • anyScript – The size of any one script.
  • any – The size of any file.

Setting the Maximum Size Budget

Next, let’s say you didn’t want your built application to be more than a specific size – like 400KB. Let’s add a budget for that and see how it goes:

{
  "type": "all",
  "baseline": "400kb",
  "maximumError": "25%",
  "maximumWarning": "12%"
}

Since our app is small, this doesn’t trigger any errors or warnings as shown below:

Now, let’s lower our baseline to 250KB:

As you can see from the image above, this triggers the following error and warning:

WARNING in budgets, maximum exceeded for total. Budget 307 kB was exceeded by 70.5 kB.

ERROR in budgets, maximum exceeded for total. Budget 358 kB was exceeded by 19.3 kB.

And if we increase the baseline value to 300KBs, it should trigger the warning only, as shown below:

Setting a Deviation from Baseline Budget

Let’s say we want our error to be trigger if the main bundle is 20% large or smaller than the size, and a warning if it’s 10%. Our budget will look like this:

{
  "type": "bundle",
  "name": "main",
  "baseline": "300kb",
  "error": "20%",
  "warning": "10%"
}

Our main bundle is about 250Kb, this should trigger a warning but not an error. This is because the minimum threshold value of 90% of 300Kb (276kb) was not reached but it was reached by the error minimum threshold which is 80% of 300Kb (240kb).

And if we lower our error threshold to 15%, we will trigger both errors:

I hope now you are getting the picture. If we were to lower the baseline from 300kb to 200kb. We should trigger the maximum threshold error and warning instead of the previous minimum threshold error.

Setting Minimum Size Budget

You can also set the minimum size for various output artifacts. An error or warning is triggered if the specified file is less than the minimum size. Let’s modify the above budget and instead set a minimum size instead of a deviation:

{
  "type": "bundle",
  "name": "main",
  "baseline": "300kb",
  "minimumError": "20%",
  "minimumWarning": "10%"
}

And if we build this, it should trigger only a warning and not an error:

If we lower the minimum error from 20% to 15% we should trigger both an error and a warning:

Final Thoughts

I hope this gives you an idea of how to work with Angular CLI Budgets. I steered cleared from dealing with bytes, KBs and Mbs because I found it to be working rather inconsistently when it comes to errors, minimum errors and warning. That said, I found working with percentages to be enough for my work and I would recommend that to anyone.