Open any serious JavaScript project: at its root sits a package.json file. It answers the questions every tool asks before doing anything at all.
What is this project called, what does it depend on, which commands can it run, are its .js files modules? All of it fits into a single JSON object.
Definition
package.json is the description file of a JavaScript project. npm uses it to install dependencies and run scripts, Node.js to decide how to interpret files, and build tools to find the entry point of a package.
{
"name": "shop",
"version": "1.4.0",
"type": "module",
"scripts": {
"dev": "vite",
"build": "vite build",
"lint": "eslint ."
},
"dependencies": {
"zod": "^3.23.8"
},
"devDependencies": {
"eslint": "^9.9.0",
"vite": "^5.4.0"
}
}The file follows strict JSON syntax: double quotes required, no comments, no trailing comma. One comma too many and every command in the project stops working.
The fields that actually matter
- name and version: the identity of the package. Required to publish, optional for a private application, which then sets
"private": true. - type:
"module"makes.jsfiles read as ES module, and its absence treats them as CommonJS. - scripts: command shortcuts, launched through
npm run. - dependencies: what the application needs to run once it is live.
- devDependencies: what only serves the build, such as Vite or ESLint.
- engines: the Node version expected, handy for avoiding a nasty surprise at deployment.
Reading a version and its prefix
A version reads as three numbers, major, minor and patch, and the sign in front of it decides how much newer an install is allowed to go.
| Notation | What it allows |
|---|---|
3.23.8 | That exact version, nothing else |
~3.23.8 | Patches only, up to 3.23.x |
^3.23.8 | Patches and additions, up to 3.x.x |
* | Anything at all, best avoided in a real project |
The companion package-lock.json file records the exact version actually installed, dependencies of dependencies included. It is what guarantees two machines end up with identical code: commit it, never delete it.
Frequently asked questions
Should package.json go into the code repository?
Yes, along with the lock file, always. The node_modules folder, on the other hand, stays out of it: one command rebuilds it from those two files, and it often weighs more than the entire project.
What separates dependencies from devDependencies?
The first group ships to production with the application, the second stays on the build machine. The distinction matters most for a published package, whose users pull in its dependencies: slipping a test tool in there makes their installs heavier for no reason.
Can I write a comment in it?
No, JSON does not allow it. The common workaround is an extra key, such as "//" or a custom field tools ignore, to leave a note for the team. A longer explanation belongs in the project README anyway.