Imported from apuya/react-basics-ui (.claude/skills/build-toolchain/SKILL.md). Install upstream with npx skills add apuya/react-basics-ui --skill build-toolchain. Copyright stays with the author.

Build / Toolchain Engineer

Owns the path from source on disk to a runnable artifact. Optimises for reproducibility first, feedback latency second, output size and runtime cost third.

Investigation order

Apply to any build problem before changing the config.

1. Reproduce. Pin the exact command, working directory, lockfile state, runtime version, and OS. A build that "works on CI but not locally" is two builds; describe both.
2. Measure. Wall time per stage (resolve, compile, bundle, emit), cache hit ratio, peak memory, output size. Profilers: --profile, --analyze, --metafile, --debug-resolve, language-specific timers.
3. Hypothesise. Name the suspected cause in one sentence: stale cache, unhashed input, lockfile mismatch, dual transformer, plugin order, runtime drift.
4. Verify. Change one variable in isolation — wipe the cache, pin the runtime, regenerate the lockfile in a clean checkout, swap one plugin out. Re-measure.
5. Apply. Smallest config diff that proves the fix.
6. Re-measure. Cold build, warm rebuild, dev start, and output size all return to or beat baseline before closing.

Skipping step 2 is the most common error — build problems look obvious and almost always aren't.

Mode router

Pick one per invocation. If ambiguous, ask.

This project's build — a published dual-format library

Most of this skill is about building an application. react-basics-ui builds a package other people install, which changes what "correct" means: the output is a public contract, not a deploy artifact.

Shape

tsup.config.ts exports an array of two configs:

package.json publishes them via the exports map (. and ./styles.css), ships only dist via files, and marks sideEffects: ["**/*.css"] so bundlers may tree-shake the JS but never drop the stylesheet.

Two gotchas that cost real time here

1. The stylesheet needs its own config. The declaration pass refuses a .css root file (TS6054), so a combined config fails the whole build. The CSS config also sets clean: false, or it wipes the JS build that ran before it.
2. The entry key must be exactly index. Naming it 'index.css' produces dist/index.css.css, which the exports map does not point at — and nothing warns you.

Externals — verify, don't assume

tsup externalises dependencies and peerDependencies by default, which is what you want: bundling react would give consumers two Reacts. Confirm after any build change:

grep -oE 'from ?"[^"./][^"]*"' dist/index.js | sort -u

Expect exactly: clsx, react, react-dom, react/jsx-runtime, react-icons/*, tailwind-merge. Anything else appearing means a dependency got inlined; anything missing means it got bundled. dist/index.js is ~540 KB of this library's own components — that number should track component count, not dependency count.

After any build change, check all four

npm run build
ls dist/index.js dist/index.cjs dist/index.d.ts dist/index.css   # all four exist
grep -c 'import\.meta' dist/index.cjs                            # must be 0 — syntax error in CJS

The import.meta check matters: it is valid in ESM and fatal in CommonJS, so a Vite-style idiom slipping into source breaks only the CJS consumers, and only at their build time.

Optimisation priority

In order. Never invert.

1. Correctness. The output matches source semantics. Tree-shaking must not drop side-effectful imports; minifiers must not rename across module boundaries; transforms must preserve this, decorators, and async semantics.
2. Reproducibility. Same inputs → same outputs, on any machine, any day.
3. Cold build time. First build from a clean checkout.
4. Warm rebuild time. Incremental build during development.
5. Dev server start. Time from start to first interactive request.
6. Bundle size. Compressed size of shipped artifacts.
7. Memory footprint. Peak RSS during build.

A faster build that emits subtly wrong output is a regression, not a win.

Reproducibility

The default question: can this exact artifact be rebuilt in six months from the committed state of the repo alone?

Inputs that must be pinned

• Runtime. Node, Python, Bun, Deno version, declared in a version file (.nvmrc, .tool-versions, .python-version, engines field) and enforced in CI.
• Package manager. Version pinned (packageManager field, pipenv --python, poetry env use). Mixing npm install with a pnpm-lock.yaml corrupts the lockfile silently.
• Direct dependencies. Exact versions in the manifest and a lockfile committed to VCS.
• Transitive dependencies. Resolved versions in the lockfile, with integrity hashes.
• Native toolchain. Compiler, linker, system libraries — declare in a base image or devcontainer when they affect output.

Lockfile rules

• Always committed. A repo with package.json but no package-lock.json / pnpm-lock.yaml / yarn.lock has no reproducibility guarantee.
• Regenerated only by a manifest change. A lockfile churn in a PR that did not touch the manifest is a smell — investigate before merging.
• Frozen in CI. Use the install mode that fails on drift (npm ci, pnpm install --frozen-lockfile, yarn install --immutable, pipenv install --deploy, poetry install --no-update). Plain install mutates the lockfile and hides drift.
• One lockfile format per repo. Two installers writing to the same node_modules produces ghost dependencies.

Determinism gotchas

Bundler configuration

Entry, output, target

• Entry: enumerate explicitly. Glob entries hide which files ship.
• Output: content-hash filenames ([name].[contenthash].js) for cacheable assets; stable names only for the HTML or manifest that points at them.
• Target: pin to a concrete set of browsers, a Node version, or a runtime spec. latest is not a target.

Transformer pipeline

Order matters and is rarely commutative.

1. Resolve (path → file)
2. Load (file → source string + maps)
3. Transform (source → source; runs N times)
4. Bundle (graph → chunks)
5. Optimise (minify, tree-shake, scope-hoist)
6. Emit (chunks → disk)

A common bug: two transformers claim the same extension and run in the wrong order. Symptoms — works in dev, breaks in prod, or vice versa. Make the order explicit in config.

Tree shaking

• Requires ESM sources. CJS is opaque to the bundler.
• Requires sideEffects: false in package.json (or a precise array) for any package whose modules can be safely dropped when unused.
• Breaks silently on:
  • Re-export barrels that re-export everything (export * from './x') without sideEffects.
  • Property access on namespace imports (import * as X).
  • Polyfills imported for side effect (must be listed in sideEffects).

Code splitting

• Route-level: dynamic import() at the route boundary. Default for SPAs.
• Vendor split: separate chunk for stable third-party deps. Inverts cache invalidation pressure from application changes.
• Shared chunks: extract code referenced by ≥2 entries. Configure the minimum reuse threshold; the default is often too aggressive and produces dozens of tiny chunks.

A bundle with 200 chunks is not split — it is shrapnel. Measure HTTP/2 push, prefetch budget, and parse cost before adding splits.

Source maps

• Dev: inline or eval-cheap-module-source-map equivalent — fast, accurate to original line.
• Prod: source-map (separate file), uploaded to the error tracker, not served to clients. A public source map leaks original source.

Dev server vs prod build

These are two different programs sharing a config file. Verify both:

• Dev: HMR works, module graph is correct, no stale modules after edit.
• Prod: tree-shaking applied, minification correct, output runs in the target runtime.

A green dev server is not evidence that prod builds correctly.

Build performance

Cache layers

Cache invalidation must depend on every input that affects output. A cache keyed on the file path but not the file content is a correctness bug, not a speed feature.

Parallelism

• Worker pools help CPU-bound transforms (TypeScript, Babel, Sass).
• They hurt I/O-bound steps; the bottleneck becomes disk, not CPU.
• Saturate at cpu - 1 workers. Above that, contention with the main thread wastes time.
• Measure before parallelising — a 4× speedup that costs 16× memory is not always worth it.

Incremental builds

Required signals from the watcher:

• File added, removed, content-changed, renamed.
• Directory rescans on case-insensitive filesystems (macOS) when case changes.

A watcher that misses a rename produces a build that disagrees with source until restart. Symptom: tests pass but production fails on the renamed file.

Package managers

Selection criteria

• Match the ecosystem. Node monorepos: pnpm or yarn with workspaces. Python projects with native deps: uv or poetry. Python apps with simple deps: pipenv or pip-tools.
• Pick one per repo. Mixed package managers produce shadow dependency graphs that pass tests and fail in prod.
• Pin its version. Without packageManager (Node) or [tool.poetry] version constraint (Python), the runner installs whatever floats — lockfile semantics differ across major versions.

Install modes

The CI install must always be the frozen mode. Plain install in CI silently regenerates the lockfile and ships drifted deps.

Workspace layout

• Hoisting models differ: npm/yarn flatten by default; pnpm symlinks. Code that assumes a flat node_modules (raw path imports, native module probes) breaks under pnpm. Test on the chosen layout.
• A package depending on a sibling must declare it. Cross-package imports that work only because hoisting flattened them are accidents.
• workspace:* and path: specifiers preserve local development across versions; replace with concrete versions only at publish time.

Pre-commit orchestration

A pre-commit hook is code that runs on every commit. Treat it as production code on a hot path.

What belongs in pre-commit

• Fast checks: format, lint, trailing whitespace, secret scan.
• Localised checks: each hook reads only the staged files it was passed.
• Idempotent fixers: a second run on the same input is a no-op.

What does not belong

• Full test suites — too slow; push to CI.
• Build steps — too slow and changes output the developer did not intend.
• Hooks that touch unstaged files — silently widens the commit's blast radius.
• Network calls — break offline commits; non-deterministic on flaky networks.

Hook configuration discipline

• Pin every hook to a tagged release (rev: in .pre-commit-config.yaml, an SHA or version in husky/lefthook scripts). Floating refs mean two developers run different versions.
• Pin language_version for any hook with a compiled language (Python, Node). Otherwise a developer's system runtime decides what runs.
• Scope files: and exclude: per hook. A linter pointed at the entire repo runs N× as long as the staged set.
• Auto-fixers must re-stage their writes or fail loudly. A hook that fixes a file without staging produces a commit that does not match what was checked.

Bypass policy

--no-verify is a tool, not a workflow. If developers bypass routinely, the hook is wrong, not the developers. Investigate before tightening.

Current state in this repo — configured but inert

husky is installed and package.json runs prepare: husky, and a lint-staged block is configured (eslint --fix + prettier --write on *.{ts,tsx}). But .husky/pre-commit does not exist, so nothing invokes lint-staged and no hook runs on commit. .husky/ contains only husky's internal _/ directory.

This is dead configuration, and it is the failure mode this section warns about in reverse: not a hook that does too much, but config that reads as protection while providing none. Either wire it:

echo 'npx lint-staged' > .husky/pre-commit && chmod +x .husky/pre-commit

…or drop husky, lint-staged, and the prepare script so the repo does not claim a guarantee it has not got. Do not leave it as-is — a reader reasonably assumes staged files are linted.

Monorepo concerns

Task graph

A monorepo build is a DAG of (package, task) nodes. The runner (turborepo, nx, bazel, make) walks the graph and caches per node.

• Declare task inputs precisely. Anything not declared is invisible to the cache and produces stale hits.
• Declare task outputs precisely. Anything not declared is not restored from cache and looks like a miss.
• One node per (package, task) pair. A task that depends on "the whole repo" defeats the cache.

Affected detection

• since=<ref> filters to packages whose inputs changed against the ref.
• Reliable only if every package's input set is complete. A missing input (e.g., a shared tsconfig) makes affected detection silently under-build.

Versioning

• Fixed: all packages share a version; one publishes, all publish. Simple, coarse.
• Independent: each package versions on its own changes. Requires a changeset workflow or commit-message convention.

Pick one per repo. Half-and-half produces tag collisions.

Red flags

Treat as bugs unless justified in writing.

• package.json without a committed lockfile.
• npm install (not npm ci) in CI.
• Two lockfile formats in the same repo (package-lock.json and pnpm-lock.yaml).
• A lockfile diff in a PR that did not touch the manifest.
• latest, *, or a floating major (^1, ~1) on a runtime, a build tool, or a compiler.
• Postinstall scripts that fetch from the network or write outside the package.
• Bundler config that imports application source — config evaluation now depends on app correctness.
• Tree-shaking enabled with no sideEffects declaration on internal packages.
• Source maps emitted to a public output directory in prod.
• Pre-commit hook pinned to main or no rev at all.
• Pre-commit hook that runs the test suite.
• A watch script that calls a different bundler than the build script.
• A cache key that excludes the transformer's own version.
• engines field absent from any published package.
• A monorepo task whose declared inputs do not include the files it reads.
• Two developers reporting different build outputs from the same commit.

Decision flowchart — "the build is broken"

Build is failing or wrong
  │
  ├─ Fails to resolve a module?
  │    ├─ Check the resolver:    extensions, conditions, exports field, tsconfig paths
  │    ├─ Check the manager:     lockfile in sync? frozen install passing? package manager pinned?
  │    └─ Check the workspace:   sibling declared as a dep? hoisting model assumed?
  │
  ├─ Resolves but transforms wrong?
  │    ├─ Two transformers claiming the same extension?  Pin order, drop one.
  │    ├─ Stale transform cache?                         Wipe; re-measure.
  │    └─ Transformer version drift across machines?     Pin runtime + lockfile.
  │
  ├─ Builds locally, fails in CI?
  │    ├─ Different runtime?           Compare .nvmrc / .python-version vs CI image.
  │    ├─ Different install mode?      CI must be frozen; local often is not.
  │    ├─ Case-sensitive paths?        Linux CI on a case-sensitive FS catches what macOS misses.
  │    └─ Missing env var?             Snapshot the env that affects the build.
  │
  ├─ Builds, but output is wrong?
  │    ├─ Tree-shake dropped a side effect?  Declare in sideEffects.
  │    ├─ Minifier renamed across modules?   Disable mangling for boundary symbols.
  │    └─ Source map mis-aligned?            Pin emitter concurrency.
  │
  └─ Builds, but is too slow?
       ├─ Measure stages first.   Optimise the slowest, not the most visible.
       ├─ Cache hit ratio low?    Check the key; one wrong input invalidates everything.
       └─ Parallelism saturated?  More workers will hurt.