ts-pkgx

This library includes tools to fetch and save package information from pkgx.dev.

Installation

npm install ts-pkgx
bun install ts-pkgx

Usage

CLI Tool

The 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

Programmatic Usage

You can also use the library programmatically in your code:

import {
  fetchAndSaveAllPackages,
  fetchPantryPackage,
  fetchPantryPackageWithMetadata,
  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}`)
}

TypeScript Types

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 {
  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

Running Tests

bun test

Development

Running Tests

bun test

Building the Package

bun run build

Updating Packages

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

Changelog

Please see our releases page for information on changes.

Contributing

Please see CONTRIBUTING for details.

Community

For help or discussion:

• Discussions on GitHub
• Join the Stacks Discord Server

Postcardware

"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 🌎

Credits

• Max Howell - for creating pkgx and Homebrew
• pkgm & dev - thanks for the inspiration
• Chris Breuer
• All Contributors

Sponsors

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.

• JetBrains
• The Solana Foundation

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙