Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

A package linked with npm link still gives Cannot find module

ErrorError: Cannot find module 'my-lib'

Short answer

npm link works in two steps. The first, run inside the library, creates a link in the global folder. The second, run inside the app, links that global entry into the app's node_modules. A module is missing when one step was skipped, the name differs from package.json, or the two steps used different global prefixes.

  • Applies to Node.js 22, Node.js 24, npm 10
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look at what the app has in node_modules and where npm thinks the global folder is. A real link shows up as a symlink.

    ls -l node_modules | grep my-lib
    npm prefix -g
  2. 2Match what you see, then jump to its fix

    1. 1ls shows no my-lib entry in node_modules, although npm link in the library succeeded.The second step was never run in the appFix
    2. 2The library folder is called one thing, its package.json name another, and npm link my-folder-name finds nothing.The link name does not match the name in package.jsonFix
    3. 3The library was linked under one Node.js version (or one nvm shell) and the app runs under another.The two steps used different global prefixesFix

What does the error look like?

  • Error: Cannot find module 'my-lib'
  • code: 'MODULE_NOT_FOUND'

Cause 1 of 3

The second step was never run in the app

1Check

Running npm link with no arguments in the library only creates the global link. The npm docs say the app has to run npm link package-name to get a symlink in its own node_modules.

ls -l $(npm prefix -g)/lib/node_modules

2Fix

Run the second step inside the app folder.

cd ../my-lib && npm link
cd ../my-app && npm link my-lib

3Verify

The app now has a symlink to the library folder.

ls -l node_modules | grep my-lib

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 3

The link name does not match the name in package.json

1Check

The docs say the name used by npm link package-name is taken from package.json, not from the directory name. Scoped packages need the scope in the name.

node -p "require('./package.json').name"

2Fix

Link and require using the name printed by that command. The one-step form npm link ../my-lib takes the folder path instead.

cd ../my-app
npm link @myorg/my-lib
# or, by folder path
npm link ../my-lib

3Verify

The require call and the link now use the same name.

node -e "require('@myorg/my-lib'); console.log('found')"

Confirmed by docs.npmjs.com

Did this fix it?

Cause 3 of 3

The two steps used different global prefixes

1Check

npm link uses the global prefix, and the prefix defaults to the folder where the node executable lives. A different Node.js install therefore has its own global folder.

node -v
npm prefix -g

2Fix

Use one Node.js version for both steps. Switch to the version you linked with, or run npm link again in the library under the version the app uses.

# after switching to the Node.js version the app uses
cd ../my-lib && npm link
cd ../my-app && npm link my-lib

3Verify

The global folder of the active Node.js contains the library.

ls -l $(npm prefix -g)/lib/node_modules

Confirmed by docs.npmjs.com

Did this fix it?

How do I stop it coming back?

  • Write the two-step command pair into the library's README, so nobody stops after the first one.
  • Use npm link ../my-lib in one command when the folders sit side by side.
  • Remember that linked dependencies are not saved to package.json by default; add --save only when everyone shares the same folder layout.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.