pnpm-dep-source

CLI to switch pnpm dependencies between local, GitHub / GitLab, and NPM sources.

Installation

npm install -g pnpm-dep-source
# or
pnpm add -g pnpm-dep-source

Usage

Initialize a dependency

# From local path - auto-detects GitHub/GitLab from package.json or git remote
pds init ../../path/to/local/pkg

# From GitHub/GitLab URL
pds init https://github.com/user/repo
pds init https://gitlab.com/user/repo

# Override or specify repo explicitly
pds init ../../path/to/local/pkg -H github-user/repo
pds init ../../path/to/local/pkg -L gitlab-user/repo

# Global CLI tools (uses ~/.config/pnpm-dep-source/config.json)
pds init /path/to/local/cli -g

init adds the dependency to package.json if not present, then auto-activates:

• Local path → switches to workspace:* mode
• GitHub URL → switches to github:user/repo#sha
• GitLab URL → switches to GitLab tarball URL

Use -D to add as a devDependency, or -I to skip adding/activation entirely.

Switch to local development

pds local [dep]    # or pds l [dep]

Note: [dep] is optional if only one dependency is configured.

This will:

• Set package.json dependency to workspace:*
• Create/update pnpm-workspace.yaml with the local path
• Add to vite.config.ts optimizeDeps.exclude (if vite config exists)
• Run pnpm install

Switch to GitHub or GitLab (auto-detect)

pds g [dep]                   # Auto-detects GitHub or GitLab (uses dist branch HEAD)
pds g [dep] -r v1.0.0         # Resolves ref to SHA
pds g [dep] -R dist           # Uses ref as-is (pin to branch name)

Errors if neither or both are configured; use pds gh or pds gl explicitly in that case.

Switch to GitHub

pds github [dep]              # Uses dist branch HEAD (resolved to SHA)
pds gh [dep] -r v1.0.0        # Resolves ref to SHA
pds gh [dep] -R dist          # Uses ref as-is (pin to branch name)

This will:

• Set package.json dependency to github:user/repo#sha
• Remove local path from pnpm-workspace.yaml
• Remove from vite.config.ts optimizeDeps.exclude
• Run pnpm install

Switch to GitLab

pds gitlab [dep]              # Uses dist branch HEAD (resolved to SHA)
pds gl [dep] -r v1.0.0        # Resolves ref to SHA
pds gl [dep] -R dist          # Uses ref as-is (pin to branch name)

This will:

• Set package.json dependency to GitLab tarball URL
• Remove local path from pnpm-workspace.yaml
• Remove from vite.config.ts optimizeDeps.exclude
• Run pnpm install

Note: GitLab uses tarball URLs (e.g. https://gitlab.com/user/repo/-/archive/ref/repo-ref.tar.gz) since pnpm doesn't support gitlab: prefix.

Switch to NPM

pds npm [dep]              # Latest version
pds npm [dep] [version]    # Specific version
pds n 1.2.3                # With one dep, arg is treated as version

Check status

pds status           # Show all configured deps
pds status [dep]     # Show specific dep
pds s                # Alias

List configured dependencies

pds         # defaults to list
pds list    # or pds ls

Update dependency fields

pds set <dep> -H user/repo      # Set GitHub repo
pds set <dep> -L user/repo      # Set GitLab repo
pds set <dep> -l ../path        # Set local path
pds set <dep> -n pkg-name       # Set NPM name
pds set <dep> -H ""             # Remove GitHub
pds set -g                      # Update global config (with single dep)

Remove a dependency from config

pds deinit [dep]    # or pds rm [dep]
pds rm -g           # Remove from global config

This removes the dependency from .pnpm-dep-source.json but does not modify package.json.

Pre-commit hooks

Prevent accidentally committing with local dependencies:

pds hooks install    # Install global pre-commit hook
pds hooks uninstall  # Remove it
pds hooks status     # Check installation status

The hook runs pds check before each commit, blocking if any pds-managed dependencies are set to workspace:*. Bypass with git commit --no-verify when needed.

Uses git config --global core.hooksPath to apply to all repositories. The hook chains to:

• Any previously configured core.hooksPath (saved and restored on uninstall)
• Local .git/hooks/pre-commit if present (normally ignored when core.hooksPath is set)

To disable the check for a specific project, add "skipCheck": true to .pnpm-dep-source.json.

Check for local dependencies

pds check            # Exits non-zero if any deps are local
pds check -q         # Quiet mode (exit code only)

Show pds info

pds info             # Show version and install source

Config file

The tool stores configuration in .pnpm-dep-source.json:

{
  "dependencies": {
    "@scope/package-name": {
      "localPath": "../../path/to/local",
      "github": "user/repo",
      "gitlab": "user/repo",
      "npm": "@scope/package-name",
      "distBranch": "dist"
    }
  },
  "skipCheck": false
}

Set "skipCheck": true to disable the pre-commit hook check for this project.

Options

• -b, --dist-branch <branch>: Dist branch name (default: "dist")
• -D, --dev: Add as devDependency (for init when adding to package.json)
• -f, --force: Suppress mismatch warnings in init
• -g, --global: Use global config (~/.config/pnpm-dep-source/config.json) for CLI tools
• -H, --github <repo>: GitHub repo (auto-detected from package.json if not specified)
• -I, --no-install: Skip running pnpm install after changes
• -l, --local <path>: Local path (for init with URL, or set command)
• -L, --gitlab <repo>: GitLab repo (auto-detected from package.json if not specified)
• -n, --npm <name>: NPM package name (defaults to package name)
• -r, --ref <ref>: Git ref, resolved to SHA (for github/gitlab commands)
• -R, --raw-ref <ref>: Git ref, used as-is (pin to branch/tag name)

Global CLI tools

For managing globally-installed CLI tools, use -g with all commands:

# Initialize a global CLI tool
pds init /path/to/local/cli -g -H github-user/repo

# List global deps
pds ls -g

# Switch global install source
pds gh -g            # Install from GitHub dist branch
pds l -g             # Install from local directory
pds n -g             # Install from NPM

Global config is stored at ~/.config/pnpm-dep-source/config.json.

Recommended workflow

1. Local development: Use pds local <dep> to develop against a local copy
2. Integration testing: Push to GitHub/GitLab, build a dist branch, use pds gh <dep> or pds gl <dep> to test
3. Release: Publish to NPM, switch consumers to pds npm <dep>

Setting up a dist branch

Add a workflow to your library that builds and pushes to a dist branch:

# .github/workflows/build-dist.yml
name: Build dist branch
on:
  workflow_dispatch:
    inputs:
      src:
        description: 'Source ref to build from'
        required: false
      dst:
        description: 'Dist branch name (default: dist)'
        required: false
jobs:
  build-dist:
    uses: runsascoded/npm-dist/.github/workflows/build-dist.yml@v1
    with:
      source_ref: ${{ inputs.src }}
      dist_branch: ${{ inputs.dst }}

See npm-dist for more options.

Requirements

• gh CLI for GitHub ref resolution
• glab CLI for GitLab ref resolution

Self-hosting

pds can manage itself! Clone the repo and use the global (-g) commands to switch between local development, dist branch testing, and NPM releases:

# Clone and initialize
git clone https://github.com/runsascoded/pnpm-dep-source.git
cd pnpm-dep-source
pnpm install && pnpm build

# Register pds as its own global dependency
pds init . -g

# Develop locally
pds l -g    # installs from local ./dist

# Test dist branch
pds gh -g   # installs from GitHub dist branch

# Use NPM release
pds n -g    # installs from NPM

License

MIT