TypeScript Package Manager Skill

An expert skill for managing TypeScript projects with comprehensive knowledge of modern package management tools and ecosystem best practices.

When to Use This Skill

• Setting up or configuring package managers (npm, yarn, pnpm, bun, deno)
• Managing project dependencies and resolving conflicts
• Optimizing package.json configuration
• Working with monorepos and workspaces
• Troubleshooting installation or dependency issues
• Configuring package scripts and build pipelines
• Understanding lock files and version constraints
• Integrating package managers with build tools
• Migrating between package managers
• Performance optimization of package operations

Prerequisites

• Node.js environment (for npm, yarn, pnpm, bun)
• Basic understanding of TypeScript/JavaScript projects
• Terminal/command line access
• Understanding of semantic versioning (semver)

Shorthand Keywords

Keywords to trigger this skill quickly:

openPrompt = ["typescript-package-manager", "ts-pkg", "pkg-manager"]

Use these shorthand commands for quick invocation:

• ts-pkg --install <package>
• pkg-manager --compare-tools
• ts-pkg migrate to pnpm
• pkg-manager --optimize workspace

Core Capabilities

Package Manager Expertise

This skill provides deep knowledge across all major JavaScript/TypeScript package managers:

• npm: The default Node.js package manager, widely used and battle-tested
• yarn: Fast, reliable package manager with enhanced features
• pnpm: Disk-space efficient with strict dependency isolation
• bun: Ultra-fast all-in-one toolkit with native package management
• deno: Secure-by-default runtime with built-in tooling

Dependency Management

• Installing, updating, and removing dependencies
• Managing dev dependencies vs production dependencies
• Understanding peer dependencies and optional dependencies
• Resolving version conflicts and compatibility issues
• Audit and security vulnerability management
• Dependency deduplication and optimization

Configuration and Optimization

• package.json structure and best practices
• Lock file management (package-lock.json, yarn.lock, pnpm-lock.yaml)
• Workspace and monorepo configuration
• Scripts and lifecycle hooks
• Registry configuration and private packages
• CI/CD integration

Ecosystem Integration

• TypeScript compiler (tsc) integration with package managers
• Build tool configuration (Vite, webpack, esbuild, Rollup, Turbopack)
• Testing framework setup (Vitest, Jest, Mocha)
• Linting and formatting tools (ESLint, Prettier)
• Development server configuration and hot reload
• CI/CD pipeline optimization

Key Concepts

Semantic Versioning (semver)

Understanding version constraints in package.json:

• ^1.2.3 (caret): >=1.2.3 <2.0.0 - Allows minor and patch updates (recommended)
• ~1.2.3 (tilde): >=1.2.3 <1.3.0 - Allows only patch updates
• 1.2.3 (exact): Exact version only
• >=1.2.3 <2.0.0 (range): Custom version range
• latest: Always use latest version (dangerous, not recommended)

Lock Files

Lock files ensure reproducible installations across environments:

• package-lock.json (npm): JSON format, exact dependency tree
• yarn.lock (yarn): YAML-like format, deterministic resolution
• pnpm-lock.yaml (pnpm): YAML format with content-addressable storage
• bun.lockb (bun): Binary format for fast parsing

Best Practice: Always commit lock files to version control.

Workspaces (Monorepos)

Manage multiple packages in a single repository:

{
  "workspaces": ["packages/*", "apps/*"]
}

Benefits:

• Shared dependencies across packages
• Cross-package development and testing
• Unified versioning and release coordination
• Simplified dependency management

Best Practices

1. Choose the Right Tool: Understand trade-offs between package managers for your project needs

   • npm: Maximum compatibility, widest ecosystem support
   • yarn: Enhanced features, good monorepo support
   • pnpm: Best disk space efficiency, strict dependencies
   • bun: Maximum speed, all-in-one tooling
   • deno: Security-first, URL-based imports

2. Lock File Discipline: Always commit lock files to ensure reproducible builds across environments

3. Semantic Versioning: Use appropriate version constraints

   • Use ^ (caret) for most dependencies (recommended)
   • Use ~ (tilde) for conservative updates
   • Use exact versions only when necessary

4. Security First: Regularly audit dependencies for vulnerabilities

   npm audit      # npm
   yarn audit     # yarn
   pnpm audit     # pnpm
   bun pm audit   # bun
   

5. Workspace Optimization: Leverage workspaces for monorepo efficiency and shared dependencies

6. Script Consistency: Use cross-platform compatible scripts (avoid shell-specific commands)

7. Minimal Dependencies: Avoid unnecessary packages to reduce complexity, security surface, and bundle size

8. Documentation: Document package manager choice, special configurations, and setup instructions in README.md

9. CI/CD Optimization: Use frozen lockfiles in CI for deterministic builds

   npm ci                                    # npm
   yarn install --frozen-lockfile            # yarn
   pnpm install --frozen-lockfile            # pnpm
   bun install --frozen-lockfile             # bun
   

10. Version Management: Use packageManager field in package.json to enforce consistency

    {
      "packageManager": "pnpm@8.15.0"
    }
    

Choosing the Right Package Manager

Decision Factors

npm (Default Choice)

• ✅ Maximum compatibility and ecosystem support
• ✅ Default with Node.js, no additional setup
• ✅ Well-tested and mature
• ❌ Slower than alternatives
• ❌ Less disk-efficient

yarn (Enhanced Features)

• ✅ Good performance and caching
• ✅ Excellent monorepo/workspace support
• ✅ Plug'n'Play mode (Berry) for zero-installs
• ❌ Classic vs Berry version confusion
• ❌ Plug'n'Play requires IDE setup

pnpm (Recommended for Most Projects)

• ✅ 60-70% disk space savings
• ✅ 2-3x faster than npm
• ✅ Strict dependency isolation prevents phantom dependencies
• ✅ Excellent monorepo support
• ❌ May expose hidden dependency issues

bun (Cutting Edge)

• ✅ Blazing fast (5-10x faster than npm)
• ✅ All-in-one: runtime, bundler, test runner
• ✅ Native TypeScript support
• ❌ Newer and less mature
• ❌ Some npm package incompatibilities

deno (Security-First)

• ✅ Secure by default with explicit permissions
• ✅ Native TypeScript support
• ✅ No package.json or node_modules
• ❌ Different paradigm (URL-based imports)
• ❌ Smaller ecosystem than npm

Quick Recommendation

• New TypeScript project: pnpm or bun
• Existing project: Keep current manager unless migrating for specific benefits
• Monorepo: pnpm or yarn (berry)
• Maximum compatibility: npm
• Security-critical: deno or pnpm

Common Tasks

Installing Dependencies

# npm
npm install

# yarn
yarn install

# pnpm
pnpm install

# bun
bun install

Adding New Dependencies

# Production dependency
npm install package-name
yarn add package-name
pnpm add package-name
bun add package-name

# Development dependency
npm install --save-dev package-name
yarn add --dev package-name
pnpm add --save-dev package-name
bun add --dev package-name

Running Scripts

# All package managers support npm scripts
npm run script-name
yarn script-name
pnpm script-name
bun run script-name

Troubleshooting

Common Issues

Installation Failures:

• Clear cache and retry
• Delete node_modules and lock file, reinstall
• Check for incompatible peer dependencies
• Verify Node.js version compatibility

Version Conflicts:

• Use resolutions/overrides in package.json
• Upgrade conflicting dependencies
• Consider using pnpm for better isolation

Performance Issues:

• Use pnpm or bun for faster operations
• Enable caching mechanisms
• Optimize workspace configuration

Lock File Conflicts:

• Resolve merge conflicts carefully
• Regenerate lock file if corrupted
• Ensure team uses same package manager

References

See the references/ folder for detailed documentation:

• package-management.md - Comprehensive guide to JavaScript/TypeScript package managers including npm, yarn, pnpm, bun, deno, with concepts, version management, security, and best practices
• integration-with-build-tools.md - Complete guide to integrating package managers with Vite, webpack, esbuild, Rollup, TypeScript compiler (tsc), and CI/CD pipelines

Scripts

See the scripts/ folder for workflow guides and automation:

• npm-workflow.md / npm-workflow.js - Complete npm workflow from initialization to publishing
• yarn-workflow.md - Complete yarn workflow covering Classic (1.x) and Berry (3.x+) versions
• pnpm-workflow.md - Complete pnpm workflow with monorepo and workspace features
• bun-workflow.md / bun-workflow.js - Complete bun workflow for ultra-fast package management
• health-check.md / health-check.js - Package manager health check and diagnostics scripts

Assets

See the assets/ folder for templates and reference materials:

• package-manager-comparison.md - Detailed comparison matrix, benchmarks, and decision tree for choosing package managers
• package-json-template.md - Production-ready package.json template with field-by-field explanations and best practices