# Guidance Build

> Wireit orchestration, build optimization, caching strategies, and build troubleshooting for the Elements monorepo. Use this skill whenever the user asks about Wireit configuration, build tasks, build dependencies, cache invalidation, build performance, adding new build tasks to package.json, cross-package dependency patterns, sideEffects declarations, CI pipeline configuration, or diagnosing slow or failing builds. Also trigger when the user mentions wireit, vite build issues, pnpm run ci, or build output problems.

- Skill: `nvidia/guidance-build` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nvidia/guidance-build`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nvidia/guidance-build/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: NVIDIA (https://skillmd.com/u/nvidia)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nvidia/guidance-build

---


# Guidance Build System

You MUST review the build system documentation before modifying build configurations or troubleshooting build issues.

## When to Use This Skill

- Optimizing build performance and parallelization
- Understanding Wireit task dependencies
- Troubleshooting build failures or cache issues
- Adding new build tasks to projects
- Configuring build orchestration across packages
- Understanding CI/CD build pipeline

## Quick Reference

### Common Commands

```shell
# Full CI locally (lint, build, test):same as CI pipeline
pnpm run ci

# Clean everything (node_modules, dist, .wireit caches)
pnpm run ci:reset

# Build a single project
cd projects/core && pnpm run build

# Force that project's Wireit scripts to rerun
mise exec -- git clean -dfX -- .wireit
mise exec -- pnpm run build

# Dev mode with watch
cd projects/core && pnpm run dev
```

### Wireit Basics

Wireit configs live in each project's `package.json` under the `wireit` key. Each task declares:

- `command`:the shell command to run
- `dependencies`:other wireit tasks that must complete first (can be cross-package)
- `files`:input file globs for cache invalidation
- `output`:output file globs that get cached

Wireit skips tasks whose inputs have not changed since the last run. `WIREIT_CACHE=none` turns off output caching but does not bypass this incremental freshness check. To force a rerun, run `mise exec -- git clean -dfX -- .wireit` from the target project directory before invoking the project script.

### Dependency Patterns

Cross-package dependencies use the `<package>:<script>` format:

```json
{
  "wireit": {
    "build": {
      "dependencies": ["../themes:build", "../styles:build"],
      "command": "vite build",
      "files": ["src/**/*", "tsconfig.json"],
      "output": ["dist/**"]
    }
  }
}
```

### Troubleshooting Build Failures

| Symptom                                    | Fix                                                                   |
| ------------------------------------------ | --------------------------------------------------------------------- |
| Stale cache causing wrong output           | Clean `.wireit/` in the affected project, then rebuild                |
| "Cannot find module" after package changes | Run `pnpm i --frozen-lockfile` to re-link workspaces                  |
| TypeScript errors after dependency update  | Rebuild dependencies first: `cd projects/themes && pnpm run build`    |
| CI passes locally but fails in pipeline    | Check Node version (`node -v` should match `.nvmrc`) and pnpm version |
| Full reset                                 | `pnpm run ci:reset && pnpm i --frozen-lockfile && pnpm run ci`        |

### Adding a New Wireit Task

1. Add the script to `package.json` with a `wireit` config
2. Declare `files` (inputs) and `output` (outputs) for caching
3. Add `dependencies` on upstream packages that must build first
4. If the task should run in CI, add it to the dependency chain of the root `ci` script

## Key Tools

- **pnpm**:package manager with workspaces
- **Wireit**:build orchestration with caching (like Bazel for Node)
- **Vite**:TypeScript compilation and bundling
- **Semantic Release**:automated versioning from conventional commits

## References

- [Build System Documentation](/projects/internals/BUILD.md)
- [Root Wireit Configuration](/package.json)
- Project `package.json` files for individual build patterns