Every kilobyte of JavaScript in your initial bundle has to be downloaded, parsed and executed before the app can respond to the user. On a fast laptop that's invisible; on a mid-range phone over a mobile connection, a bloated bundle is the difference between an app that feels instant and one that feels broken. The good news is that most bundle bloat comes from a handful of predictable causes, and the Angular build tells you exactly where it is if you know how to ask.

This is lesson 8.5 of the Angular Tutorial. Lesson 8.4 made images load efficiently; this one does the same for your JavaScript. You'll read the build output, generate a bundle map, find what's large and why, fix tree-shaking blockers, move code out of the initial bundle with lazy routes and @defer, and set budgets so the bundle doesn't quietly grow back.

Read the build output first #

Run a production build:

ng build

The Angular CLI's application builder (esbuild and Vite, the default since Angular 17) prints two tables:

Each row shows a raw size and an estimated transfer size (compressed). Raw size is roughly what the browser has to parse and execute; transfer size is what goes over the network. Watch both, but the initial total is your headline number.

Generate a bundle map #

The tables tell you how big, not why. For that, ask the build for its dependency graph:

ng build --stats-json

With the esbuild-based builder this writes stats.json, an esbuild metafile, into your output folder. Drop it into the esbuild bundle analyzer (esbuild.github.io/analyze) to get a treemap of every module in every chunk, with sizes. Webpack-era tools like webpack-bundle-analyzer don't understand this format; use the esbuild analyzer instead.

A second, builder-independent view comes from source maps:

ng build --source-map
npx source-map-explorer "dist/my-app/browser/*.js"

source-map-explorer attributes every byte of the output back to the source file it came from, which is useful for answering "how much of main.js is really my code?"

The usual suspects #

Open the treemap and look at the biggest rectangles in the initial chunks. In most Angular apps, the culprits are some mix of these:

Make tree-shaking work for you #

Tree-shaking removes code that's imported but never used. esbuild does it well, but only when the code allows it:

• ES modules only. Tree-shaking relies on static import/export. CommonJS modules (require, module.exports) can't be analysed, so the whole module ships. The build warns about CommonJS dependencies; treat those warnings as a to-do list, not noise. Silence one (via allowedCommonJsDependencies) only after deciding it's acceptable.
• Import precisely. import { debounce } from 'lodash-es' ships one function; import _ from 'lodash' ships the whole library.
• Tree-shakable providers. Services declared with providedIn: 'root' are only bundled if something injects them. Registering a service in a providers array bundles it even if nothing uses it.
• Avoid side effects at module level. Code that runs when a module is imported (registering globals, patching prototypes) forces the bundler to keep that module. Keep module top levels to declarations.
• Beware re-exporting barrels in libraries you control: a barrel file that also contains side effects can pull everything it re-exports into the bundle.

Move code out of the initial bundle #

Removing code is best; deferring code you still need is next best.

Lazy routes split whole features off:

// app.routes.ts
export const routes: Routes = [
  { path: '', component: Home },
  { path: 'reports', loadComponent: () => import('./reports/reports').then(m => m.Reports) },
  { path: 'admin', loadChildren: () => import('./admin/admin.routes').then(m => m.ADMIN_ROUTES) },
];

@defer splits off parts of a page, which is perfect for heavy widgets below the fold:

<app-order-summary [order]="order()" />

@defer (on viewport) {
  <app-sales-chart [data]="history()" />     <!-- chart library loads only when scrolled into view -->
} @placeholder {
  <div class="chart-skeleton"></div>
}

Everything referenced only inside the @defer block, including the chart component and the charting library it imports, moves into a lazy chunk. Lesson 5.6 covers the triggers (on viewport, on idle, on interaction, prefetch) in depth.

Dynamic import() handles the rest, such as a library needed only after a button click:

async exportPdf() {
  const { jsPDF } = await import('jspdf');   // downloaded on first use
  new jsPDF().text('Report', 10, 10).save('report.pdf');
}

Set budgets so it stays fixed #

Bundle size creeps back one dependency at a time. Budgets in angular.json turn that creep into a build warning or error:

"budgets": [
  { "type": "initial", "maximumWarning": "500kB", "maximumError": "1MB" },
  { "type": "anyComponentStyle", "maximumWarning": "4kB", "maximumError": "8kB" }
]

These are the values new projects start with. Once you've slimmed your bundle, tighten the initial budget to just above your current size, so the next heavy import fails the build and gets a conversation instead of slipping into production. Budgets also accept types like anyScript and bundle (with a name) for finer control.

A repeatable workflow #

1. ng build and note the initial raw and transfer totals.
2. ng build --stats-json and open the treemap; list the five biggest items in the initial chunks.
3. For each: remove it, replace it with something smaller, import it precisely, or defer it.
4. Rebuild and compare the totals. Keep changes that measurably help.
5. Tighten the initial budget to lock in the gain.

Do this per release, or whenever a dependency is added. It takes minutes, and it's much easier than untangling a year of growth.

Gotchas #

What's next #

Lesson 8.6 brings images, JavaScript and rendering together under Core Web Vitals: measuring LCP, INP and CLS for a single-page app, the difference between lab data (Lighthouse) and field data (CrUX), and Angular-specific fixes for each metric.

Try it yourself #

Run ng build --stats-json on a real project, open the treemap, and write down the five largest modules in the initial chunks. Move one heavy, below-the-fold component into a @defer (on viewport) block, rebuild, and compare the initial totals. Then set your initial budget to 10% above the new size.