Aube

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

1. Install through mise — mise use aube and pin in [tools] (e.g. aube = "2.2.9"); never install aube standalone. See mise.
2. Single version source — mise.toml drives both node and aube; after migrating, remove the packageManager field from package.json so versions do not fork.
3. Keep a Dependabot-compatible lockfile — aube reads and writes an existing pnpm-lock.yaml or package-lock.json in place, so keep that committed rather than switching to aube-lock.yaml. Dependabot lacks an aube ecosystem and cannot maintain aube-lock.yaml. For new projects, set defaultLockfileFormat = "pnpm" in aube-workspace.yaml, .npmrc, or settings.toml. In dependabot.yml, use the npm ecosystem for these projects — no aube ecosystem exists. Adopt aube-lock.yaml only without Dependabot. Locked versions are trusted on frozen installs (aube ci) without per-install revalidation.
4. 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.
5. Phased migration — pilot in one project or subcomponent before committing; do not replace wholesale.

Commands

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-action picks missing pnpm on pnpm-lock.yaml. Call binary directly: aube exec wrangler deploy with CLOUDFLARE_API_TOKEN in env.
• aube exec swallows global flags — aube exec tsc --version prints aube's version. Put -- before binary: aube exec -- tsc --version.
• aubr echoes commands to stderr — prints expanded command prefixed with $ to stderr (matching npm/pnpm); pass --silent / -s if scripts parse stderr.
• Global installs use aube data root in 2.x — aube add -g installs to $XDG_DATA_HOME/aube/bin (~/.local/share/aube/bin), ignoring PNPM_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/package modules loop under aube — disable in ~/.config/starship.toml ([nodejs] and [package] disabled = true) to prevent prompt loops.
• mise install aube fails GitHub attestation verification — see CI section for the jdx/aube-action fix.

Related

• mise — installs and pins aube locally; provides the single version source (mise.toml) that jdx/aube-action@v1 reads in CI.