How we test NPM packages before publishing with npm pack

This content originally appeared on DEV Community and was authored by Yoriiis

When working on multiple interdependent NPM packages across projects, testing a new version before publishing is essential.

At Prisma Media, we maintain several packages on our private NPM registry, used directly on our websites. While each package comes with a standalone demo, we regularly need to validate development versions in real environments.

Understanding `npm pack`

Running npm pack builds your package locally and generates a .tgz archive identical to what would be published with npm publish. The archive is created in the current directory and includes only the files defined in the files field of your package.json or filtered by .npmignore.

It's also a convenient way to verify what your package will actually ship before publishing. Inspecting the generated archive helps ensure that only the expected files are included.

Testing options

Developers have a few options to test packages locally:

Local linking: npm link works if both the package and consuming project are cloned locally
Preview or shared environments: npm link fails here. Other options include:
- Publishing a tagged version (like beta), it requires deployment to the registry
- Using npm pack, it generates the .tgz archive that would be published, without touching the registry

We chose npm pack for its simplicity and safety. It allows developers and product teams to test new versions in local or preview environments, without affecting production workflows.

Implementation

Our package pipelines follow a standard sequence: install, build, test, pack and finally deploy.

For details on our reusable GitLab CI template you can read

Scaling GitLab CI/CD with reusable templates

Yoriiis ・ Oct 15

#devops #gitlab #ci #automation

The npm pack job is manual. When a developer needs a dev version:

Navigate to the latest pipeline of the merge request
Trigger the npm-pack job
The job runs and uploads the TGZ as an artifact
Install and test locally:

Download and extract the artifact
Install the TGZ in your project:

   npm install <path_to_tgz_file>

This replaces the version from the registry with the local TGZ version. Example diff:

   - "player": "1.0.0"
   + "player": "file:player-1.1.0.tgz"

Commit the TGZ file to your branch if you plan to deploy a preview
Once committed, the CI will install the TGZ

GitLab CI template

Here is a simplified .gitlab-ci.yml template for the npm-pack job:

npm-pack:
  variables:
    PACKAGES_DIR: 'npm-pack-packages'
  image: node:22-alpine
  script:
    - mkdir $PACKAGES_DIR
    - PACKAGE_TGZ=$(npm pack)
    - mv "$PACKAGE_TGZ" $PACKAGES_DIR
  artifacts:
    paths:
      - $PACKAGES_DIR
  when: manual

This job generates the TGZ locally and stores it as an artifact. The file can then be installed for local or preview testing.

For the GitHub Actions equivalent

Discover npm-pack workflow examples on GitHub

Advantages

Developers can test packages locally without publishing
The TGZ can be versioned in the dev branch, allowing CI to install it on preview environments
Product teams can validate features before merging

⚠️ Remember: TGZ files are for development and preview only, never for production.

Key points

npm pack replaces npm link for shared or CI environments
When switching back to a registry version, always run npm uninstall <package> before reinstalling
Version TGZ files only for temporary testing; never use them in production
CI pipelines can safely produce TGZ artifacts for local or preview testing
Manual triggering keeps pipelines efficient

Conclusion

Using npm pack to test packages locally or in preview environments simplifies cross-project development. It sits between local linking and full registry publishing, giving developers and product teams a faster way to validate changes.

By integrating this workflow into CI, we can safely validate packages, maintain developer productivity and ensure quality before official publication.

The complete example is available on GitHub for you to try out! 🧑‍💻

GitHub npm-pack on GitHub

Resources

This content originally appeared on DEV Community and was authored by Yoriiis

Print Share Comment Cite Upload Translate Updates

APA

Yoriiis | Sciencx (2025-10-26T21:54:00+00:00) How we test NPM packages before publishing with npm pack. Retrieved from https://www.scien.cx/2025/10/26/how-we-test-npm-packages-before-publishing-with-npm-pack/

MLA

" » How we test NPM packages before publishing with npm pack." Yoriiis | Sciencx - Sunday October 26, 2025, https://www.scien.cx/2025/10/26/how-we-test-npm-packages-before-publishing-with-npm-pack/

HARVARD

Yoriiis | Sciencx Sunday October 26, 2025 » How we test NPM packages before publishing with npm pack., viewed ,<https://www.scien.cx/2025/10/26/how-we-test-npm-packages-before-publishing-with-npm-pack/>

VANCOUVER

Yoriiis | Sciencx - » How we test NPM packages before publishing with npm pack. [Internet]. [Accessed ]. Available from: https://www.scien.cx/2025/10/26/how-we-test-npm-packages-before-publishing-with-npm-pack/

CHICAGO

" » How we test NPM packages before publishing with npm pack." Yoriiis | Sciencx - Accessed . https://www.scien.cx/2025/10/26/how-we-test-npm-packages-before-publishing-with-npm-pack/

IEEE

" » How we test NPM packages before publishing with npm pack." Yoriiis | Sciencx [Online]. Available: https://www.scien.cx/2025/10/26/how-we-test-npm-packages-before-publishing-with-npm-pack/. [Accessed: ]

rf:citation

» How we test NPM packages before publishing with npm pack | Yoriiis | Sciencx | https://www.scien.cx/2025/10/26/how-we-test-npm-packages-before-publishing-with-npm-pack/ |

Please log in to upload a file.

There are no updates yet.
Click the Upload button above to add an update.

You must be logged in to translate posts. Please log in or register.

Understanding npm pack