Package Managers & npm

Beginner · 42 min

Why projects need a package manager, how package.json and lockfiles work, and how npm scripts tie a project's commands together.

Before thisVersion Control with Git

Traversy Media · 42 min

Package Managers & npm

The player loads from youtube-nocookie.com when you press play. Nothing reaches YouTube before that.

Taught by Traversy MediaReport a problem with this video
Not started
Set this lesson's status

What you'll learn

  • A package manager automates downloading, installing, and tracking the libraries a project depends on, instead of you copying files by hand.
  • package.json declares what your project depends on and which versions are acceptable; node_modules is the result of actually installing those dependencies.
  • Semantic versioning (major.minor.patch) tells you whether an update is expected to break your code, add a feature safely, or just fix a bug.
  • A lockfile pins the exact versions actually installed, so every machine and every CI run gets the identical dependency tree, not just a version that satisfies the range.
  • npm scripts let a project define its own named commands (like dev or build), so the whole team runs the same command instead of memorizing different tool invocations.

Why you can’t just download libraries by hand

Modern frontend projects almost never start from zero. You pull in a date-formatting library, a UI component kit, a testing framework, a bundler — dozens of small, focused pieces of code written by other people. In principle you could download each one’s files manually and drop them into your project. In practice this breaks down fast: those libraries have their own dependencies, which have their own dependencies, and keeping track of which version of what is compatible with which by hand is a losing game the moment a project has more than a handful of packages.

A package manager — npm, along with alternatives like Yarn and pnpm — automates this entirely. You declare what you want at a high level (“this project needs React, version 18 or compatible”), and the package manager figures out the full dependency tree, downloads everything from a central registry, and wires it up so your code can simply import it.

package.json: the project’s manifest

Every npm-managed project has a package.json file at its root. It’s the project’s identity card: name, version, scripts, and — most importantly — its dependencies and devDependencies. Dependencies are what your app needs to actually run, like a charting library your UI renders. devDependencies are tools you only need while building or testing, like a linter or a test runner — things that never ship to the end user’s browser.

This distinction matters in practice. When someone installs your project for production use, a --production flag can skip devDependencies entirely, keeping the deployed footprint smaller. Keeping dependencies correctly categorized isn’t bureaucracy — it directly affects what gets shipped.

Semantic versioning: reading the version number

Packages are versioned using semantic versioning — major.minor.patch, like 4.2.1. Each segment has a meaning: a patch bump (4.2.1 → 4.2.2) means a bug fix with no expected behavior change. A minor bump (4.2.1 → 4.3.0) means a new feature was added in a backward-compatible way — your existing code should keep working. A major bump (4.2.1 → 5.0.0) means something broke on purpose — an intentional, incompatible change.

In package.json, you’ll usually see ranges rather than exact versions: ^4.2.1 means “4.2.1 or anything compatible up to, but not including, 5.0.0” — it’ll happily take new minor and patch releases. A ~4.2.1 is more conservative, allowing only patch updates. These ranges exist because pinning every dependency to one exact version forever would mean never getting bug fixes without a manual edit — but they also mean two installs done weeks apart can legitimately resolve to different versions.

Lockfiles: making installs reproducible

That last point is exactly the problem lockfiles solve. package-lock.json (npm’s lockfile; Yarn and pnpm have their own equivalents) records the exact version of every package — and every package’s own dependencies — that was actually installed, down to the specific patch version and even a hash of its contents. When you or a teammate or a CI server runs npm install with a lockfile present, everyone gets the identical tree, regardless of what’s been published to the registry since.

Without a lockfile, “works on my machine” becomes a real and common failure mode: you installed last Tuesday, a teammate installs today, and a patch release of some deep dependency introduced a subtle bug that only shows up for them. Committing the lockfile closes that gap, which is why it should always be checked into version control alongside package.json, never gitignored.

npm scripts: a shared vocabulary for commands

The scripts section of package.json lets a project define its own named commands: "dev": "vite", "build": "vite build", "test": "vitest", "lint": "eslint .". Running npm run dev executes whatever that script maps to. This matters because the actual underlying tool invocation can be long, environment-specific, or just change over time as the project swaps tools — but the team’s vocabulary (npm run dev, npm run build) stays stable.

It also means onboarding a new teammate, or coming back to a project after months away, doesn’t require remembering the exact bundler flags — you read package.json’s scripts section and you know how to run everything the project needs. That consistency is small on any single project but becomes essential the moment you work across several.

Check yourself

  1. 01What's the difference between dependencies and devDependencies in package.json?

    dependencies are packages your app needs at runtime, in production, like a UI library; devDependencies are tools only needed while developing, like a test runner or bundler, and aren't required once the app is built and shipped.

  2. 02Why do two caret ranges like ^2.3.1 and ^2.9.0 not guarantee the same installed version?

    A caret range allows any version that doesn't change the major number, so ^2.3.1 could resolve to 2.3.1 or to 2.9.0 — the exact version depends on what's newest and compatible at install time, unless a lockfile pins it.

  3. 03Why should you commit the lockfile to version control?

    Without it, a fresh install just resolves the loosest-matching versions allowed by package.json, which can differ between your machine and a teammate's or CI's, introducing bugs that only show up on one of them. The lockfile makes installs reproducible.

  4. 04What does running npm install actually do?

    It reads package.json (and the lockfile, if present), downloads the specified packages and all of their own dependencies from the registry, and writes them into the node_modules folder so your code can import them.

Go deeper

Notes

Private to you

Esc
↑↓ navigate↵ open? shortcuts

Keyboard shortcuts

Press Esc to close

Anywhere

⌘K
Search and commands
/
Search
?
This sheet
Esc
Close

Reading a lesson

J
Next lesson
K
Previous lesson
B
Bookmark