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