aube
Use aube as the Node.js package manager, installed and pinned through mise. aube is jdx's fast, security-first package manager (https://aube.sh/); this skill captures the how we use it here decisions, not the official reference.
Core conventions
- Install through mise —
mise use aubeand pin in[tools](e.g.aube = "2.2.9"); never install aube standalone. Seemise. - Single version source —
mise.tomldrives both node and aube; after migrating, remove thepackageManagerfield frompackage.jsonso versions do not fork. - Keep a Dependabot-compatible lockfile — aube reads and writes an existing
pnpm-lock.yamlorpackage-lock.jsonin place, so keep that committed rather than switching toaube-lock.yaml. Dependabot lacks an aube ecosystem and cannot maintainaube-lock.yaml. For new projects, setdefaultLockfileFormat = "pnpm"inaube-workspace.yaml,.npmrc, orsettings.toml. Independabot.yml, use thenpmecosystem for these projects — noaubeecosystem exists. Adoptaube-lock.yamlonly without Dependabot. Locked versions are trusted on frozen installs (aube ci) without per-install revalidation. - Accept supply-chain defaults — aube denies lifecycle scripts by default, holds new releases behind a 24h cooling window, checks typosquats, and downgrades trust. Keep these; allow only the specific builds you need.
- Phased migration — pilot in one project or subcomponent before committing; do not replace wholesale.
Commands
| Command | Use |
|---|---|
aubr <script> (= aube run) |
Daily driver: aubr build, aubr test, aubr dev. Echoes $ <cmd> to stderr (--silent to mute). |
aube test |
Auto-installs on stale state, then runs test script. |
aube ci |
Frozen-lockfile install for CI; runs no scripts by default. |
aube install |
Local setup / Docker layers. |
aube add <pkg> |
Add a dependency (malware-checked by default). |
aubx <tool> (= aube dlx) |
Run a one-off tool without installing. |
aube exec [--] <cmd> |
Run binary from deps. Put -- before binary so flags pass through (see Gotchas). |
aube approve-builds |
Interactive review/approval of lifecycle build scripts. |
CI (GitHub Actions)
Prefer jdx/aube-action@v1 over jdx/mise-action@v4: aube's repo moved
jdx/aube -> aubepkg/aube, and mise's aqua backend still verifies GitHub
attestations against the old identity, breaking mise install aube for every
release since 2.2.8. jdx/aube-action@v1 downloads the release directly (no
attestation check) and installs Node.js too via node-version: auto (reads
mise.toml, .nvmrc, etc.) — drop actions/setup-node. Still need
mise-action for other tools in the same job? Set
MISE_AQUA_GITHUB_ATTESTATIONS: false on that step instead.
Cache both aube directories — the content store and registry metadata are
separate (see https://aube.sh/package-manager/ci.html#cache-choices) — via
aube store path / aube cache path, not hardcoded paths:
- uses: jdx/aube-action@v1
with:
node-version: auto
- id: aube-paths
run: |
echo "store=$(aube store path)" >> "$GITHUB_OUTPUT"
echo "cache=$(aube cache path)" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v6
with:
path: ${{ steps.aube-paths.outputs.store }}
key: ${{ runner.os }}-aube-store-${{ hashFiles('**/pnpm-lock.yaml') }}
- uses: actions/cache@v6
with:
path: ${{ steps.aube-paths.outputs.cache }}
key: ${{ runner.os }}-aube-cache-${{ hashFiles('**/pnpm-lock.yaml') }}
- run: aube ci
- run: aubr test
Lifecycle scripts
aube jails lifecycle scripts by default. Allow needed builds via
aube approve-builds or allowBuilds in aube-workspace.yaml /
pnpm.allowBuilds in package.json, e.g. esbuild, workerd. Verify
locally before relying on CI. Jailed builds can also be granted explicit
permissions (jailBuildPermissions).
Gotchas
- Third-party actions auto-detect the package manager — e.g.
wrangler-actionpicks missing pnpm onpnpm-lock.yaml. Call binary directly:aube exec wrangler deploywithCLOUDFLARE_API_TOKENin env. aube execswallows global flags —aube exec tsc --versionprints aube's version. Put--before binary:aube exec -- tsc --version.aubrechoes commands to stderr — prints expanded command prefixed with$to stderr (matching npm/pnpm); pass--silent/-sif scripts parse stderr.- Global installs use aube data root in 2.x —
aube add -ginstalls to$XDG_DATA_HOME/aube/bin(~/.local/share/aube/bin), ignoringPNPM_HOME. Add this directory to$PATH. - bun -> aube is also a runtime migration — migrating runtime (
node:*) and test runner (bun test -> Vitest) is separate from package-manager switch. - starship
nodejs/packagemodules loop under aube — disable in~/.config/starship.toml([nodejs]and[package]disabled = true) to prevent prompt loops. mise install aubefails GitHub attestation verification — see CI section for thejdx/aube-actionfix.
Related
mise— installs and pins aube locally; provides the single version source (mise.toml) thatjdx/aube-action@v1reads in CI.