---
name: wireit
description: Author and use Wireit scripts. Use when working with Wireit configuration, package.json scripts, build pipelines, or when the user mentions Wireit.
review: always
---

# Wireit

## Documentation

Full documentation: https://github.com/google/wireit

## Authoring Wireit Scripts

- Wireit is very static, list dependencies explicitly (won't infer them from pnpm workspace relationships).
- if something needs go (ex:compile) before another thing go (ex:bundle) that's a dependency
- envs: see https://github.com/google/wireit?tab=readme-ov-file#environment-variables
- deps can be relative ex "../../other-pkg:script-name"
- If a package in this repo has another package as a package.json dep or devDep, it should be a wireit dep for compile
- If an extension has another extension as an extensionDependency, it should be a wireit dep for bundle
  caching: if you specify `files` and `output` (even `[]`) you'll get caching (skips when neither have changed)
- You can have a wireit script without it being an npm script (ex: you can't execute it on its own, but it can run as a dep of another wireit script that can start from `pnpm run`)
- don't make circular references

## Using Wireit Scripts

- run commands with WIREIT_CACHE=none to avoid caching behaviors
- Agents should not run these (they won't exit)
  - any script with --watch
  - any `service:true` if you're an Agent, it won't exit
- wireit can't follow stuff outside `files`
  - manually changing code in node_modules then running compile or bundle
  - exception: `salesforcedx-vscode-services` `vscode:bundle` tracks `node_modules/@salesforce/templates/lib/**`
  - npm link'd packages (ex: symlinks to node libraries locally modified)

## Extra Arguments (passing CLI flags through wireit)

ref: https://github.com/google/wireit?tab=readme-ov-file#extra-arguments

- `pnpm run {script} -- {script args}` — single `--` forwards args to underlying command
- ex: `pnpm run build -- --verbose` passes `--verbose` to the command in `wireit.build.command`

## Common Patterns

top level `compile`, `lint`, `test` should run all of that in the various packages. When creating new packages, update these.

## Errors

If you see "Unknown error thrown: Error: Did not expect..." or "Internal error!" from wireit — another process was running the same scripts. Re-run the command yourself to confirm it passes. DO NOT CLEAR `.wireit` to solve this.

## Notes

each package will have its own `.wireit` cache, and there's also one at the top level.