esbuild & Turbopack Workflows

Modern frontend build systems have moved from plugin-heavy, JavaScript-driven architectures to native-compiled, parallel execution engines. The shift prioritizes deterministic graph resolution, sub-second cold starts, and memory-efficient incremental updates. For engineers maintaining application toolchains, the practical question is no longer “which bundler is fastest” but “where does the Go-native throughput of esbuild end and the Rust-native incrementalism of Turbopack begin, and how do you wire remote caching across both.” The guides below cover pipeline orchestration, benchmark-driven configuration, version pinning, and the production trade-offs that decide whether a build stays under 500ms cold or drifts into multi-second rebuilds.

The reason this split exists at all is historical. The first generation of JavaScript bundlers — Browserify, then webpack — were written in JavaScript and ran the entire dependency graph through a single-threaded event loop. Every module was parsed, pushed through a chain of loaders, and re-serialized in one process, and the plugin ecosystem that made webpack ubiquitous is exactly what capped its throughput: a Babel pass over a five-thousand-module graph is thousands of round trips through user-land JavaScript. Native-compiled engines break that ceiling in two different directions. esbuild attacks the constant factor by rewriting the whole pipeline in Go and parallelizing it across cores; Turbopack attacks the algorithmic factor by never redoing work whose inputs did not change. Understanding which of those two wins for a given workload is the whole game, and it is why “which bundler is fastest” is the wrong question — the honest answer is always “fastest at what, on which change.”

The failure you are trying to avoid is the slow feedback loop. On a large app, a dev server that takes twenty seconds to boot and two seconds to reflect a one-line edit is not a minor annoyance; it changes how engineers work, pushing them toward larger, less frequent edits and longer debugging cycles. The cost is real but diffuse, which is why it survives in codebases for years without anyone filing a bug. A native engine that boots in under a second and patches the browser in under a hundred milliseconds keeps the edit-run-observe loop tight enough that a developer stays in flow. Every configuration decision below is ultimately in service of that latency budget, and every gotcha is a way that budget silently blows out.

Where these tools sit in the pipeline matters as much as which one you pick. esbuild is rarely the whole build; it is a transform stage embedded inside Vite, tsup, Remix’s compiler, or a bespoke CLI. Turbopack is the dev-time engine for Next.js and, increasingly, a standalone bundler. Neither is a drop-in replacement for a webpack production build with a mature plugin graph, and treating them as one is how teams end up with subtly wrong output — missing polyfills, broken tree-shaking, or CSS ordering that only diverges under production minification. Read each guide below with the pipeline position in mind: the same engine behaves differently as a dev transform than it does as the final packager, and most of the pain in this space comes from assuming those two roles are interchangeable.

esbuild API & CLI for rapid builds

esbuild (v0.25.x) is written in Go and runs lexing, parsing, and minification across OS threads with a lock-free architecture. The compiled binary executes directly without a Node bridge, which is why cold starts stay under 500ms on medium-to-large codebases. It deliberately trades deep AST-transformation fidelity for raw throughput: there is no Babel-style plugin pass over the tree, only a fixed set of transforms exposed through the build, transform, and context APIs. The esbuild API and CLI for rapid builds guide covers when to reach for the JS API versus the CLI, and how context() watch mode keeps the process warm for incremental rebuilds instead of re-spawning per change.

A baseline browser build pins an explicit target and emits linked source maps so the binary never falls back to a permissive default:

// build.mjs — esbuild 0.25.x, Node 20+
import * as esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  target: ['chrome110', 'firefox110', 'safari16'],
  platform: 'browser',
  sourcemap: 'linked',
  minify: true,
  outdir: 'dist',
});

The cost of running a compiled Go binary is cross-platform distribution: CI runners on ARM need the matching @esbuild/linux-arm64 optional dependency, and a mismatched lockfile surfaces as Cannot find module '@esbuild/...' at install time. Pin the binary version and audit it in the same lockfile that ships to production.

Under the hood, the reason a native loader is fast and a plugin is not comes down to the threading model. esbuild’s build runs as a set of Go goroutines scheduled across every available core; parsing, scope analysis, and printing all happen without a global lock. A built-in loader is just another Go code path that stays inside that model. A JavaScript plugin, by contrast, has to marshal the file contents out of the Go process, across a serialization boundary, into the Node runtime, run your callback, and marshal the result back. That round trip is cheap once and ruinous ten thousand times, and because plugin callbacks can be asynchronous, esbuild has to hold the dependent work until they resolve. The practical rule is that anything you can express as a target, a define, or a built-in loader belongs in the config, and only genuinely dynamic logic belongs in a plugin.

The context() API deserves more attention than it usually gets, because it is what separates a one-shot CLI invocation from a real dev server. build() spins up the engine, produces output, and tears everything down; if you call it on every file change you pay the process-startup cost each time. context() creates a long-lived build object whose rebuild() reuses the parsed module graph and only re-reads the files that changed on disk. Watch mode and the built-in dev server are both layered on top of it. The following pattern is the correct shape for an incremental build loop:

// watch.mjs — esbuild 0.25.x, Node 20+
import * as esbuild from 'esbuild';

const ctx = await esbuild.context({
  entryPoints: ['src/index.ts'],
  bundle: true,
  target: ['chrome110'],
  sourcemap: 'linked',
  outdir: 'dist',
});

// Rebuilds reuse the warm graph; only changed files are re-read.
await ctx.watch();

// Optional: serve dist/ with live reload on a fixed port.
const { host, port } = await ctx.serve({ servedir: 'dist' });
console.log(`serving on http://${host}:${port}`);

Getting the target wrong is the most common correctness bug in an esbuild config, not a performance one. If you omit target, esbuild assumes the newest syntax everything supports and emits, for example, native class fields and optional chaining untouched. That output runs fine in your local Chrome and then throws a SyntaxError on an older Safari or an embedded webview in production. The symptom is a blank page with a parse error in a browser you never tested; the root cause is a permissive default target; the fix is to pin the oldest engines you actually support; and the way to confirm it is to grep the emitted bundle for the syntax you expected to be down-leveled. Treat target as a contract with your support matrix, not a performance knob you can leave unset.

Custom loaders & asset handling

Native bundlers excel at JavaScript and TypeScript but applications also carry CSS, images, fonts, and WebAssembly. esbuild’s built-in loaders (dataurl, file, binary, text, base64) copy or inline resources by extension without an AST pass, which is the fastest path. The moment a transform needs custom logic — say, optimizing an SVG before inlining it — you fall back to a JavaScript plugin via onResolve/onLoad, which reintroduces Node-bridge latency. The custom loaders and asset handling guide walks through keeping the hot path native and reserving plugins for genuinely dynamic transforms, including writing an esbuild plugin for inline SVG imports.

// build.mjs — esbuild 0.25.x
import * as esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  loader: {
    '.svg': 'dataurl',
    '.wasm': 'binary',
    '.png': 'file',
  },
  assetNames: 'assets/[name]-[hash][ext]',
  outdir: 'dist',
});

Benchmark any plugin loader against the equivalent native loader before shipping it. A JS onLoad callback that runs synchronously on every matched file serializes the otherwise-parallel build and is the most common cause of a “fast” bundler suddenly taking seconds.

The hashing in assetNames: 'assets/[name]-[hash][ext]' is worth understanding because it drives your caching story downstream. esbuild computes the hash from the file’s contents, so an unchanged asset keeps its filename across builds and a CDN or browser cache keeps serving it; a changed asset gets a new hash and busts the cache automatically. This is content-addressing at the asset level, and it is why you should never hand-roll query-string cache-busting on top of it. The gotcha is that the hash covers only the bytes esbuild sees: if a plugin rewrites an asset non-deterministically — embedding a build timestamp, say — the hash changes on every build and you lose the cache entirely. Keep asset transforms deterministic for the same reason you keep cache inputs hermetic.

Choosing between dataurl and file is a size trade-off, not a style preference. dataurl inlines the asset as a base64 string directly in the JavaScript, which removes a network request but inflates the bundle by roughly a third of the asset’s size and makes it uncacheable independently of the code. file emits a separate hashed file and leaves a URL reference, which costs a request but lets the asset cache on its own lifecycle. The crossover point in practice is a few kilobytes: tiny icons and single-color SVGs are worth inlining; anything a user might see cached across sessions should be a file. Setting this per-extension in the loader map, as the block above does, is the right granularity — do not reach for a plugin to make a decision a static config already expresses.

When you genuinely need a plugin, scope its onLoad filter as tightly as possible. A filter of /\.svg$/ that matches every SVG in node_modules will run your callback thousands of times; a filter that also checks a namespace or a path prefix runs it only where you meant. The symptom of a too-broad filter is a build that is fast on a clean checkout and slowly degrades as dependencies accrete assets you never intended to transform. The root cause is that filters match the whole module graph, not just your source; the fix is to narrow the regex and gate on namespace; and you confirm the blast radius by logging the paths your onLoad actually receives before you optimize anything else.

Integrating esbuild with framework toolchains

Most frameworks run a hybrid pipeline: Vite uses esbuild for dependency pre-bundling and TypeScript stripping in dev, then hands production bundling to Rollup; Next.js uses Turbopack as the default dev engine. Maintaining a consistent developer experience means aligning module resolution, path aliases, and environment-variable injection so the dev transform and the production bundle resolve the same graph. The classic failure is a tsconfig paths entry honored by one tool and ignored by the other, producing Could not resolve "@/..." only in CI. The integrating esbuild with framework toolchains guide covers aliasing parity and the common migration of replacing babel-loader with esbuild in a CRA project to drop the Babel transform from the dev loop.

For monorepos the hard part is workspace boundary traversal: dependency hoisting, peer-dependency resolution, and node_modules layout must match between the dev server and the CI build, or you get missing exports and hydration mismatches that reproduce only on the runner. Enforce strict version pinning on the compiler binaries and audit the lockfile to prevent drift.

The mechanism behind the “honored by one tool, ignored by the other” alias failure is that tsconfig.json paths is a TypeScript type-resolution feature, not a runtime module-resolution feature. TypeScript uses it to type-check imports, but Node, esbuild, and Rollup each need to be told about it separately — through a resolve.alias map, an esbuild alias option, or a plugin like vite-tsconfig-paths. When the dev transform reads the aliases and the production bundler does not, every @/… import type-checks and runs in dev, then fails to resolve in the CI production build with a bare Could not resolve error. The fix is to derive both tools’ alias config from a single source — ideally generating the bundler alias map from tsconfig at build time — so the two can never drift apart. Confirm parity by building for production locally with a freshly installed node_modules, which reproduces the CI resolver rather than your warm dev graph.

Environment-variable injection is the second parity trap. esbuild replaces process.env.X through define, statically, at transform time; a framework’s production bundler may instead expose variables through a runtime shim or a different prefix convention (Vite’s import.meta.env, Next’s NEXT_PUBLIC_). If a value is defined on one path and not the other, a feature flag reads true in dev and undefined in production, and the bug ships silently because nothing throws. The discipline is to route every build-time constant through one injection mechanism and to fail the build when a referenced variable is missing rather than letting it default to undefined. Confirm it by grepping the production bundle for the literal you expected the constant to be replaced with; if you find process.env still present, the replacement did not run.

Turbopack incremental compilation

Turbopack (stable in Next.js 15) is implemented in Rust on the Turbo engine, a fine-grained task-graph runtime. Instead of bundling whole files atomically, it tracks dependencies at the module — and in many cases expression — level, and re-runs only the tasks whose inputs changed. A disk-backed cache serializes the graph so a warm dev server reaches HMR feedback under 100ms even across thousands of modules. The trade-off is memory: a live in-memory graph for instant invalidation is RAM-hungry, especially with source maps enabled, so set sourcemap: 'external' and align cache eviction with session lifecycles. The Turbopack incremental compilation guide details cache warming, invalidation scoping, and configuring the Turbopack cache for Next.js projects.

When invalidation misbehaves — a stale module served after an edit, or a resolution error that survives a restart — the cause is usually a cache key that does not capture a config input. Treat the cache key as the source of truth: if a change does not move the key, the engine will not recompute it.

The task graph is the mental model that makes Turbopack’s behavior predictable. Every unit of work — reading a file, parsing a module, resolving an import, generating a chunk — is a cacheable function of its inputs, and the engine memoizes the result keyed on those inputs. When you edit a file, the engine invalidates only the tasks that read that file and, transitively, the tasks that depended on their outputs. If your edit changed a function body but not the module’s exported signature, the invalidation stops at the module boundary and nothing downstream recompiles. This is why HMR latency stays roughly flat as the graph grows: the work is proportional to the size of the change, not the size of the project. The corollary is that a change which touches a widely imported module — a shared type barrel, a root layout — fans out to many tasks and feels slow, and that is the algorithm working as designed, not a regression.

The memory cost is the price of that in-memory graph, and it is the single most common Turbopack operational problem. Every memoized task result lives in RAM for instant invalidation, and source maps roughly double the retained size per module because the mapping tables are large. On a big app a dev server can climb past several gigabytes and eventually approach Node’s heap limit, at which point the server either crashes or falls back to slow full recompiles. The symptom is a dev server that starts snappy and degrades over hours; the root cause is unbounded graph retention plus source-map bloat; the fix is to set source maps to 'external' so the maps are written to disk instead of retained, and to restart on a session boundary rather than leaving the server running for days. Confirm the improvement by watching RSS over a working session: a healthy server plateaus, a leaking one climbs monotonically.

The invalidation bugs — a stale module served after you clearly edited it — almost always trace to an input the cache key does not capture. A common example is a value read from a .env file or a config module that Turbopack does not treat as a tracked input; you change it, the key does not move, and the engine happily serves the memoized result. The way to reason about this is to treat the cache key as the definition of “what this build depends on.” If editing something does not change behavior, either the key is missing that input or you are editing the wrong file. Deleting the on-disk cache directory is the blunt confirmation: if a full cold rebuild picks up the change, the key was the problem, and the real fix is to declare the missing input rather than to clear the cache on every run.

Remote caching & distributed build coordination

A local engine cache only helps the machine that produced it. Teams running the same build across many CI jobs and many developers want a shared, content-addressed cache so the first machine to compute an artifact uploads it and every subsequent machine replays it. The cache key is a hash of source, config, and toolchain version; a clean checkout that matches an existing key skips the build entirely. The remote caching and distributed build coordination guide covers cache-key hygiene, hermetic inputs, and security boundaries on a shared cache, including a worked setup for configuring a remote cache with Turborepo and Vercel.

The failure mode that erodes trust in a remote cache is a non-hermetic input: an absolute path, a timestamp, or a machine-specific environment variable that leaks into a task’s output but not its key. The result is a cache hit that replays the wrong artifact. Audit task inputs and outputs so every byte of the result is a deterministic function of the hashed inputs.

Content-addressing is what makes a shared cache safe to trust, and it is worth being precise about the mechanics. Each task declares its inputs — source files, config, environment variables, the toolchain version — and the cache key is a hash over all of them. Before running a task, the orchestrator computes the key and asks the remote cache whether an artifact with that key already exists. A hit downloads the artifact and its captured logs and skips execution entirely; a miss runs the task, uploads the resulting outputs under the key, and the next machine to compute the same key gets a hit. The economics are compelling on a monorepo: a package whose inputs did not change between two CI runs is never rebuilt, and a teammate who pulls a branch someone already built downloads the artifacts instead of compiling them.

The hermeticity requirement follows directly. Because a hit replays a previously captured output byte-for-byte, any input that affects the output but is not in the key produces a wrong-artifact hit — the worst kind of caching bug, because it is silent and non-deterministic. The usual culprits are absolute paths baked into a bundle, a build timestamp, a machine hostname, or an environment variable read at build time but never declared as a task input. The discipline is to enumerate every task’s real inputs and outputs and make the output a pure function of the declared inputs. Confirm it the hard way: build the same commit on two different machines with cleared caches and diff the outputs; if they differ, you have a non-hermetic input to hunt down, and the diff usually points straight at it.

Security is the other boundary a shared cache introduces. A remote cache is a write path that many machines can populate, so a poisoned artifact uploaded by a compromised runner would be replayed by everyone who hits the key. Scope write access to trusted CI, keep pull-request builds read-only against the shared cache, and sign or verify artifacts where the platform supports it. Treat the cache as part of your supply chain, because functionally it is: a cache hit ships code you did not compile on the machine that shipped it, which is convenient right up until the moment the thing you replayed is not the thing you thought you built.

esbuild & Turbopack version compatibility

Both engines pin hard to Node and toolchain versions, and the matrix shifts every minor release. esbuild’s binary ships per platform/arch and must match the host Node ABI expectations at install; Turbopack’s stability and feature set are coupled to the Next.js version that vendors it. Before an upgrade, check the esbuild & Turbopack version compatibility reference for the supported Node ranges, known breaking changes, and the optional-dependency pins that prevent install-time resolution failures on ARM CI agents.

The two coupling models fail in different ways and deserve different upgrade rituals. esbuild’s per-platform binary is distributed as a set of optional dependencies — @esbuild/darwin-arm64, @esbuild/linux-x64, and so on — and the main package selects the right one at install based on the host. The failure mode is a lockfile generated on one architecture that omits the optional dependency another architecture needs; the install then throws Cannot find module '@esbuild/linux-arm64' on the ARM runner even though it worked on the developer’s laptop. The fix is to generate the lockfile with every platform’s optional dependencies present and to pin the esbuild version exactly so the binary and its JavaScript wrapper never mismatch — a mismatch there produces the cryptic Host version does not match binary version error, which no amount of reinstalling fixes until the versions are actually aligned.

Turbopack’s coupling is entirely to Next.js: you do not install or upgrade Turbopack independently, you get whatever version the Next.js release vendors. That makes the upgrade unit the Next.js version, and it means a Turbopack fix or regression arrives only through a Next.js bump, carrying everything else that bump includes. The practical consequence is that you cannot cherry-pick a Turbopack fix; you evaluate the whole Next.js release. Before adopting a new minor, check the release notes for Turbopack-specific behavior changes — cache-format changes in particular force a cold rebuild on first boot after the upgrade, which looks like a performance regression until the cache repopulates and everyone panics for the wrong reason. Pin the Next.js version and stage the upgrade through CI before it reaches developer machines.

Decision matrix: esbuild vs Turbopack vs Rollup/Vite

Development speed does not guarantee production efficiency, and no single engine wins on every axis. esbuild minifies and scope-hoists aggressively, but its tree-shaking operates at the module level, not the expression level, so shared utility modules retain exports when sideEffects annotations are missing. Rollup remains the standard for production tree-shaking because of its deeper static analysis and explicit package.json sideEffects handling — which is exactly why Vite pairs esbuild for pre-bundling with Rollup for production output. Pick by the dominant constraint:

For the production-bundling and tree-shaking depth that Rollup and Vite bring, see the Vite configuration ecosystem and the broader core concepts of modern bundling. Teams targeting a 30%+ production payload reduction typically run a hybrid: esbuild or Turbopack for iteration, Rollup for the optimized output.

The tree-shaking distinction in that table is the one that most often surprises teams, so it is worth spelling out. esbuild’s dead-code elimination works at the level of whole modules and top-level statements: if a module is imported but one of its named exports is never referenced, esbuild can drop that export only when it can prove the module has no side effects. Absent a "sideEffects": false annotation in package.json, esbuild conservatively keeps the code, because evaluating the module might do something observable. Rollup performs deeper cross-module analysis and honors the same sideEffects field, which is why a library bundled through Rollup routinely ships a smaller payload than the same library through esbuild. This is not esbuild being careless; it is a deliberate throughput-for-precision trade, and it is exactly why Vite uses esbuild to pre-bundle dependencies for dev speed and Rollup to produce the optimized production output.

There is a decision the table cannot make for you: whether the fidelity gap between your dev engine and your production engine is acceptable. A hybrid pipeline that transforms with esbuild in dev and bundles with Rollup in production means the code you debug is not byte-for-byte the code you ship. Most of the time the difference is invisible, but it surfaces exactly where it hurts — a module that Rollup tree-shakes away but esbuild keeps, a CSS ordering that diverges under production minification, a polyfill injected on one path and not the other. If you cannot tolerate that gap, the answer is to run the same engine in both modes and accept slower dev or slower prod; the direction the ecosystem is moving is precisely to erase the gap by making one Rust engine serve both.

Performance & observability

Bundler orchestration is an operations problem once it leaves a laptop. Instrument the build before optimizing it. esbuild’s --metafile emits a JSON record of every input, output, and import, which feeds bundle-analysis tooling and per-module size budgets; Next.js exposes Turbopack trace logging for compilation latency and module counts. Track three signals over time: cold-start duration, HMR latency distribution (watch the tail, not the median), and remote-cache hit ratio. A falling hit ratio usually means a cache key absorbed a noisy input and is now missing on every run.

In CI, enforce NODE_ENV=production, target the runner architecture explicitly (GOOS/GOARCH for esbuild’s binary selection, the matching Rust target for Turbopack), and warm the cache during dependency installation rather than at first build. Wire a bundle-size regression threshold into PR checks so a stray import that doubles a chunk fails review instead of shipping. Validate production output with Lighthouse CI or WebPageTest to keep minification and splitting aligned with Core Web Vitals.

Reading an esbuild metafile is a concrete skill worth having. The JSON it emits has two top-level keys, inputs and outputs; each output lists the inputs that contributed to it and their byte contributions, which lets you attribute chunk size to specific modules rather than guessing. The workflow is to emit the metafile, load it into an analyzer or a size-budget script, and diff it between builds so a dependency that quietly doubles a chunk shows up as a number rather than a hunch. Wire that diff into CI and a stray import * as _ from 'lodash' that pulls the whole library becomes a failing check instead of a payload nobody notices for a quarter.

// analyze.mjs — esbuild 0.25.x, Node 20+
import * as esbuild from 'esbuild';
import { writeFileSync } from 'node:fs';

const result = await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  minify: true,
  metafile: true,
  outdir: 'dist',
});

writeFileSync('meta.json', JSON.stringify(result.metafile));

// analyzeMetafile() renders a text breakdown of size by input.
const report = await esbuild.analyzeMetafile(result.metafile);
console.log(report);

Watching the tail of the HMR distribution rather than the median is the non-obvious part of the observability story. The median HMR latency stays low almost by construction — most edits touch a leaf module and patch instantly — so it tells you nothing about the edits that actually frustrate developers. The regressions live in the tail: the p95 edit that touches a shared module and fans out, or the first edit after a cache eviction. Track the distribution, alert on the p95, and when it rises look for a newly widened dependency — a barrel file that now re-exports the world, or a type import that dragged a runtime dependency into the graph. The median will look fine the entire time the experience degrades, which is exactly why the median is the wrong thing to dashboard.

Future trajectory

The native-bundler space is consolidating on Rust. Turbopack is on a path to general stabilization beyond Next.js as a standalone bundler. Rolldown — a Rust Rollup-compatible bundler from the Vite team — aims to replace the esbuild+Rollup split inside Vite with a single engine, removing the dev/prod fidelity gap that the hybrid pipeline papers over. Oxc (the Oxidation Compiler) is building a Rust parser, resolver, transformer, and linter that several of these tools share, which is what makes the consolidation feasible. esbuild itself continues as a focused, stable transform engine rather than chasing feature parity. Plan upgrades assuming the dev/prod engine boundary narrows: the hybrid pipelines documented here are a transitional state, not a permanent architecture.

Implementation checklist

• Pin exact esbuild and Turbopack/Next.js versions and audit them in the lockfile that ships to production.
• Include the platform optional dependencies (@esbuild/linux-arm64 and peers) so ARM CI runners install cleanly.
• Set explicit target environments; never rely on the permissive default.
• Keep asset handling on native loaders; reserve JS plugins for genuinely dynamic transforms and benchmark each one.
• Use sourcemap: 'external' on long-running Turbopack dev servers to cap memory.
• Make every cache input hermetic so remote-cache hits replay correct artifacts.
• Emit --metafile / Turbopack traces and track cold start, HMR tail latency, and cache hit ratio.
• Gate PRs on a bundle-size regression threshold and validate production output against Core Web Vitals.

When a native bundler is the wrong choice

Native speed is not free of constraints, and there are workloads where reaching for esbuild or Turbopack costs you more than it saves. The clearest case is a build that leans on a deep webpack plugin ecosystem — module federation, a bespoke chain of loaders that mutate the AST, or a framework whose production output is defined by its webpack config. Porting that to a native engine is not a config change; it is a reimplementation, and the parts that do not port cleanly are exactly the parts nobody documented. If the plugin graph is load-bearing and stable, the throughput win rarely justifies rebuilding it, and a partial port that silently drops a transform is worse than the slow build you started with.

The second case is a build whose correctness depends on precise, expression-level tree-shaking of a library you ship to others. esbuild’s module-level elimination is fine for application bundles where the whole graph is consumed, but if you publish a package and your consumers pay for every byte you leave in, Rollup’s deeper analysis is the right tool and esbuild is a false economy. The third case is any pipeline where the fidelity gap between a fast dev transform and a different production bundler is unacceptable — a payments flow, a heavily polyfilled legacy target, anything where “works in dev, breaks in prod” is a serious incident rather than an annoyance. In those pipelines, run one engine end-to-end even if it is slower, because a consistent slow build beats a fast build you cannot trust.

The honest framing is that native bundlers optimize iteration latency, and iteration latency is only sometimes the binding constraint. When your bottleneck is production payload size, plugin compatibility, or output determinism, the fast engine solves a problem you do not have while quietly introducing one you do. Pick the engine that matches the constraint that actually hurts, not the one with the best benchmark.

Debugging a native build that got slow

When a native build that used to be fast starts dragging, work the pipeline in order rather than guessing. Start by confirming whether the regression is in cold start or in incremental rebuild, because they have different causes. A slow cold start points at the up-front graph work — a newly added entry point, a dependency that pulls in a large transitive graph, or a plugin whose onResolve runs on every import. A slow incremental rebuild points at invalidation scope: an edit is fanning out to more tasks than it should, usually because a widely imported module changed or a barrel file now re-exports too much. Measure which one moved before touching config; optimizing cold start when the pain is in rebuilds wastes a day.

Next, isolate whether the cost is native or in a plugin. Temporarily strip every JavaScript plugin from the config and rebuild; if the time collapses, the plugin was serializing the parallel engine, and the fix is to narrow its filter, make its callback synchronous and cheap, or replace it with a built-in loader. If the time barely moves, the cost is in the graph itself, and the metafile is your next stop — it will show you which inputs contribute the most bytes and, by proxy, the most parse work. A dependency that suddenly dominates the metafile is usually an accidental deep import or a library that lost its tree-shaking annotation in an upgrade.

Finally, check the cache. A build that is slow only on the first run after a pull is a cache that got invalidated wholesale, and the question is what moved the key — a toolchain bump, a config change, or a non-hermetic input that makes the key unstable. A build that is slow on every run despite an unchanged tree is a cache that is never hitting, which is the same root cause seen from the other side. In both cases the diagnosis is to log the computed cache key across runs and find the input that changes when nothing meaningful did. The discipline throughout is the same one the rest of this page keeps returning to: the cache key is the source of truth, and most native-build mysteries dissolve the moment you can see what the key actually captured.

Related

• esbuild API & CLI for rapid builds — the build, transform, and context APIs and when to use each.
• Custom loaders & asset handling — native loaders versus JS plugins for CSS, images, and WASM.
• Integrating esbuild with framework toolchains — aliasing and resolution parity across dev and prod.
• Turbopack incremental compilation — the Turbo engine task graph, cache warming, and invalidation scoping.
• Remote caching & distributed build coordination — content-addressed shared caches and hermetic inputs.
• esbuild plugin patterns — the onResolve/onLoad hooks, namespaces, virtual modules, and build-time injection.
• esbuild & Turbopack version compatibility reference — Node ranges, breaking changes, and binary pinning.