Explain Codes LogoExplain Codes Logo

Installing a local module using npm?

javascript
npm-link
local-modules
package-management
Alex KataevbyAlex Kataev·Oct 23, 2024
TLDR

Use a local npm module via npm link from its root directory:

npm link

And then link it in the target project:

npm link <module-name>

Be sure your module's unique "name" in package.json helps dodge any conflicts. This resembles a global npm install of your local module, thanks to symlink magic.

For direct usage without linking, install directly from the local path:

npm install /path/to/module

This phase will tuck the module neatly into your project's node_modules, effectively ring-fencing it within your project.

Resourceful resolutions and reckless rogues

Peer dependencies: Friend or Foe?

When your local module brings along its squad of peer dependencies, npm link can get tricky, with resolution issues cropping up. The symlink may cause Node.js to look for these peers in all the wrong places, like a lost festival-goer.

For such cases, mention the local module in package.json using the file: protocol:

"dependencies": { "local-module-friend": "file:../path/to/module" }

Bypass symlink drama and rest assured that peer dependencies will be discovered in the node_modules party venue.

The simple and the dogged

Local module life in the development circus

When frequent changes in the local module reflect in your development circus ring, npm link helps maintain sanity. Still, never ignore the peer dependency elephant in the room.

When wielding the npm link sword, run npm install first in the linked package fortress (to arm its dependencies), and then in the dev project battleground to ensure consistency else suffer the blue screen of death!

npm link provides a handy global symlink, but when juggling with numerous local modules, reach out for Monorepo tools (e.g. Lerna, Yarn Workspaces) for effortless management and delicate juggling.

Why did Node resolve my module that way?!

Understanding Node.js's mysterious resolution paths when dealing with local modules can save you from shouting at the screen. Tools like npm ls help inspect dependency family trees and verify your local modules are resolving into their well-behaved selves.

Best practices and those pesky pitfalls

Version control: The guardian of source code

When using local modules, shield the symlinked node_modules in your version control fortress. Tools like .gitignore are a knight's shining armor, using them avoids pushing symlink demons to other developers' calm coding heaven.

A tale of two package managers

Venturing between npm and yarn realms can cause a turbulence as yarn manages symlinks and local file paths in its unique fashion as compared to npm. To keep the journey smooth, stick to one steadfast package manager.

CI: The watchful Overseer

As CI systems come into play, ensure the local paths or symlinks are reachable caravan stops, or replace them with relevant production packages during build process. It's the coding equivalent of swapping stunt doubles in for the action scenes.