Packages and package.json

Last lesson ended with a bare specifier - import { format } from "date-fns" - and a promise to explain where that comes from. This is that lesson. A package is a folder of code with a file called package.json at its root describing what the folder is: its name, its version, and which file to start from. That description is what turns a directory into something another project can depend on.

Your own project is a package too, even if you never publish it. The same file that lets a library say "I am date-fns version 4.1.0, start at src/index.js" lets your app say "I am kettle-timer, I depend on these four things, and here are the commands for building and testing me".

npm is the registry those packages are published to and the command-line tool that fetches them. When you run npm install, it reads the dependency list in your package.json, downloads each package and everything those packages themselves depend on, and puts the whole lot in a folder called node_modules.

name and version. The npm documentation calls these the most important fields, and they are required if you plan to publish: together they identify a specific release of a specific package. Next lesson is about the version number's grammar.

main, and the more modern exports. main names the file someone gets when they import your package by its bare name. Node's own documentation describes exports as the modern alternative: it can declare several entry points, vary them by environment, and - the part that matters - prevent importing any file you did not list. Where both are present, exports wins.

type. This is the switch that decides how Node reads your .js files. With "type": "module" they are ES modules, the import/export syntax of the last two lessons. Without it, or with "type": "commonjs", they are CommonJS and use require instead. The extensions .mjs and .cjs override the switch file by file. If you have ever hit "Cannot use import statement outside a module", this field is where the answer lives.

scripts. A named list of commands the project knows how to run - test, build, lint, dev. Lesson six is about why this small object is the most useful thing in the file.

dependencies and devDependencies. Two lists, and the split is the subject of the next section.

dependencies are the packages your code needs in order to RUN. If you deleted one, the shipped product would break. devDependencies are the ones you need in order to WORK: the test runner, the formatter, the type checker, the bundler. Delete one of those and your product still runs perfectly; you just cannot test or build it comfortably.

The distinction is not bookkeeping. Anyone who installs your package gets your dependencies, because they need them; they do not get your devDependencies, because your test runner is your business. Get the split wrong in one direction and every consumer of your library downloads a testing framework they will never run. Get it wrong in the other and your app is missing something it needs the moment it starts.

There is a security dimension too, and it is worth naming early because it becomes real fast. Every dependency is code you did not write, running with the same permissions as code you did write, and each one brings its own dependencies. A short dependency list is not just faster to install; it is a smaller surface for somebody else's mistake. Reading a package's own package.json before adding it is a five-second habit that pays for itself.

Follow the chain once and bare specifiers stop being mysterious. You write import { format } from "date-fns". The name has no dot and no slash at the front, so it is a bare specifier: not a file in your project. The runtime or bundler looks for a folder called date-fns inside node_modules, reads that folder's own package.json, and uses its exports or main field to decide which file inside it to load. That file is a module like any other, and it has its own imports, which get resolved the same way, all the way down.

Two consequences follow immediately. First, node_modules is generated, not authored: it is the result of npm reading your dependency list, which is why editing a file in there is pointless - the next install throws your change away - and why it is always in .gitignore. It can hold tens of thousands of files, and nothing in it is yours.

Second, if the package is not in node_modules, the import fails, and the error will say the module cannot be found rather than anything about npm. "Module not found" almost always means one of: you have not run npm install, you installed it somewhere else, or you spelled the package name differently from the way its author did.

Treating package.json as if it were JavaScript. It is JSON: every key is quoted with double quotes, there are no comments, no trailing commas, and no expressions. A single trailing comma stops every npm command with a parse error. If you want to explain a choice, the README is the place.

Committing node_modules. It is enormous, it is machine-specific, and it is fully reproducible from package.json plus the lockfile of the next lesson. The correct thing to commit is the two small files that describe it.

Editing a file inside node_modules to fix a bug. It works until the next install, then vanishes without trace - and it works for you and nobody else. The honest routes are to report the bug upstream, or to pin the working version.

Installing without looking. npm install <name> writes to package.json and downloads that package's whole dependency tree. It is worth ten seconds on the package's page first: when it was last published, how many dependencies it drags in, and whether the thing you want is three lines you could write yourself.

A package is a folder described by a package.json. name and version identify it; main or exports says where an importer enters it; type decides whether its .js files are ES modules or CommonJS; scripts names its commands; dependencies and devDependencies list what it needs to run and what you need to work on it. A bare specifier is resolved by finding the package in node_modules and reading its own package.json. node_modules is generated from your dependency list, so it is never edited and never committed.