npm-link

Symlink the current package globally

$ npm link

$ npm link [package_name]

$ npm unlink [package_name]

npm link [<package-spec> | <package-folder>]

[no arguments]
    When run inside a package's root directory, this command creates a global symbolic link pointing to that package. This makes the package globally available to be linked into other projects.

<package-name>
    When run inside a consuming project's root directory, this command creates a local symbolic link within its node_modules folder, pointing to the globally-linked package specified by <package-name>.

<package-folder>
    When run inside a consuming project's root directory, this command creates a local symbolic link within its node_modules folder, directly pointing to the specified local <package-folder> without requiring global registration.

The npm link command is a powerful utility within the npm ecosystem designed to facilitate local development and testing of npm packages. It establishes a symbiotic relationship between a local package and other projects that depend on it, without the need for publishing the package to a registry. Essentially, it uses symbolic links (symlinks) to connect a package's source directory directly into a project's node_modules folder.

This mechanism is particularly useful for developers working on multiple interdependent modules. Instead of constantly reinstalling a local package after every change, npm link allows for instantaneous updates. When changes are made in the linked package, they are immediately reflected in the consuming project, significantly streamlining the development workflow.

npm link operates in two primary modes: first, by globally registering a package (run npm link in the package's root directory), and second, by linking that globally registered package into a consuming project (run npm link <package-name> in the project's root). It can also directly link a local folder using npm link <path-to-folder>. The inverse operation, npm unlink, removes these symbolic links.

Creating symbolic links, especially on Windows, may require elevated administrator privileges or enabling Developer Mode.

While excellent for development, npm link is not intended for production deployments. It can sometimes lead to issues with conflicting dependency versions if the linked package and the consuming project have different versions of shared dependencies, or with peer dependency resolution.

Always use npm unlink to clean up the symlinks when done, otherwise, your global node_modules or local node_modules might point to non-existent or outdated paths.

When you run npm link in a package, npm creates a symlink in a global location (typically /usr/local/lib/node_modules/<package-name> on Unix-like systems, or %AppData%\npm\node_modules\<package-name> on Windows). When you run npm link <package-name> in another project, npm creates a symlink from that project's node_modules/<package-name> to the global symlink, which then points to your original package source. This dual-symlink approach ensures a consistent linking process.

On Windows, creating symbolic links is a privileged operation. If you encounter permissions errors, ensure you are running your terminal as an administrator, or enable Developer Mode in Windows settings. Alternatively, some setups might use directory junctions for folders, which have slightly different permissions requirements.

The npm link command has been a fundamental feature of the Node.js package manager since its early days. It emerged as an essential tool to address the common challenge of developing and testing multiple interconnected npm packages locally. As the modularization trend in JavaScript and Node.js ecosystems grew, the need for an efficient way to iterate on dependent packages without publishing them for every minor change became paramount, solidifying npm link's role as a core development utility.

npm unlink(1), npm install(1), ln(1)