{"id":17985,"library":"ts-pkgx","title":"TypeScript Package Manager Library & CLI","description":"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.","status":"active","version":"0.4.154","language":"javascript","source_language":"en","source_url":"https://github.com/stacksjs/ts-pkgx","tags":["javascript","pkgx","pantry","homebrew","typescript","bun","package","cli","library"],"install":[{"cmd":"npm install ts-pkgx","lang":"bash","label":"npm"},{"cmd":"yarn add ts-pkgx","lang":"bash","label":"yarn"},{"cmd":"pnpm add ts-pkgx","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ts-pkgx is primarily designed for ESM usage with TypeScript. CJS `require` is generally not recommended.","wrong":"const { installPackage } = require('ts-pkgx');","symbol":"installPackage","correct":"import { installPackage } from 'ts-pkgx';"},{"note":"All core functionalities are named exports, not default exports.","wrong":"import uninstallPackage from 'ts-pkgx';","symbol":"uninstallPackage","correct":"import { uninstallPackage } from 'ts-pkgx';"},{"note":"Always import directly from the main package entry point. Aliasing is fine, but avoid deep imports.","wrong":"import { listPackages as getPackages } from 'ts-pkgx/dist/index';","symbol":"listPackages","correct":"import { listPackages } from 'ts-pkgx';"}],"quickstart":{"code":"import { installPackage, uninstallPackage, listPackages, getPackageDetails } from 'ts-pkgx';\n\nasync function managePackages() {\n  console.log('--- Installing a package (example: 'pkg-utils') ---');\n  try {\n    const installResult = await installPackage('pkg-utils');\n    console.log(`Installation successful: ${installResult.packageName} version ${installResult.version}`);\n  } catch (error) {\n    console.error('Installation failed:', error instanceof Error ? error.message : String(error));\n  }\n\n  console.log('\\n--- Listing all installed packages ---');\n  const allPackages = await listPackages();\n  console.log('Installed packages:', allPackages.map(p => `${p.name}@${p.version}`).join(', '));\n\n  console.log('\\n--- Getting details for a specific package ---');\n  const pkgDetails = await getPackageDetails('pkg-utils');\n  if (pkgDetails) {\n    console.log(`Details for pkg-utils: Path=${pkgDetails.path}, Description=${pkgDetails.description}`);\n  } else {\n    console.log('pkg-utils not found or details unavailable.');\n  }\n\n  console.log('\\n--- Uninstalling the package ---');\n  try {\n    const uninstallResult = await uninstallPackage('pkg-utils');\n    console.log(`Uninstallation successful: ${uninstallResult.packageName}`);\n  } catch (error) {\n    console.error('Uninstallation failed:', error instanceof Error ? error.message : String(error));\n  }\n}\n\nmanagePackages();\n\n// To use the CLI, assuming ts-pkgx is globally installed or available via npx:\n// npx ts-pkgx install pkg-utils\n// npx ts-pkgx list\n// npx ts-pkgx info pkg-utils\n// npx ts-pkgx uninstall pkg-utils","lang":"typescript","description":"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."},"warnings":[{"fix":"Consult the official documentation for supported package manager integrations and configuration options before assuming behavior.","message":"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.","severity":"gotcha","affected_versions":">=0.4.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Ensure the user or process executing ts-pkgx has the necessary permissions. For library calls, handle potential permission-denied errors gracefully.","message":"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.","severity":"gotcha","affected_versions":">=0.4.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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.","cause":"Attempting to install or uninstall a system-level package without sufficient administrator privileges.","error":"Error: EACCES: permission denied, unlink '/usr/local/bin/some-package'"},{"fix":"Verify that your `tsconfig.json` targets `ES2020` or higher with `module: 'NodeNext'` or `'ESNext'`, and use `import { installPackage } from 'ts-pkgx';`.","cause":"Incorrect import statement (e.g., using `require` for an ESM-only package or a default import for a named export).","error":"TypeError: Cannot read properties of undefined (reading 'installPackage')"},{"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.","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.","error":"Package '<package-name>' not found in known registries/providers."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}