This library includes tools to fetch and save package information from pkgx.dev.
npm install ts-pkgx bun install ts-pkgxThe library includes a comprehensive CLI tool to manage packages from pkgx.dev:
# Fetch a single package bun run pkgx:fetch node # Fetch multiple packages bun run pkgx:fetch --pkg "node,python,go" # With custom output directory bun run pkgx:fetch node --output-dir ./data/packages # Fetch all packages bun run pkgx:fetch-all # Set options for fetching bun run pkgx:fetch-all --timeout 180000 --output-dir ./data/packages --limit 100 # Generate documentation bun run pkgx:docs # Update local pantry cache bun ./bin/cli.ts update-pantry # Generate TypeScript files from cache bun ./bin/cli.ts generate-ts # Generate package index bun ./bin/cli.ts generate-index # Generate package aliases bun ./bin/cli.ts generate-aliases # Generate constants file bun ./bin/cli.ts generate-consts # Resolve dependency files and transitive dependencies bun ./bin/cli.ts resolve-deps deps.yaml # Get PHP versions for CI/CD workflows bun ./bin/cli.ts get-php-versions bun ./bin/cli.ts get-php-versions --format yaml bun ./bin/cli.ts get-php-versions --branches 8.4,8.3 --format csvts-pkgx includes a powerful dependency resolver that can analyze dependency files and resolve all transitive dependencies:
# Resolve a single dependency file bun ./bin/cli.ts resolve-deps deps.yaml --verbose --install-command # Find and resolve all dependency files in a project bun ./bin/cli.ts resolve-deps --find-files ./my-project # Output as JSON for automation bun ./bin/cli.ts resolve-deps deps.yaml --json # Filter for specific OS bun ./bin/cli.ts resolve-deps deps.yaml --target-os darwin --include-os-depsts-pkgx also provides comprehensive Integration APIs designed for package managers and deployment tools that need advanced dependency resolution:
import { resolveDependencies } from 'ts-pkgx' // Resolve dependencies from a YAML file const result = await resolveDependencies('./deps.yaml', { targetOs: 'darwin', includeOsSpecific: true }) console.log(`Installing ${result.totalCount} packages...`) // Install each resolved package for (const pkg of result.packages) { await launchpad.install(pkg.name, pkg.version) }Key Features:
- 🔍 Deep transitive dependency resolution - Automatically resolves all nested dependencies
- ⚡ Version conflict resolution - Intelligently handles conflicting version constraints
- 🎯 OS-specific dependencies - Platform-aware dependency resolution
- 📄 Multiple input formats - YAML files, strings, and individual packages
- 🔧 Semantic versioning - Full semver constraint support (^, ~, >=, etc.)
For detailed integration examples and API documentation, see the Launchpad Integration Guide.
You can also use the library programmatically in your code:
import { fetchAndSaveAllPackages, fetchPantryPackage, fetchPantryPackageWithMetadata, findDependencyFiles, resolveDependencies, resolveDependenciesFromYaml, resolveDependencyFile, resolvePackageDependencies, savePackageAsTypeScript, saveToCacheAndOutput } from 'ts-pkgx' // Fetch a single package using pkgx.dev const nodePackage = await fetchPantryPackage('node') console.log(nodePackage) // Fetch package with metadata from pantry const packageWithMeta = await fetchPantryPackageWithMetadata('node', { timeout: 30000, debug: false }) // Fetch and save all packages const savedPackages = await fetchAndSaveAllPackages({ timeout: 120000, outputDir: 'src/packages', concurrency: 8 }) console.log(`Saved ${savedPackages.length} packages`) // Save package as TypeScript file if (packageWithMeta) { const filePath = savePackageAsTypeScript('src/packages', 'node', packageWithMeta.packageInfo) console.log(`Saved to ${filePath}`) } // Resolve dependency files and transitive dependencies const depFiles = findDependencyFiles('./my-project') for (const file of depFiles) { const result = await resolveDependencyFile(file, { pantryDir: 'src/pantry', packagesDir: 'src/packages', maxDepth: 10, verbose: true, }) console.log(`${file}: Found ${result.uniquePackages.length} unique packages`) if (result.conflicts.length > 0) { console.log(`Resolved ${result.conflicts.length} version conflicts`) } } // Launchpad Integration API - Resolve dependencies for package managers const launchpadResult = await resolveDependencies('./deps.yaml', { targetOs: 'darwin', includeOsSpecific: true, maxDepth: 10, verbose: false }) console.log(`Launchpad: Installing ${launchpadResult.totalCount} packages`) console.log(`Direct dependencies: ${launchpadResult.directCount}`) console.log(`Version conflicts resolved: ${launchpadResult.conflicts.length}`) // Install commands ready for use (both use direct deps only) console.log('Launchpad:', launchpadResult.launchpadCommand) console.log('pkgx:', launchpadResult.pkgxCommand) // Resolve from YAML string const yamlContent = ` global: true dependencies: bun.sh: ^1.2.16 gnu.org/grep: ^3.12.0 ` const yamlResult = await resolveDependenciesFromYaml(yamlContent) // Resolve single package dependencies const grepDeps = await resolvePackageDependencies('gnu.org/grep') console.log(`grep has ${grepDeps.length} total dependencies`) // Get PHP versions for CI/CD workflows const { getPhpVersionsForWorkflow } = await import('ts-pkgx') const workflowVersions = getPhpVersionsForWorkflow() console.log('Latest PHP versions for CI:', workflowVersions) // Output: ['8.4.11', '8.3.24', '8.2.29', '8.1.32']ts-pkgx provides comprehensive TypeScript types for all packages in the pkgx.dev ecosystem, enabling you to work in a fully typed environment with extensive type safety features:
import type { LaunchpadInstallResult, // Launchpad API result type LaunchpadPackage, // Individual package in Launchpad result LaunchpadResolverOptions, // Launchpad resolution options PackageFetchOptions, // Options for fetching packages Packages, // Type alias for Pantry Pantry, // Complete pantry type with all packages PkgxPackage // Package information interface } from 'ts-pkgx' import { aliases, // Package aliases mapping pantry // Access to all packages with full type safety } from 'ts-pkgx' // Access packages with full type safety using domain-based properties const nodePackage = pantry.nodejs_org const pythonPackage = pantry.python_org const goPackage = pantry.go_dev const bunPackage = pantry.bun_sh // Alternative access using underscored domain names const curlPackage = pantry.curl_se const gitPackage = pantry.git_scm_org // All package properties are fully typed console.log(nodePackage.name) // string: 'nodejs.org' console.log(nodePackage.domain) // string: 'nodejs.org' console.log(nodePackage.description) // string: package description console.log(nodePackage.programs) // readonly string[]: ['node', 'npm', 'npx'] console.log(nodePackage.versions) // readonly string[]: available versions console.log(nodePackage.installCommand) // string: 'launchpad install nodejs.org' console.log(nodePackage.companions) // readonly string[]: companion packages console.log(nodePackage.dependencies) // readonly string[]: dependencies // Type-safe access with aliases const alias = aliases.node // 'nodejs.org' const packageByAlias = pantry[aliases.node as keyof Pantry] // Package fetching with typed options const fetchOptions: PackageFetchOptions = { timeout: 30000, outputDir: 'src/packages', cacheDir: '.cache', debug: false, concurrency: 8 }The type system includes:
- Comprehensive type safety: All package properties and operations are type-checked
- Pantry types: Full type definitions for all packages in the pkgx ecosystem
- Package interfaces: Detailed typed interfaces for package metadata
- Fetch options: Type-safe configuration for package fetching operations
- Domain mapping: Both domain names and underscored variants for flexible access
- Alias support: Type-safe alias resolution for common package names
- Auto-completion: Full IntelliSense support in your IDE for all 1600+ packages
bun testbun testbun run build# Update the local pantry cache bun ./bin/cli.ts update-pantry # Regenerate all package TypeScript files bun ./bin/cli.ts fetch --all # Generate documentation bun ./bin/cli.ts generate-docsPlease see our releases page for information on changes.
Please see CONTRIBUTING for details.
For help or discussion:
"Software that is free, but hopes for a postcard." We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.
Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎
- Max Howell - for creating pkgx and Homebrew
- pkgm & dev - thanks for the inspiration
- Chris Breuer
- All Contributors
We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.
The MIT License (MIT). Please see LICENSE for more information.
Made with 💙
