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

# 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:

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

Troubleshooting Build Failures

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
• Root Wireit Configuration
• Project package.json files for individual build patterns