aube-package-manager

# Aube Package Manager > Skill by [ara.so](https://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) ```sh # Install globally mise use -g aube # Pin to a project mise use aube # Verify aube --version ``` ### Via npm ```sh npm install -g @endevco/aube ``` ### Via Homebrew (beta tap) ```sh 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 ```sh 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 ```sh 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 ```sh 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 ```sh aubr build # Equivalent to: aube run build aubx cowsay hi # Equivalent to: aube dlx cowsay hi ``` ### Inspection & Maintenance ```sh 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 ```sh 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 | File | Reads | Writes in place | |---|---|---| | `aube-lock.yaml` | ✅ | ✅ | | `pnpm-lock.yaml` v9 | ✅ | ✅ | | `package-lock.json` v2/v3 | ✅ | ✅ | | `npm-shrinkwrap.json` | ✅ | ✅ | | `yarn.lock` (v1 classic + v2+ berry) | ✅ | ✅ | | `bun.lock` | ✅ | ✅ | **Not supported:** - pnpm v5/v6 lockfiles (upgrade with pnpm first) - Yarn PnP projects (switch to `node_modules` linker first) ## Workspaces ```sh # 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`: ```yaml packages: - "packages/*" - "apps/*" ``` ## Dependency Lifecycle Scripts Aube skips lifecycle scripts by default for security. ```sh # 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`. ```json { "name": "my-app", "aube": { "registry": "https://registry.npmjs.org/", "store-dir": "/custom/store/path" } } ``` ```sh # 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 ```yaml 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 ```dockerfile 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) ```sh # Only update the lockfile, don't install into node_modules aube install --lockfile-only ``` ## Migrating from pnpm ```sh # 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 ```sh # 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 ```sh # 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 ```sh # 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 ```sh 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: ```sh 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: ```sh 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: ```sh 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 ```sh # 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: ```sh # In .yarnrc.yml nodeLinker: node-modules yarn install # regenerates yarn.lock for node-modules layout aube install # now aube can take over ``` ## Links - [Documentation](https://aube.en.dev) - [Benchmarks](https://aube.en.dev/benchmarks) - [Lockfile compatibility](https://aube.en.dev/package-manager/lockfiles) - [Scripts and binaries](https://aube.en.dev/package-manager/scripts) - [Configuration reference](https://aube.en.dev/package-manager/configuration) - [Installation methods](https://aube.en.dev/installation)