lpm

Link local npm packages into a consumer project without global registration or global state. LPM copies publishable files and configures package-manager overrides. It can also watch and install changes automatically, stash links temporarily, and commit source versions into the consumer manifest.

Install

npm install --global @tarik02/lpm
# or
nix profile install github:tarik02-org/lpm

Use

Run LPM from the consumer project:

lpm link ../ui-kit /work/shared/logger
lpm dev

link accepts package-root paths containing package.json. dev watches and copies changes; start source build commands yourself.

Manifest normalization is enabled by default. Use --verbatim to copy package.json unchanged:

lpm link ../ui-kit --verbatim

Supported package managers: npm, pnpm, Yarn, Bun, and Aube.

Run lpm <command> --help for command details.

Ignore local files

LPM writes to .local/lpm by default. Keep .local out of Git using one of:

• Add .local/ to ${XDG_CONFIG_HOME:-$HOME/.config}/git/ignore to ignore it globally (core.excludesFile).
• Add /.local/ to the project's .gitignore.
• Add /.local/ to .git/info/exclude for the current checkout only.

If you configure another LPM directory, ignore that path instead.

CLI cheatsheet

| Command | Action | | ---------------------------- | ------------------------------------------------------- | | lpm link <path>... | Link package roots and run install | | lpm link <path> --verbatim | Link without normalizing the materialized manifest | | lpm dev [package...] | Watch and copy all links or selected packages | | lpm stash | Use exact source versions from the registry temporarily | | lpm unstash | Restore all local links | | lpm commit | Write source versions to dependencies and remove links | | lpm unlink [package...] | Select links interactively or unlink named packages | | lpm unlink --all | Unlink every package | | lpm status | Show link mode, package manager, paths, and health | | lpm doctor | Report missing paths and package-manager configuration | | lpm doctor --fix | Rebuild materializations, repair configuration, install |

While stashed, link, unlink, dev, and commit ask before discarding the stash. Pass --force in noninteractive use.

Configuration

The optional global config is ${XDG_CONFIG_HOME:-$HOME/.config}/lpm/config.json:

{
  "directory": ".cache/lpm"
}

directory defaults to .local/lpm and must stay inside the consumer root. Add it to the consumer's ignore rules. To change it after linking, unlink first and relink afterward.

Troubleshooting

lpm status
lpm doctor
lpm doctor --fix

If an install fails, fix the reported problem and rerun the command or use doctor --fix. If a source moves, link its new path.

Design

• Project language
• Core linking design
• Architecture decisions
• AI use