Guides

Why your build takes forever — 3 causes you can fix in one evening

Illustration: an hourglass beside an assembly line

You change one line of button text. You hit deploy. And you wait eight minutes.

The annoying part is that this usually takes an evening to fix — most people just start at the wrong end. Let's go through the three causes by frequency, but first: measuring, because without it you'll optimise the wrong thing.

The symptom

npm run build or your server build takes minutes even though the project is small. Sometimes it's faster locally than in CI — or the other way round. And it keeps getting worse over time.

Measure where the seconds go first

The classic mistake is "optimising the build" blind. People rip out libraries and rewrite configs when eight of the ten minutes were spent installing dependencies.

Open the build log and look at the timestamps between steps. Practically every CI prints a duration per step, and locally time is enough:

time npm ci
time npm run build

Two numbers and you know where to look. If the first is long, go to cause 1. If the second is, causes 2 and 3.

Cause 1. No dependency cache (the most common)

Locally you install packages once and forget. But the build server starts from a blank slate every time: it downloads hundreds of megabytes of node_modules again on every push. There are your minutes.

How to check. Find the dependency install step in the log and look at its duration. Over a minute and you almost certainly have no cache. Another sign: the log shows packages being fetched from the network rather than restored.

How to fix. Turn on caching keyed by your lock file. In GitHub Actions that's one line in the environment setup:

- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: 'npm'

The cache key is derived from package-lock.json: dependencies unchanged, cache reused; changed, cache rebuilt. Other platforms have their own equivalent — search their docs for "cache." While you're there, check you're calling npm ci and not npm install in CI: it's faster and installs exactly what the lock file says — our piece on npm install errors covers the difference.

If you build through Docker, it's the same cause wearing a different hat: layers cache in order. Copy package.json and the lock file first, install dependencies, and only then copy the rest of the code — that way editing one line of source doesn't invalidate the dependency layer.

Cause 2. You're building things you don't need

Second most common: the bundler dutifully chews through files that never reach the output.

How to check. Compare the size of what goes in against what comes out:

du -sh . --exclude=node_modules
du -sh dist

Hundreds of megabytes in and a couple out means the bundler is reading junk.

How to fix:

  • Exclude the extras. Your .dockerignore (and .gitignore) should list node_modules, .git, the build folder, source images. Without .dockerignore literally everything ships into the image, local node_modules included — slow and pointless.
  • Turn off source maps in production. They're for debugging, they're slow to generate and heavy. In most bundlers that's a single flag.
  • Don't run checks twice. If your linter and tests already ran as their own CI step, there's no reason to bake them into the build as well.

Cause 3. One heavy dependency, or importing the whole library

The third cause is quieter: the build gets slowly heavier as the project grows.

The usual culprit is importing an entire package for one function:

import _ from 'lodash'                // pulls in the whole library
import debounce from 'lodash/debounce' // pulls in one function

The bundler has to process the whole package even if you took one line from it. A couple of imports like that add a minute.

How to check. Look at what takes up space in the output. Most bundlers have a flag or plugin for a bundle-size report; the simplest approach is sorting the output files by size and spotting the unexpectedly fat ones.

How to fix: import the specific thing rather than the package; drop libraries you use one function from (moment, fully imported UI kits are the usual suspects); audit package.json for dependencies you stopped needing long ago.

A separate note for TypeScript: type checking on every build easily eats half your time. Many bundlers can build without it and run type checks as a separate parallel step — that alone nearly halves total time.

If none of that helped

Check whether you're building on the weakest free runner, and whether the build fires several times per push (common when a few workflows are wired together). Sometimes a "slow build" is three builds queued behind each other.

Why is CI slower than my machine?

Because locally you already have a cache, installed dependencies and a warm disk, while CI starts from zero on a weaker machine every time. A 2–3× difference is normal; 10× means no cache.

Does a faster build mean a worse one?

No. Everything above removes wasted work, not quality: a cache doesn't change the result, .dockerignore drops things you didn't need, targeted imports produce the same code. The one deliberate trade-off is source maps — without them production debugging is harder, so many people keep generating them but don't publish them.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →