@dephub/package-install/README.md

Install packages with flexible scope support using your preferred package manager

# @dephub/package-install

> Install packages with flexible scope support using your preferred package manager

[![NPM version](https://img.shields.io/npm/v/@dephub/package-install.svg?style=flat)](https://npmjs.org/package/@dephub/package-install)
[![ESM-only](https://img.shields.io/badge/ESM-only-brightgreen?style=flat)](https://nodejs.org/)

## 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 💿

```bash
# 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

```bash
# 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

```bash
# 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 🛠️

```typescript
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

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

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

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

### Interactive Installation

```typescript
// 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

```typescript
// 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

```typescript
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`

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

### `InstallResult`

```typescript
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`

```typescript
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`

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

## License 📄

MIT License

**Author:** Estarlin R ([estarlincito.com](https://estarlincito.com))