apuya/react-basics-ui / .claude/skills/build-toolchain
build-toolchain
VerifiedDesigns and maintains build tooling — bundlers (Vite, Webpack, Rollup, esbuild, Parcel, tsup), package managers (npm, pnpm, yarn, Pipenv, Poetry, uv), lockfile hygiene, pre-commit hooks, runtime pinning, build cache, module resolution, monorepo workspaces, reproducibility. Audits for non-deterministic builds, lockfile drift, mixed package managers, unpinned runtimes, broken caches, and hooks that mutate without staging. Use when adding a bundler, switching package managers, debugging slow or non-reproducible builds, configuring pre-commit, or laying out a monorepo. Triggers on "build", "bundler", "vite", "webpack", "rollup", "esbuild", "parcel", "tsup", "swc", "babel", "npm", "pnpm", "yarn", "pipenv", "poetry", "uv", "pip-tools", "lockfile", "pre-commit", "husky", "lefthook", "build cache", "slow build", "hmr", "tree shaking", "code splitting", "monorepo", "workspace", "turborepo", "nx", "reproducible build", ".nvmrc", ".python-version", "engines field", "build toolchain".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 19.2 KB |
SKILL.md
View on GitHub---
name: build-toolchain
description: Designs and maintains build tooling — bundlers (Vite, Webpack, Rollup, esbuild, Parcel, tsup), package managers (npm, pnpm, yarn, Pipenv, Poetry, uv), lockfile hygiene, pre-commit hooks, runtime pinning, build cache, module resolution, monorepo workspaces, reproducibility. Audits for non-deterministic builds, lockfile drift, mixed package managers, unpinned runtimes, broken caches, and hooks that mutate without staging. Use when adding a bundler, switching package managers, debugging slow or non-reproducible builds, configuring pre-commit, or laying out a monorepo. Triggers on "build", "bundler", "vite", "webpack", "rollup", "esbuild", "parcel", "tsup", "swc", "babel", "npm", "pnpm", "yarn", "pipenv", "poetry", "uv", "pip-tools", "lockfile", "pre-commit", "husky", "lefthook", "build cache", "slow build", "hmr", "tree shaking", "code splitting", "monorepo", "workspace", "turborepo", "nx", "reproducible build", ".nvmrc", ".python-version", "engines field", "build toolchain".
---
# 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.
| Mode | Use when | Output |
|------|----------|--------|
| **Design** | A new bundler, package manager, or monorepo layout is being introduced | Config spec (entry points, outputs, transformers, plugins, cache strategy, lockfile and runtime pinning) |
| **Audit** | Existing config needs review | Tiered findings (Blocker / High / Medium) with the rule each violates |
| **Diagnose** | Build is slow, flaky, non-deterministic, or producing the wrong output | Root cause traced through resolver → transformer → bundler → emitter |
| **Optimise** | Build works but is too slow or too large | Ranked changes by measured impact, smallest first |
## 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**:
| Config | Entry | Emits |
|---|---|---|
| JS | `src/index.ts` | `index.js` (ESM) · `index.cjs` · `index.d.ts` / `.d.cts` · sourcemaps |
| CSS | `src/global.css` | `index.css` (~293 KB, Tailwind + the token system) |
`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:
```bash
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
```bash
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
| Source | Symptom | Fix |
|---|---|---|
| `Date.now()` baked into output | New hash on every build | Inject build date at runtime, not build time |
| Filesystem iteration order | Chunk hashes shuffle across machines | Sort glob results before consumption |
| Parallel emitter race | Source maps mis-aligned with chunks | Pin emitter concurrency or pin output filenames |
| Postinstall scripts touching the network | Build differs by region or DNS state | Vendor or remove the postinstall |
| Untracked env vars (`NODE_ENV`, `CI`, locale) | Output diverges by environment | Snapshot the env in the build manifest |
## 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
| Layer | Keyed by | Invalidates when | Storage |
|---|---|---|---|
| Resolver cache | (specifier, conditions, importer dir) | Manifest or directory listing changes | In-memory per process |
| Transform cache | (file content hash, transformer version, options) | File or transformer changes | Disk, per project |
| Bundle cache | (module graph, options) | Any input module changes | Disk or runner cache |
| Dependency cache | (lockfile hash) | Lockfile changes | Runner cache |
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
| Intent | Command pattern | Effect |
|---|---|---|
| Add a dep | `add <pkg>` / `poetry add` / `pipenv install` | Mutates manifest and lockfile |
| Sync from lockfile (CI) | `ci` / `install --frozen-lockfile` / `install --deploy` / `install --no-update` | Fails on drift |
| Sync from lockfile (local) | Same as CI, or `install` if drift is allowed | Local convention |
| Upgrade | `update <pkg>` / `poetry update` | Recomputes lockfile within manifest constraints |
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:
```bash
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.
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |