npm link: Usage & Common Errors

Symlink a local package into another project.

npm link creates a global symlink to a package, then links it into a consuming project - the classic way to develop a library against an app without publishing.

What it does

In the library directory, npm link creates a global symlink to it. In the consuming project, npm link <name> symlinks that global link into node_modules, so edits to the library are picked up immediately without reinstalling.

Common usage

# in the library:
npm link
# in the consuming app:
npm link my-lib
# undo:
npm unlink my-lib && npm install

Common CI gotcha: linked deps do not exist in CI

A build works locally but fails in CI with "Cannot find module" because it relied on an npm link symlink that only exists on your machine. CI installs from the registry or workspace, not your global links - depend on a real version or a workspace, and reserve npm link for local dev only.

# in CI, use a published version or a workspace, not a link:
npm ci

Related guides