Lesson 24 of 28
In progress
npm, package.json and scripts
Understand what npm installs, read a package.json, add scripts, and know when a project does not need any of it.
Most JavaScript jobs involve npm within the first week. The tool itself is simple: it downloads packages and runs scripts. The confusion is mostly about what belongs in a project and what is disposable.
What you will learn
- Read the important fields of
package.json. - Install a dependency and run a script.
- Decide when a project should skip npm entirely.
What npm actually does
npm has two jobs: it installs packages into node_modules, and it runs the commands listed in scripts. It does not build your app, and it does not make code faster. Those come from the packages you choose.
A project becomes an npm project when it has a package.json. Create one with:
npm init -y
That writes a minimal manifest. Edit the name, description and scripts rather than accepting the defaults forever.
The fields that matter
{
"name": "task-panel",
"version": "1.0.0",
"private": true,
"type": "module",
"scripts": {
"dev": "vite",
"build": "vite build",
"test": "node --test"
},
"dependencies": {
"date-fns": "^4.1.0"
},
"devDependencies": {
"vite": "^6.0.0"
}
}
type: "module" makes .js files ES modules in Node. private: true prevents accidentally publishing. scripts are the commands you and your team actually run; they belong in the file so nobody has to remember flags.
dependencies are needed at runtime; devDependencies are needed to build or test. A bundler belongs in dev dependencies, a date library in dependencies. Getting this wrong bloats production installs.
Version ranges use semver: ^4.1.0 allows updates that do not change the major version, ~4.1.0 allows patch updates only, and an exact 4.1.0 pins. The lockfile records what was actually installed, and it belongs in version control.
Installing and running
npm install
npm install date-fns
npm install --save-dev vitest
npm run dev
npm install with no arguments reads the manifest and lockfile. Adding a package name installs it and updates both. npm run <script> executes an entry from scripts, with node_modules/.bin on the path so local tools work without a global install.
npx <tool> runs a package’s binary without adding it to the project. It is handy for one-off generators and confusing when it downloads something unexpected; prefer a script for anything repeated.
node_modules is large and reproducible, so it is never committed. A fresh clone runs npm install and gets the same tree from the lockfile.
What a dev server gives you
A tool such as Vite serves your files over HTTP, reloads the browser when a file changes, and bundles for production. The first two are conveniences you can live without; the third matters when a project has many modules.
The catch is that the browser no longer loads exactly what you wrote. Source maps connect the running code back to your files, and the Network panel shows the transformed output. When something behaves differently in production, that transformation is the first suspect.
When to skip npm
This track’s lessons run without a build step, and so can a real site. If your project is a handful of HTML, CSS and module files:
- No install step means no supply-chain risk and nothing to update.
- The browser’s module loader is enough.
- A static host can serve the folder directly.
Reach for npm when you need a framework, TypeScript, a test runner, or many small modules that would mean many requests. Reach for it because of a concrete need, not because a tutorial opened with it.
Running npm install inside a folder without a package.json creates one implicitly and installs into a stray node_modules. Check where you are, and commit the manifest and lockfile together so a teammate’s install matches yours.
Write a package.json for a small site with a dev script that starts a static server, a test script that runs node --test, one runtime dependency and one dev dependency. Explain which is which.
Show solution
{ "name": "small-site", "version": "1.0.0", "private": true, "type": "module", "scripts": { "dev": "vite", "test": "node --test" }, "dependencies": { "date-fns": "^4.1.0" }, "devDependencies": { "vite": "^6.0.0" } } date-fns runs in the browser, so it is a runtime dependency. Vite only serves and builds during development, so it is a dev dependency and is not needed to run the finished site.
Reading scripts from inside a program
Editable. Runs in your browser.
for (const [name, command] of Object.entries(manifest.scripts)) {
console.log(`npm run ${name} -> ${command}`);
}
console.log("runtime deps:", manifest.dependencies.length);
Press Run to see the output.
Scripts are just named commands, which is why they are worth naming well: npm run dev tells a new teammate more than a paragraph of setup notes.
Recap
package.jsondeclares metadata, scripts and dependencies; the lockfile pins what was installed.npm installrestores the tree,npm runexecutes scripts, andnode_modulesis never committed.- A static site can skip npm entirely; adopt tooling for a concrete need.
Next, you will debug a real page with the browser’s developer tools instead of guessing.
What is the difference between npm and npx?
Should I commit package-lock.json?
Progress is saved in this browser only. No account, no email.