Use npm pack to test your packages locally

When working with npm packages you often want to test your package without having to publish it to npm. This enables you to have a quicker feedback loop and keeps the number of published versions to a minimum.

This is where npm pack comes in.

First: Build your Package

Before you can use npm pack you must first build your package. So run your build command and check that this has completed successfully. In my use case, for @ag-grid-community/angular the command is:

community-modules/angular$ npm run build

Second: Locate your Build Artifacts package.json

The important part of this step is to run npm pack in the correct folder location where the build artifact package.json is located. Depending on your project that may be the same folder as where you ran your build. For me though, with this Angular library that means navigating into the dist/ag-grid-angular folder as that is where the Angular library builds to.

community-modules/angular$ cd ./dist/ag-grid-angular

Third: Pack your artifacts

Now it is time to package our build artifacts to enable us to produce a package that mimic what would be published to npm. We tell npm to pack it to our user folder ~ for ease.

community-modules/angular/dist/ag-grid-angular$ npm pack --pack-destination ~

After this runs you will have the following file.

~/ag-grid-community-angular-27.0.0.tgz

Fourth: Point package.json to your file

Now that we have this package we can test it in our application. To do this we update our package.json to point to the file that we produced in the previous step.

"dependencies": {
  "@ag-grid-community/angular": "file:~/ag-grid-community-angular-27.0.0.tgz"
}

Then make sure you remember to re-install your packages after this update.

npm install

Fifth: Test your package in your application

Now you can run your application using your packed dependency.
This enables you to test your package without having to publish it to npm for all the world to see.

Not only does this save us time by giving us a quicker feedback loop but it keeps our published packaged versions clean. This approach also gives us more confidence that our library is working as expected when installed into an application. We are more closely mimicking our users as opposed to testing against the raw source files.

Happy testing!

---

Stephen Cooper - Senior Developer at AG Grid
Follow me on Twitter @ScooperDev or Tweet about this post.

Comments

[Abbas Cyclewala]

Great article! Just adding some more points which might be helpful.

You don't need to pack your library to test it.
Just point the package.json dependency to actual library folder instead of the packed version and do npm i once.
npm creates a link to actual folder inside node_modules

Saves you additional steps of packaging and installing it after every change in your test project

[Stephen Cooper]

Thanks for highlighting this use case. I have done this in the past but seemed to run into issues with the linking. Maybe I should give it another go though as does save a few steps.

However, I still like the additional confidence of working off the same item that will actually end up in npm.

[Andreas Riedmüller]

I didn't know about this method, I always use npm link.
For developing this is very handy as it is also possible to get autorefresh/hmr

For testing a package before publishing using npm pack seems like a much better alternative because npm link does not care about the files property. All files in the project are included as it is just a symlink.

And I just found out that this should work as well:

npm install https://github.com/username/repo.git

Thanks for sharing!

[Daniel Li]

npm link uses symbolic links to link to raw source files as opposed to what the end-users will see, which is usually the build artifacts and maybe a subset of the source files copied over. Using npm link does not ensure you've packaged your package correctly.

[Abhishek Kumar]

How to do this. Can you explain with code. Please.

[Stephen Cooper]

The official docs have some examples of this with an explanation of what it does.

docs.npmjs.com/cli/v8/commands/npm...

[Andreas Riedmüller]

I tried to summarize the important points in an article of mine, you can find it here: dev.to/receter/the-minimal-setup-t...

[Sarvesh Prajapati]

great article man

[Stephen Cooper]

Thanks! I have come back to the draft a few times to remind myself so how to do it so thought I should share it.

[Sarvesh Prajapati]

absolutely

[Adam Patterson]

With PHP Composer I can keep my code and dependance linked to Packagist and just replace the folder with a SimLink locally while I develop my code.

With NPM this won't work. I have to use "file:../_packages/my-package-name" as you mentioned but now my CI build is broken...

I must be doing something wrong or this seems like a really big inconvenience.

[Lara Raoof]

God bless u!
I should delete my node_module and package_lock.json to see the changes!
when I test it again

[Lara Raoof]

Also Do you have any idea about this question?
Thanks in advance

[ramstheroyalp]

@scooperdev Thanks for the blog...
Btw, do we need to provide a relative path here?

"@ag-grid-community/angular": "file:~/ag-grid-community-angular-27.0.0.tgz"

What if the calling application is a different project altogether? How too reference this file?
May be copying it to the project and keep it at the package.json level and call?