TypeScript Package Manager Skill

An expert skill for managing TypeScript projects with comprehensive knowledge of modern package management tools and ecosystem best practices. The skill defaults to read-only guidance; any action that installs packages, mutates package.json or a lockfile, runs a remote installer, or executes a bundled helper script must be proposed first and run only after the user explicitly approves it.

Safety and Trust Model

Inspect before executing. The bundled helpers under scripts/ (notably bun-workflow.js.txt and health-check.js.txt) shell out to local tools via child_process.execSync. They ship with a .js.txt extension so they are not directly executable; open and read each one, rename it back to .js only inside a trusted project working directory you control, and run it only after confirming the exact command.
Verify remote installers. Any documented one-liner that fetches code from the network (for example curl -fsSL https://bun.sh/install | bash or powershell -c "irm bun.sh/install.ps1 | iex") executes whatever the upstream serves at that moment. Confirm the URL, prefer the official downloaded installer or your OS package manager, and pin to a known version when stricter review is required.
Approve dependency changes explicitly. Treat installs, updates, removals, audits with --fix, and lockfile regenerations as mutating actions. Surface the exact command and the expected package.json / lockfile diff first, then proceed only after the user confirms.
Provenance disclosure. The helper scripts in this skill are local to this repository and are not currently published with an upstream source or homepage in the registry metadata. Treat them as untrusted code until you have read them, and prefer skills with clear provenance when execution is involved.

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

All of the following are mutating operations: propose the exact command, show the expected package.json and lockfile diff, and execute only after explicit user approval.

Installing, updating, and removing dependencies (requires approval and diff review)
Managing dev dependencies vs production dependencies
Understanding peer dependencies and optional dependencies
Resolving version conflicts and compatibility issues
Audit and security vulnerability management (read-only by default; --fix flags require approval)
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

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
Lock File Discipline: Always commit lock files to ensure reproducible builds across environments
Semantic Versioning: Use appropriate version constraints
- Use ^ (caret) for most dependencies (recommended)
- Use ~ (tilde) for conservative updates
- Use exact versions only when necessary

Security First: Regularly audit dependencies for vulnerabilities

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

Workspace Optimization: Leverage workspaces for monorepo efficiency and shared dependencies
Script Consistency: Use cross-platform compatible scripts (avoid shell-specific commands)
Minimal Dependencies: Avoid unnecessary packages to reduce complexity, security surface, and bundle size
Documentation: Document package manager choice, special configurations, and setup instructions in README.md

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

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. The helper sources ship with a .js.txt extension so they are inert until a user explicitly renames them to .js; they execute local shell commands through child_process.execSync (for example bun-workflow.js.txt line 45 and health-check.js.txt line 47 to detect tool versions). Read each helper before renaming, run it only inside a trusted project directory, and prefer the .md walkthroughs when you only need reference material.

npm-workflow.md / npm-workflow.js.txt - Complete npm workflow from initialization to publishing (rename to .js before running with Node)
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.txt - Complete bun workflow for ultra-fast package management (rename to .js before running). The documented Bun installer one-liners (curl … | bash, irm … | iex) fetch and execute remote code; verify the source URL and prefer a pinned, downloaded installer when stricter review is required.
health-check.md / health-check.js.txt - Package manager health check and diagnostics scripts (rename to .js before running)

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