Matrix Package Lifecycle

Appearance

Local Development ​

This section covers the inner loop a package author lives in: building, testing, running directly from a checkout, and refreshing a running Host without copying files by hand. CLAUDE.md Rule 10 captures the canonical commands; this section spells out the mechanics.

Pages ​

  • Build — pnpm build, pnpm build:affected, package build scripts
  • Test — pnpm test, pnpm test:affected, integration tests
  • Run in place — mx run . --env <env> and mx up, the deployless run path
  • Folder-backed source — running a Host against a checkout without copying
  • Installed source — when you do want a copy in <MATRIX_HOME>/packages/
  • Refresh without copying — rebuilding and re-loading a single runtime in a running Host
  • Config explain — mx config, mx info, and inspecting the resolved config a runtime sees

The inner loop, end to end ​

bash
# in projects/matrix-3/packages/<my-pkg>
$EDITOR src/...

pnpm build                # build only this package
pnpm test                 # run package tests

# Option A: run directly from the checkout
matrix run . --env dev

# Option B: refresh a running Host
hivecast operator refresh-host-package \
  --package @open-matrix/<my-pkg> \
  --home /tmp/matrix-home \
  --restart

Always rebuild before testing or before running against a Host. The artifacts in dist/ are what runs; stale dist/ produces false results (CLAUDE.md "REBUILD BEFORE TESTING" lesson).

See also ​