DEV Community


Working with Local NPM Packages

aideslucas profile image aideslucas ・3 min read

If you work on packages you must know the frustration of how to test it locally without publishing the changes to your repository.

There are a few possible options, but all have some cons, that is why I created the local-package-cli project.

  • The "NPM" way of doing testing would be Symbolic Linking: you can run npm link on the package under test, and in the repo you want to test it you could run npm link [package-name] this will link them together and the changes made on the package will affect the testing repo. when you are done you need to unlink them first in the testing repo npm unlink --no-save [package-name] then in the package npm unlink.
    I find this process a lot overwhelming, lots of commands to run, you must run them in the correct order, etc…

  • Publishing the package to a Local NPM Repository and install it from there: there are a few local npm repositories you could work with publish the package there and install in the testing repo the package from the local npm repository, to do so you would need to change your npm repository running npm set registry http://localhost:[port] then when you are done remember to set the registry back.
    Changing the registry each time you need to test your packages is a bit much, also it wont save you the process of running npm publish and installing it in the testing repo

  • Changing the package.json to be a file link:
    you could change your testing repo's package.json to look something like this

// package.json
  "dependencies": {
    "my-package": "file:../packages/my-package",
Enter fullscreen mode Exit fullscreen mode

this would work great but you would need to remember to change the package.json back and not accidentally commit those changes.

  • Manual process:

A. you could run npm pack on the package, and install the tgz file on the testing repo (with npm install) - this will change the package.json and you'll need to remember to revert it.

B. you could run npm pack on the package extract the tgz and copy its content to the node_modules folder of the testing repo.


I found that the manual process has the least cons, but as it is a manual process it takes time to do some simple tasks. this is why I created the local-package-cli.

you would need to install it globally npm install --global local-package-cli when installed it gives you a cli command pkg-cli with 2 major arguments install and copy that automize the manual processes from above

A. pkg-cli install [package-name] will install the package requested from your local workspace to the current repo (without changing your package.json)

B. pkg-cli copy will pack and copy the tgz content of the current repo (the package) to all your local repo's that require the package.

before you can start to work with the pkg-cli you will need to init it giving the init command the path to your root workspace folder, this is the folder that the pkg-cli will recursively check for the packages and repos the need it.

pkg-cli init ~/Workspace

There are a few more options you can pass with the init command, such as buildScript or compileScript but you can also set those up later

for more info check out the readme of the package

Discussion (0)

Editor guide