Common NPM Mistakes Every Developer Should Avoid

Learn how to avoid common mistakes when managing dependencies, publishing packages, and more.

NPM is the world’s largest package manager, and using it in practice is relatively straightforward. However, when adding custom configurations or using its advanced features, many things could go wrong.

So, in this article, I will discuss seven common mistakes you should avoid when using NPM.

1. Manually adding dependencies to package.json

You should avoid updating the package.json manually since it could break the synchronization between package.json and package-lock.json.

Instead, you can use CLI commands like npm i --save and npm i --save-dev to update package.json and package-lock.json automatically. This will also alert you if there are any version mismatches in those 2 files.

However, using CLI commands doesn’t always guarantee a smooth dependency upgrade process.

For example, if you execute npm i --save package@~1.0.0, you could expect an @version pattern to be mirrored in the package. But Instead, we can use the ^ symbol to save the version with provisions upgrade in package.json.

So, always double-check your package.json after updating dependencies.

2. Locking your peer dependencies to a specific patch version

Usually, the peerDependencies are used to avoid duplicate installations of the package dependencies. And, it will be annoying if we lock the peer dependencies to a specific patch version. So, let’s take a simple example to understand the fundamental reason behind this issue.

{
  "name": "tea-latte",
  "peerDependencies": {
    "tea": "1.x"
  }
}

According to the above code, the tea-latte module depends on a specific version (e.g.: 1.x) of the tea package.

But, there can be other packages or modules in your project that depend on the latest version of the tea package. Therefore, locking the tea package for an older version can cause unexpected behaviors in your application.

Note: If peer dependencies are not explicitly dependent upon higher versions in the dependency tree, NPM versions 1, 2, and 7 will install them automatically. Versions 3,4,5 and 6 will give you a warning message.

3. Publishing multiple modules as a single package

An independently source-controlled and shared “card” component. On the right => its dependency graph, auto-generated by Bit.

Whether it is a UI library, a utility “toolbox”, or any other group of modules, it is almost always a bad idea to publish them all as a single package.

There’s no reason why we should force consumers of our code to couple their project to an entire set of modules or components when all they need is a sub-part of it. They should choose what to use and which version of it, and they should never have to deal with meaningless updates.

Most chances are that you agree with me but dread the thought of managing a monorepo to maintain all these packages. To that I say, fear not!

The JS ecosystem has come a long way since the days of the monorep-polyrepo dichotomy.

We are now fortunate to be able to source-control and publish independent components from simple CRA-like projects, with auto-generated package.json , documentation, and more.

To learn more about using Bit to publish multiple packages, see here:

Publish Multiple Components to NPM with no package.jsons to Maintain

4. Publishing sensitive data by accident

If you publish a module that contains sensitive information by accident, the first thing you might do is unpublishing the package.

But, once a module is published, it gets copied to all registry mirrors. Unpublishing it won’t make a difference.

Whitelists are a handy technique to secure what you publish in the registry and avoid accidentally releasing sensitive data.

All you need to do is modify the package.json with a property namedfiles. with files property, you can easily specify files or directories you need to publish.

{
 “name”: “my-package”,
 “version”: “1.0.0”,
 “description”: “my-package”,
 “scripts”: {
 “test”: “echo \”Error: no test specified\” && exit 1"
 },
 “files”: [
 “dist/”
 ],
 “keywords”: [],
 “author”: “bhagya-withana”
}

So I recommend using whitelists to control which files are included in your next package.

5. Providing a regular authentication token

If you use private modules in a CI/CD pipeline, you need to provide an authentication token. However, NPM CLI doesn’t allow to control read and write access when generating these tokens.

You manually generate a token using the public registry API and avoid any security vulnerability caused by tokens.

The below command will generate a token with read-only access for you.

curl -u [USERNAME]:[PASSWORD] https://registry.npmjs.org/-/npm/v1/tokens \
-X POST -H 'content-type: application/json' \
-d '{"password":"[USERNAME]", "readonly": "true"}'

Also, you can review, add, and delete the tokens you have created using the NPM website.

Token option under your profile

6. Upgrading for the sake of upgrading

Maintaining the latest versions is a good practice. However, you should not upgrade your packages just because there is a new version. Let’s find out why.

There are few reasons for that,

• There can be bugs in the latest versions.
• Version upgrades without proper study can cause unexpected behaviors in your application.
• New features might not be useful for your project.
• Need to consider the dependencies between other packages.

So, you need to evaluate the changes and compatibility of the new upgrade before updating your project’s library dependencies.

7. Deleting package-lock.json

Deleting package-lock.json file to resolve NPM issues has become a common practice among developers.

However, we should avoid this since the package-lock.json file keeps track of the exact version of every package installed. For example, if you run npm update, upgraded versions of the dependencies will be reflected in the package-lock.json file.

So, instead of deleting package-lock.json file, you can try the below options.

• Solve the package.json conflicts.
• Take out package-lock.json from the main branch.
• Run npm install again.

Final Thoughts

NPM is an essential part of any JavaScript-based project, and it helps developers install and manage packages efficiently.

But, we make many mistakes when using NPM, and some of them can cause serious issues. And, in this article, I discussed 7 such mistakes we make and best practices to avoid them.

So, I hope you will use them in your project from here onwards, and if you have any suggestions, please share them in the comments section.

Thank you for Reading !!!

Learn More

NPM Tips and Tricks

Publish Multiple Components to NPM with no package.jsons to Maintain

Will Bit Replace npm?