Aube Package Manager

Aube Package Manager

Skill by ara.so — Daily 2026 Skills collection.

Aube is a fast Node.js package manager written in Rust. It drops into existing projects by reading and writing existing lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lock), uses a global content-addressable store to reduce disk usage, and delivers dramatically faster installs than pnpm or Bun — especially on warm CI.

Installation

Via mise (recommended)

shCopy code
# Install globally
mise use -g aube

# Pin to a project
mise use aube

# Verify
aube --version

Via npm

shCopy code
npm install -g @endevco/aube

Via Homebrew (beta tap)

shCopy code
brew install endevco/tap/aube

Core Concepts

• Lockfile compatibility: Reads and writes existing lockfiles in place — no forced migration.
• Global store: Package files live in ~/.local/share/aube/store/ (XDG) and are shared across projects.
• Isolated layout: Packages link through node_modules/.aube/ — phantom dependencies are blocked.
• Secure defaults: New package releases wait a minimum age; lifecycle scripts require explicit approval.

Key Commands

Install & Dependency Management

shCopy code
aube install                    # Install all dependencies
aube install -r                 # Install across all workspace packages
aube install --prod             # Production dependencies only
aube install --lockfile-only    # Update lockfile without touching node_modules

aube add react                  # Add a runtime dependency
aube add -D vitest              # Add a dev dependency
aube add zod --filter @acme/api # Add to a specific workspace package
aube remove react               # Remove a dependency
aube update                     # Update deps within package.json ranges

CI

shCopy code
aube ci    # Clean install: removes node_modules, verifies lockfile is fresh, installs

Use aube ci in CI pipelines where the lockfile must be the source of truth.

Running Scripts and Binaries

shCopy code
aube run build          # Run a package.json script
aube run test           # Run test script (auto-installs if deps are stale)
aube test               # Shortcut: same as `aube run test`
aube dev                # Any script name works directly as a subcommand
aube build
aube lint

aube exec vitest        # Run a local binary from node_modules/.bin
aube dlx cowsay hi      # Run a package in a throwaway environment (like npx)

Multicall Shims

shCopy code
aubr build        # Equivalent to: aube run build
aubx cowsay hi    # Equivalent to: aube dlx cowsay hi

Inspection & Maintenance

shCopy code
aube list                   # List installed packages
aube why react              # Explain why a package is installed
aube outdated               # Show outdated dependencies
aube audit                  # Security audit
aube store path             # Show global store location
aube store prune            # Remove unused packages from global store
aube config get registry    # Read config values

Publishing

shCopy code
aube pack       # Pack a package tarball
aube publish    # Publish to registry
aube link       # Link a local package
aube unlink     # Unlink a local package

Lockfile Compatibility

Not supported:

• pnpm v5/v6 lockfiles (upgrade with pnpm first)
• Yarn PnP projects (switch to node_modules linker first)

Workspaces

shCopy code
# Install across all workspace packages
aube install -r

# Run a script in all workspace packages
aube run test -r

# Add a dependency to a specific package
aube add zod --filter @acme/api
aube add -D typescript --filter @acme/shared

Workspace config files:

• pnpm-workspace.yaml — read and written if present
• aube-workspace.yaml — used for aube-first projects

Example aube-workspace.yaml:

yamlCopy code
packages:
  - "packages/*"
  - "apps/*"

Dependency Lifecycle Scripts

Aube skips lifecycle scripts by default for security.

shCopy code
# See which packages had scripts skipped
aube ignored-builds

# Approve specific packages to run their build scripts
aube approve-builds

After approval, the allowed packages are recorded in your project config so teammates get the same behavior.

Configuration

Aube reads config from package.json under "aube" key or from .auberc / aube.config.yaml.

jsonCopy code
{
  "name": "my-app",
  "aube": {
    "registry": "https://registry.npmjs.org/",
    "store-dir": "/custom/store/path"
  }
}

shCopy code
# Read a config value
aube config get registry

# Set a config value
aube config set registry https://my-private-registry.example.com

CI/CD Patterns

GitHub Actions

yamlCopy code
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install mise
        uses: jdx/mise-action@v2

      - name: Install aube
        run: mise use -g aube

      - name: Cache aube store
        uses: actions/cache@v4
        with:
          path: ~/.local/share/aube/store
          key: aube-store-${{ hashFiles('**/pnpm-lock.yaml', '**/aube-lock.yaml') }}
          restore-keys: |
            aube-store-

      - name: Install dependencies
        run: aube ci

      - name: Run tests
        run: aube test

Docker

dockerfileCopy code
FROM node:22-slim

# Install aube via npm
RUN npm install -g @endevco/aube

WORKDIR /app

# Copy lockfile and package.json first for layer caching
COPY package.json pnpm-lock.yaml ./

# Frozen install — fail if lockfile would change
RUN aube ci

COPY . .

RUN aube run build

CMD ["node", "dist/index.js"]

Lockfile-only update (for Docker layer caching)

shCopy code
# Only update the lockfile, don't install into node_modules
aube install --lockfile-only

Migrating from pnpm

shCopy code
# 1. Install aube
mise use -g aube

# 2. Run in your existing project — aube reads pnpm-lock.yaml
cd my-project
aube install

# 3. Approve any build scripts that pnpm was running
aube approve-builds

# 4. Replace pnpm scripts in package.json (optional)
# Before: "scripts": { "postinstall": "pnpm run build:native" }
# After:  keep as-is, aube runs package.json scripts the same way

Migrating from npm/yarn

shCopy code
# npm — aube reads package-lock.json
cd my-npm-project
aube install

# yarn classic — aube reads yarn.lock
cd my-yarn-project
aube install

# Bun — aube reads bun.lock
cd my-bun-project
aube install

Common Patterns

Monorepo with filtered commands

shCopy code
# Build only the API package
aube run build --filter @acme/api

# Run tests in all packages that changed
aube run test --filter '...[origin/main]'

# Install and run in one step (auto-install if stale)
aube exec vitest --run

Global store management

shCopy code
# Find where the store lives
aube store path
# → ~/.local/share/aube/store

# Clean up packages no longer used by any project
aube store prune

Checking why a package is installed

shCopy code
aube why lodash
# Shows the dependency chain that requires lodash

Troubleshooting

aube ci fails with lockfile mismatch

The lockfile is out of sync with package.json. Fix locally:

shCopy code
aube install          # updates lockfile
git add pnpm-lock.yaml
git commit -m "chore: update lockfile"

Build scripts not running

Aube skips lifecycle scripts by default. Check what was skipped:

shCopy code
aube ignored-builds
aube approve-builds   # interactively approve packages

Package phantom dependency errors

Aube uses an isolated layout — packages can only import their declared dependencies. Fix by adding the missing dependency explicitly:

shCopy code
aube add <missing-package>

Slow first install / cold cache

The first install populates the global store. Subsequent installs (same or other projects with shared deps) will be significantly faster. Cache ~/.local/share/aube/store in CI for warm-cache performance.

pnpm v5/v6 lockfile not supported

shCopy code
# Upgrade lockfile with pnpm first
pnpm install  # regenerates as v9 format
# Then switch to aube
aube install

Yarn PnP projects

Aube writes node_modules, not .pnp.cjs. Switch the Yarn linker first:

shCopy code
# In .yarnrc.yml
nodeLinker: node-modules
yarn install   # regenerates yarn.lock for node-modules layout
aube install   # now aube can take over

Links

• Documentation
• Benchmarks
• Lockfile compatibility
• Scripts and binaries
• Configuration reference
• Installation methods