Files

T

fargo 1a822493ba format: apply repo prettier (3.8.1) to the folded skills tree

963 markdown files reformatted with the repository's pinned prettier so
pnpm format:check covers the folded tree like every other repo file.

The formatter's embedded-language pass also normalized code fences
(TS semicolons, closed HTML tags in examples, lowercased CSS hex colors,
one renumbered list that skipped an index). Alphanumeric token deltas vs
the fold commit were audited file-by-file; all are formatter-equivalent
markup normalizations plus the four sanitized skills.

2026-08-19 14:37:17 -05:00

2.9 KiB

Raw Blame History

name, description

name	description
pnpm-aliases	Install packages under custom names for versioning, forks, or alternatives

pnpm Aliases

pnpm supports package aliases using the npm: protocol. This lets you install packages under different names, use multiple versions of the same package, or substitute packages.

Basic Syntax

pnpm add <alias>@npm:<package>@<version>

In package.json:

{
  "dependencies": {
    "<alias>": "npm:<package>@<version>"
  }
}

Use Cases

Multiple Versions of Same Package

Install different versions side by side:

{
  "dependencies": {
    "lodash3": "npm:lodash@3",
    "lodash4": "npm:lodash@4"
  }
}

Usage:

import lodash3 from 'lodash3';
import lodash4 from 'lodash4';

Replace Package with Fork

Substitute a package with a fork or alternative:

{
  "dependencies": {
    "original-pkg": "npm:my-fork@^1.0.0"
  }
}

All imports of original-pkg will resolve to my-fork.

Replace Deprecated Package

{
  "dependencies": {
    "request": "npm:@cypress/request@^3.0.0"
  }
}

Scoped to Unscoped (or vice versa)

{
  "dependencies": {
    "vue": "npm:@anthropic/vue@^3.0.0",
    "@myorg/utils": "npm:lodash@^4.17.21"
  }
}

CLI Usage

Add with alias

# Add lodash under alias
pnpm add lodash4@npm:lodash@4

# Add fork as original name
pnpm add request@npm:@cypress/request

Add multiple versions

pnpm add react17@npm:react@17 react18@npm:react@18

With TypeScript

For type resolution with aliases, you may need to configure TypeScript:

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "lodash3": ["node_modules/lodash3"],
      "lodash4": ["node_modules/lodash4"]
    }
  }
}

Or use @types packages with aliases:

{
  "devDependencies": {
    "@types/lodash3": "npm:@types/lodash@3",
    "@types/lodash4": "npm:@types/lodash@4"
  }
}

Combined with Overrides

Force all transitive dependencies to use an alias:

# pnpm-workspace.yaml
overrides:
  'underscore': 'npm:lodash@^4.17.21'

This replaces all underscore imports (including in dependencies) with lodash.

Git and Local Aliases

Aliases work with any valid pnpm specifier:

{
  "dependencies": {
    "my-fork": "npm:user/repo#commit",
    "local-pkg": "file:../local-package"
  }
}

Best Practices

Clear naming: Use descriptive alias names that indicate purpose

"lodash-legacy": "npm:lodash@3"
"lodash-modern": "npm:lodash@4"

Document aliases: Add comments or documentation explaining why aliases exist
Prefer overrides for global replacement: If you want to replace a package everywhere, use overrides instead of aliases
Test thoroughly: Aliased packages may have subtle differences in behavior

2.9 KiB Raw Blame History