@dephub/package-install

Install packages with flexible scope support using your preferred package manager

Features ✨

• 🔧 Multi-scope Installation - Install packages in local, workspace, global, or dev scope
• 🎯 Smart Package Manager Detection - Automatically detects your package manager (npm, yarn, pnpm, bun)
• 🚀 Zero Dependencies - Only uses @dephub packages for core functionality
• 🔒 Type Safe - Full TypeScript support with strict types
• 💻 CLI & API - Use via command line or programmatically
• ❓ Interactive Confirmation - Optional prompt before installation

Installation 💿

# Using npm
npm install @dephub/package-install

# Using pnpm
pnpm add @dephub/package-install

# Using yarn
yarn add @dephub/package-install

# Using bun
bun add @dephub/package-install

CLI Usage 🖥️

Basic Commands

# Install a package (default: production dependency)
package-install eslint

# Install as development dependency
package-install --dev typescript

# Install globally
package-install --global esbuild

# Install into workspace (monorepo support)
package-install --workspace react

Options

• --packageManager <manager> - Specify package manager: npm, yarn, pnpm, bun
• --global - Install the package globally
• --dev - Install as a development dependency
• --production - Install as a production dependency (default)
• --workspace - Install into the current workspace

Examples

# Install with specific package manager
package-install eslint --packageManager pnpm

# Install multiple scopes (the last one wins)
package-install typescript --dev --workspace

# Install globally with bun
package-install serve --global --packageManager bun

Programmatic Usage 🛠️

import {
  install,
  askInstall,
  InstallBuilder,
  installer,
} from '@dephub/package-install';

// Install a package without confirmation (production scope by default)
const result = await install('eslint');
console.log(result.success); // true or false

// Install with specific scope
const result2 = await install('typescript', 'dev');

// Interactive installation with confirmation
const result3 = await askInstall('react', 'workspace');

// Use the builder for advanced configuration
const builder = new InstallBuilder()
  .setName('vue')
  .setScope('global')
  .setPackageManager('npm');

const result4 = await builder.install();

// Or use the pre-configured instance
installer.setName('prettier');
installer.setScope('dev');
const result5 = await installer.install();

API Reference 📚

install(name, scope?)

Install a package with the specified scope without user confirmation.

Parameters:

• name (string) - Package name to install
• scope (InstallScope) - Installation scope: 'global', 'workspace', 'dev', 'production' (default: 'production')

Returns: Promise<InstallResult> - Installation result

askInstall(name, scope?)

Prompts the user for confirmation before installing the package.

Parameters:

• name (string) - Package name to install
• scope (InstallScope) - Installation scope: 'global', 'workspace', 'dev', 'production' (default: 'production')

Returns: Promise<InstallResult> - Installation result with user confirmation

InstallBuilder

Builder class for installing packages with method chaining.

new InstallBuilder(options?)

Creates a new InstallBuilder instance.

Parameters:

• options (InstallOptions) - Optional initial configuration

setPackageManager(packageManager)

Sets the package manager to use for installation.

Parameters:

• packageManager (PackageManager) - The package manager to use (npm, yarn, pnpm, bun)

Returns: InstallBuilder

setName(name)

Sets the name of the package to install.

Parameters:

• name (string) - The name of the package to install

Returns: InstallBuilder

setScope(scope)

Sets the installation scope.

Parameters:

• scope (InstallScope) - The installation scope (global, workspace, dev, production)

Returns: InstallBuilder

install()

Installs the package using the configured settings.

Returns: Promise<InstallResult>

askInstall()

Prompts the user for confirmation before installing the package.

Returns: Promise<InstallResult>

detectPackageManager()

Automatically detects and sets the package manager from the environment.

Returns: Promise<void>

installer

Pre-configured InstallBuilder instance for immediate use.

Installation Scopes 🔧

• production: Install as a production dependency (default)
• dev: Install as a development dependency
• global: Install globally
• workspace: Install into the current workspace (monorepo support)

Examples 💡

Basic Installation

// Install a production dependency
await install('lodash');

// Install a development dependency
await install('typescript', 'dev');

// Install globally
await install('esbuild', 'global');

Interactive Installation

// Ask for confirmation before installing
const result = await askInstall('react', 'workspace');
if (result.skipped) {
  console.log('Installation cancelled by user');
} else if (result.success) {
  console.log('Package installed successfully');
} else {
  console.log('Installation failed:', result.error);
}

Advanced Builder Usage

// Chain methods for fluent configuration
const result = await new InstallBuilder()
  .setName('vue')
  .setScope('dev')
  .setPackageManager('pnpm')
  .install();

// Use the pre-configured instance
installer.setName('eslint');
installer.setScope('dev');
const result2 = await installer.askInstall();

Error Handling

try {
  const result = await install('some-package');
  if (!result.success) {
    console.error('Installation failed:', result.error);
  }
} catch (error) {
  console.error('Unexpected error:', error);
}

Types

InstallScope

type InstallScope = 'global' | 'workspace' | 'dev' | 'production';

InstallResult

interface InstallResult {
  /** Whether the installation was successful */
  success: boolean;
  /** The name of the package that was attempted to be installed */
  name: string;
  /** The package manager used for installation, if any */
  packageManager?: PackageManager;
  /** The installation scope that was used */
  scope: InstallScope;
  /** Error message if the installation failed */
  error?: string;
  /** Whether the installation was skipped by user confirmation */
  skipped?: boolean;
}

InstallOptions

interface InstallOptions {
  /** The package manager to use for installation */
  packageManager?: PackageManager;
  /** The name of the package to install */
  name?: string;
  /** The installation scope */
  scope?: InstallScope;
}

PackageManager

type PackageManager = 'npm' | 'yarn' | 'pnpm' | 'bun';

License 📄

MIT License

Author: Estarlin R (estarlincito.com)