If you’ve been working with Node.js for a while, you know that package.json is the heart of your project. It keeps track of dependencies, scripts, metadata, and more. But despite its importance, developers often make mistakes that can lead to broken builds, security issues, or just plain confusion.
Let’s go over seven common mistakes in package.json configuration—and how to avoid them.
1. Forgetting to Set private: true
If you’re working on a private project that should never be published to npm, but you forget to set "private": true, you risk accidentally publishing it with npm publish.
The Problem:
{
"name": "my-internal-project",
"version": "1.0.0"
}
If someone (or even you) runs npm publish, your internal project goes public.Â
The Fix:
Add "private": true to prevent accidental publication:
{
"name": "my-internal-project",
"version": "1.0.0",
"private": true
}
Now, npm publish will throw an error if you try to publish this package.
2. Incorrect main Entry Point
The main field tells Node.js which file to load when your package is imported. If it’s misconfigured, tools like Webpack or Node.js might not find your package.
The Problem:
{
"main": "index.js"
}
But what if your main file is actually inside a src folder?
The Fix:
Make sure main points to the correct entry file:
{
"main": "src/index.js"
}
If you’re using ESM (ES Modules), also define the module field:
{
"main": "src/index.js",
"module": "src/index.mjs"
}
This ensures compatibility with both CommonJS and ES Modules.
3. Using dependencies Instead of devDependencies
Many developers accidentally install development tools (like linters or testing frameworks) as production dependencies.
The Problem:
{
"dependencies": {
"eslint": "^8.0.0",
"mocha": "^10.0.0"
}
}
Now, your production build will include unnecessary dev tools, increasing the final package size.
The Fix:
Move tools like eslint, jest, mocha to devDependencies:
{
"devDependencies": {
"eslint": "^8.0.0",
"mocha": "^10.0.0"
}
}
Run:
npm install eslint --save-dev
or
yarn add eslint --dev
to install it properly.
4. Hardcoding Version Numbers Without Care
Using exact versions ("lodash": "4.17.21") can cause issues when updates are needed. But using wildcard versions ("lodash": "*") can introduce breaking changes.
The Problem:
{
"dependencies": {
"lodash": "*"
}
}
This will always install the latest version—even if it introduces breaking changes.
The Fix:
Use semantic versioning:
{
"dependencies": {
"lodash": "^4.17.21"
}
}
^4.17.21→ Allows patch and minor updates (safe).~4.17.21→ Allows patch updates only (extra safe).
5. Missing engines Field for Node.js Version Control
If your project requires a specific Node.js version, you should specify it. Otherwise, teammates (or CI/CD pipelines) might run it on the wrong version.
The Problem:
{
"name": "my-app"
}
This doesn’t enforce a Node.js version. If someone runs it with an outdated version, unexpected errors may occur.
The Fix:
{
"engines": {
"node": ">=16.0.0"
}
}
Now, if someone tries to install the project with an older Node.js version, they’ll get a warning.
6. Forgetting to Define scripts Properly
The scripts section is a powerful way to automate tasks. Many developers forget to define essential scripts or leave unnecessary ones.
The Problem:
{
"scripts": {
"test": "jest"
}
}
Missing important scripts like start, build, or dev can make it harder for new developers to use your project.
The Fix:
Make sure you have a well-defined scripts section:
{
"scripts": {
"start": "node src/index.js",
"dev": "nodemon src/index.js",
"build": "webpack",
"test": "jest --coverage",
"lint": "eslint . --fix"
}
}
This makes development easier and enforces best practices.
7. Not Keeping package.json Clean and Updated
Over time, package.json can accumulate unused dependencies and duplicate entries, leading to messy and slow projects.
The Problem:
- Old dependencies that are no longer needed
- Redundant entries
- Incorrect indentation or formatting
The Fix:
Run:
npm prune
to remove unused dependencies.
Use:
npm outdated
to check for outdated packages.
Format package.json properly using:
npx prettier --write package.json
A clean package.json means faster installs and better maintainability.
Final Thoughts
Your package.json might seem like just a configuration file, but small mistakes can lead to big headaches. By avoiding these seven common mistakes, you’ll keep your project secure, optimized, and easy to maintain.
You may also like:
1)Â 5 Common Mistakes in Backend Optimization
2)Â 7 Tips for Boosting Your API Performance
3)Â How to Identify Bottlenecks in Your Backend
4)Â 8 Tools for Developing Scalable Backend Solutions
5)Â 5 Key Components of a Scalable Backend System
6)Â 6 Common Mistakes in Backend Architecture Design
7)Â 7 Essential Tips for Scalable Backend Architecture
8)Â Token-Based Authentication: Choosing Between JWT and Paseto for Modern Applications
9)Â API Rate Limiting and Abuse Prevention Strategies in Node.js for High-Traffic APIs
Read more blogs from Here
Share your experiences in the comments, and let’s discuss how to tackle them!
Follow me on Linkedin
