How to Publish a Test Version of Your NPM Package

When developing an NPM package, you often need to test pre-release versions before publishing a stable release. Whether for internal development, beta testing, or experimental features, following the right approach ensures a smooth and structured deployment process.

This guide walks you through publishing a test version of your package on NPM without affecting production releases.

---

✅ Steps to Publish a Test Version on NPM

1️⃣ Log In to NPM

Before publishing, ensure you are authenticated with NPM:

npm login

This command will prompt for your NPM username, password, and email. Once authenticated, you can proceed with publishing your test package.

---

2️⃣ Update package.json

Modify your package.json file to include a test version identifier:

{
  "name": "@your-org/your-package",
  "version": "1.0.0-beta.0", // Add 'beta', 'alpha', or a unique tag
  "publishConfig": {
    "access": "public"
  }
}

Versioning Guide

• 1.0.0-alpha.1 → Early experimental release
• 1.0.0-beta.1 → Feature complete, but in testing
• 1.0.0-rc.1 → Release Candidate (near-final version)

The publishConfig.access setting ensures your package is publicly available (remove it for private packages).

---

3️⃣ Use --tag to Publish a Test Version

To publish the test version, run:

npm publish --tag beta

How This Works:

• By default, running npm install @your-org/your-package installs only the latest stable version.
• Using --tag beta ensures that your test version does not overwrite your production release.
• Developers can install the test version explicitly:

npm install @your-org/your-package@beta

This allows the team to test the beta release without affecting users installing the latest stable version.

---

4️⃣ Automate Versioning with npm version

Instead of manually updating package.json, you can automate versioning:

npm version prerelease --preid=beta

This command will automatically increment the beta version to the next pre-release (e.g., 1.0.1-beta.1).

Then, publish it with:

npm publish --tag beta

Automating versioning ensures consistent releases and prevents accidental version duplication.

---

5️⃣ Install the Test Version

Once the test version is published, developers can install it like this:

npm install @your-org/your-package@beta

For specific versions, use:

npm install @your-org/your-package@1.0.0-beta.1

This ensures that the correct version is being tested before rolling out the final release.

---

🚀 Summary of Commands

Step Command Login to NPM npm login Set a test version in package.json "version": "1.0.0-beta.0" Publish as beta npm publish --tag beta Auto-update version npm version prerelease --preid=beta Install test version npm install @your-org/your-package@beta

---

🛠 Additional Tips for Testing

1️⃣ Use a Private NPM Registry

If you don’t want to publish your test versions publicly, consider using Verdaccio (a lightweight private NPM registry):

npm set registry http://localhost:4873/

This allows internal teams to test packages before publishing to the public NPM registry.

2️⃣ Publish to GitHub Packages (For Private Testing)

If your team is using GitHub Packages, update package.json like this:

"publishConfig": {
  "registry": "https://npm.pkg.github.com/"
}

Then publish using:

npm publish

3️⃣ Automate Publishing in CI/CD

Using GitHub Actions or Jenkins, you can automate NPM publishing by adding a workflow like this:

- name: Publish Test Version
  run: |
    npm version prerelease --preid=beta
    npm publish --tag beta

This ensures that new test versions are automatically published for internal teams to validate before release.

---

🎯 Final Thoughts

Publishing test versions of your NPM package allows your team to test, iterate, and validate updates before pushing them to production. By using scoped versions (beta, alpha, rc), you prevent breaking changes from affecting live users while ensuring a smooth development cycle.

Following these best practices will help your team maintain a robust, error-free, and well-managed package release process. 🚀

---

Have questions about publishing NPM packages? Let me know in the comments!