TypeScript Package Manager Library & CLI

0.4.154 verified Thu Apr 23 auth: no javascript

ts-pkgx is a TypeScript-first library and command-line interface (CLI) designed for managing software packages across different environments. It provides a programmatic API that allows developers to integrate package management functionalities directly into their applications, abstracting away the specifics of underlying package managers. Concurrently, it offers a robust CLI for direct system-level operations, similar in scope to universal package managers like Homebrew or the package handling capabilities within modern runtimes like Bun. The current stable version is 0.4.154. It exhibits a highly rapid release cadence, with numerous patch versions (e.g., v0.4.144 through v0.4.154) often released in close succession, though recent updates frequently state 'No significant changes.' This suggests an active but perhaps automated development and release workflow. Its primary differentiation lies in offering a cohesive TypeScript-friendly library interface alongside a powerful command-line tool, enabling both application-embedded and standalone package lifecycle management.

Common errors

error Error: EACCES: permission denied, unlink '/usr/local/bin/some-package' ↓

cause Attempting to install or uninstall a system-level package without sufficient administrator privileges.

fix

Run the command with sudo (e.g., sudo npx ts-pkgx install <package>) or ensure the executing user/process has write access to the target directories.

error TypeError: Cannot read properties of undefined (reading 'installPackage') ↓

cause Incorrect import statement (e.g., using `require` for an ESM-only package or a default import for a named export).

fix

Verify that your tsconfig.json targets ES2020 or higher with module: 'NodeNext' or 'ESNext', and use import { installPackage } from 'ts-pkgx';.

error Package '<package-name>' not found in known registries/providers. ↓

cause The specified package does not exist in the configured underlying package manager's repositories, or ts-pkgx does not support that particular package/ecosystem.

fix

Double-check the package name for typos. Verify ts-pkgx's documentation for supported package types and sources, and ensure the necessary underlying package managers (e.g., Homebrew) are installed and configured.

Warnings

gotcha ts-pkgx operates on system-level packages, not necessarily npm dependencies. Ensure you understand which package manager (e.g., Homebrew, apt, etc.) it might be interacting with under the hood for your specific OS and environment. ↓

fix Consult the official documentation for supported package manager integrations and configuration options before assuming behavior.

breaking While recent releases show 'No significant changes', the rapid patch version increments (e.g., 0.4.144 to 0.4.154 in quick succession) suggest an active development lifecycle where minor breaking changes or API shifts could occur without a major version bump. Always review changelogs. ↓

fix Pin to exact patch versions in production environments (`"ts-pkgx": "~0.4.154"` or `"ts-pkgx": "0.4.154"`) and thoroughly test updates before deployment.

gotcha Permissions are critical for system-level package management. Running ts-pkgx commands or library functions that modify the system (install, uninstall) might require elevated privileges (e.g., `sudo` on Linux/macOS) which can lead to errors if not handled correctly. ↓

fix Ensure the user or process executing ts-pkgx has the necessary permissions. For library calls, handle potential permission-denied errors gracefully.

Install

npm install ts-pkgx

yarn add ts-pkgx

pnpm add ts-pkgx

Imports

installPackage
wrong
```
const { installPackage } = require('ts-pkgx');
```
correct
```
import { installPackage } from 'ts-pkgx';
```
ts-pkgx is primarily designed for ESM usage with TypeScript. CJS `require` is generally not recommended.
uninstallPackage
wrong
```
import uninstallPackage from 'ts-pkgx';
```
correct
```
import { uninstallPackage } from 'ts-pkgx';
```
All core functionalities are named exports, not default exports.
listPackages
wrong
```
import { listPackages as getPackages } from 'ts-pkgx/dist/index';
```
correct
```
import { listPackages } from 'ts-pkgx';
```
Always import directly from the main package entry point. Aliasing is fine, but avoid deep imports.

Quickstart

This example demonstrates how to programmatically install, list, get details for, and uninstall a package using the ts-pkgx library functions, along with comments on CLI usage.

import { installPackage, uninstallPackage, listPackages, getPackageDetails } from 'ts-pkgx';

async function managePackages() {
  console.log('--- Installing a package (example: 'pkg-utils') ---');
  try {
    const installResult = await installPackage('pkg-utils');
    console.log(`Installation successful: ${installResult.packageName} version ${installResult.version}`);
  } catch (error) {
    console.error('Installation failed:', error instanceof Error ? error.message : String(error));
  }

  console.log('\n--- Listing all installed packages ---');
  const allPackages = await listPackages();
  console.log('Installed packages:', allPackages.map(p => `${p.name}@${p.version}`).join(', '));

  console.log('\n--- Getting details for a specific package ---');
  const pkgDetails = await getPackageDetails('pkg-utils');
  if (pkgDetails) {
    console.log(`Details for pkg-utils: Path=${pkgDetails.path}, Description=${pkgDetails.description}`);
  } else {
    console.log('pkg-utils not found or details unavailable.');
  }

  console.log('\n--- Uninstalling the package ---');
  try {
    const uninstallResult = await uninstallPackage('pkg-utils');
    console.log(`Uninstallation successful: ${uninstallResult.packageName}`);
  } catch (error) {
    console.error('Uninstallation failed:', error instanceof Error ? error.message : String(error));
  }
}

managePackages();

// To use the CLI, assuming ts-pkgx is globally installed or available via npx:
// npx ts-pkgx install pkg-utils
// npx ts-pkgx list
// npx ts-pkgx info pkg-utils
// npx ts-pkgx uninstall pkg-utils