intermediate30 minby DevFox

Building and Bundling

Compiling versus bundling, emitting declaration files, source maps that make production stack traces readable, and choosing an output that suits who consumes it.

TypeScript
Tooling

A production error arrives:

text

TypeError: Cannot read properties of undefined
    at t (/app/dist/index.js:1:48213)

One line, column 48213, in a file that is entirely one line. The code that failed is somewhere in three hundred kilobytes of minified output, and nothing connects it back to what you wrote.

Building is where source becomes something you ship, and the decisions made there determine whether an incident like that takes five minutes or an afternoon. By the end of this lesson you will know what the compiler emits, what a bundler adds on top, and which settings decide whether a stack trace is usable.

Two different jobs

Compiling

One file in, one file out.

TypeScript to JavaScript, with your directory structure preserved. That is all tsc does.

For a Node library or a small service it is often all you need.

Bundling

Many files in, a few files out.

Resolution, minification, tree-shaking and asset handling on top of the compile.

Required for the browser, where hundreds of separate module requests would be unusable.

Two jobs, often done by two different tools, and a project can genuinely need only the first

Most modern build tools do not type-check. esbuild, swc and Vite strip types and emit, exactly as tsx did in the foundations course:

json

{
  "scripts": {
    "check": "tsc --noEmit",
    "build": "vite build"
  }
}

Both in CI. A successful build says nothing about type correctness, which surprises people the first time a broken type reaches production through a green pipeline.

The settings that shape output

json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "outDir": "dist",
    "rootDir": "src",
    "sourceMap": true,
    "declaration": true,
    "declarationMap": true
  }
}

target decides how much your code is rewritten. A lower target means older syntax and more transformation — async functions become state machines, class fields become constructor assignments. Set it to the oldest runtime you support and no lower, because every step down produces larger, slower output.

declaration emits .d.ts files. Required for a library; pointless for an application.

declarationMap links those back to your source, so a consumer's go-to-definition lands in your actual code rather than a declaration file.

Source maps decide the incident

Bad — shipping without them.

Good — generated, and available to whatever reads the trace.

A source map records which output position came from which source position. Without one, a minified trace names a single-character function at a column number, and finding the real line means reverse-engineering the bundle.

For a Node service, sourceMap: true plus --enable-source-maps is the whole answer:

For the browser, do not publish maps publicly — they contain your full source. Upload them to your error tracker instead, which is a standard step in every such tool:

This is the highest-value line in this lesson. It costs a build flag and converts an unreadable trace into a file and a line number.

Building a library

Different from an application in three ways.

Do not bundle dependencies. A library that inlines its dependencies means a consumer gets two copies of whatever else they already had. Mark them external:

Do not minify. Consumers minify, and unminified code makes their debugging possible.

Ship types, and both formats if you must. The exports map from the modules lesson, with types first in each block:

files limits what is published. sideEffects: false tells bundlers that importing a module does nothing on its own, which is what makes tree-shaking possible for your consumers — and is a lie if any module runs code at import time.

Dual-format publishing is worth avoiding when you can. It doubles your build and creates the dual-package hazard from the modules lesson, where one process loads both copies.

Making the output smaller

Three things that actually matter for a browser bundle.

Tree-shaking removes exports nobody imports. It requires ESM — a bundler cannot statically analyse require — and it is defeated by side effects at module top level, which is what sideEffects: false is asserting.

Code splitting loads what a page needs, when it needs it:

A dynamic import() becomes a separate chunk. A charting library nobody opens should not be in the initial download.

Measure before optimising, which is the profiling lesson applied here:

The result is nearly always one dependency far larger than expected — a date library where three functions were needed, an icon set imported whole. Guessing which one wastes the afternoon; the visualiser names it in seconds.

Reproducible builds

Two habits, both cheap.

Install from the lock file. npm ci fails if package-lock.json and package.json disagree, and installs exactly what is locked. npm install may resolve something newer, which means the artefact you tested is not the one you ship.

Build once, deploy that. Rebuilding per environment gives each one a different artefact from the same commit. Build in CI, store the output, and promote the same files through staging to production.

Environment differences then belong in configuration, read at runtime — which is the validated-at-startup pattern from the foundations course rather than a build-time substitution.

A cheat sheet to keep

Where to go next

You can now produce output suited to what consumes it, and — the part that matters at 3am — connect a production stack trace back to the line you wrote. Source maps plus --enable-source-maps is a two-line change with a return that is hard to overstate.

Next is Runtime Versus Compile Time, which makes explicit something this course has circled repeatedly. Types are erased before the program runs, and knowing exactly what survives explains a whole family of surprises — including several you have already met.

Before you move on, check whether your production build emits source maps and whether whatever reads your errors can use them. In a surprising number of projects the answer is that maps are generated and nothing consumes them, which is all of the cost and none of the benefit.