optional-deps-lib

Deterministically install optional tooling dependencies into an isolated cache root instead of mutating the user's project.

optional-deps-lib is a small runtime helper for library authors who need to bootstrap optional packages on demand while keeping those installs reproducible and separate from the consumer's app.

Why this exists

• Keeps optional tooling installs outside the user's project directory.
• Lets the client choose exact dependency specs and versions.
• Verifies installed packages after each install attempt instead of trusting exit codes alone.
• Recovers from partial installs by retrying and, if needed, recreating only the isolated cache root.

Installation

npm install optional-deps-lib

How it works

1. optional-deps-lib resolves an isolated cache directory for optional packages.
2. It writes a small manifest with the exact specs requested by the client.
3. It detects the active package manager (npm, pnpm, yarn, or bun).
4. It installs the requested packages into the cache root.
5. It re-checks resolution from the cache root before reporting success.

The default cache root is versioned so installs remain deterministic across library upgrades.

Usage

import {
  installOptionalDependencies,
  resolveOptionalInstallRoot,
  hasDependency
} from 'optional-deps-lib'

async function ensurePostcss(projectPath) {
  if (hasDependency(projectPath, 'postcss')) {
    return null
  }

  const installed = await installOptionalDependencies('PostCSS', ['[email protected]'])

  if (!installed) {
    throw new Error('Failed to install PostCSS support')
  }

  return resolveOptionalInstallRoot()
}

Supported package managers

• npm
• pnpm
• yarn
• bun

The installer also contains Windows and WSL-specific path handling so isolated installs can run in the same environment where the user launched the host tool.

Deterministic package versions

This package does not ship its own dependency catalog.

Clients are expected to pass exact dependency specs such as:

• [email protected]
• [email protected]
• @rspack/[email protected]

That keeps version policy with the consuming tool while this library focuses on isolated installation, package-manager execution, and verification.

API

• installOptionalDependencies(integration, dependencySpecs, options?)
• installOptionalDependenciesBatch(plans)
• resolveOptionalInstallRoot()
• resolveDevelopInstallRoot()
• hasDependency(projectPath, dependency)

installOptionalDependencies(integration, dependencySpecs, options?)

Installs the requested exact dependency specs into the isolated cache root and verifies they can be resolved afterward.

installOptionalDependenciesBatch(plans)

Installs several integration plans in sequence and stops on the first failure.

resolveOptionalInstallRoot()

Returns the versioned isolated cache directory used for optional installs.

resolveDevelopInstallRoot()

Resolves the host extension-develop installation root when this package is used inside that runtime.

hasDependency(projectPath, dependency)

Checks whether the nearest project package.json already declares the given dependency.

Guarantees

• Optional installs are isolated from the consumer project.
• User project lockfiles are not modified by bootstrap installs.
• Install success is verified via follow-up resolution checks.
• Recovery only resets the isolated optional dependency root.

License

MIT (c) Cezar Augusto.