Node.js: Code Outside the Browser / Working with npm (Node Package Manager)

Package Versioning and Updating

🔢 Understanding Semantic Versioning (SemVer)

📌 Most npm packages follow Semantic Versioning (SemVer), expressed as three numbers:

MAJOR.MINOR.PATCH

Example: 1.18.11

🔍 What Each Number Means

🔢 Position

🏷️ Name

💡 Meaning

1️⃣ First

Major

Big changes — can include breaking changes that may stop your existing code from working

2️⃣ Second

Minor

New features added — should be backward-compatible (won't break existing code)

3️⃣ Third

Patch

Bug fixes only — smallest, safest kind of update

📝 Examples of Version Changes

  • 🐞 1.18.1 → 1.18.2 → 1.18.11: These are all patch updates — just bug fixes, safe to accept.

  • ✨ 1.18.x → 1.19.x: A minor update — new features added, but your existing code should still work fine.

  • ⚠️ 1.x.x → 2.0.0: A major update — could include breaking changes (e.g., a function gets renamed, or its parameters change), meaning your existing code might stop working.

⚠️ Be cautious with major version updates — always check the package's changelog/documentation before upgrading across a major version.

⚙️ Controlling Which Updates You Accept

📄 In package.json, each dependency has a version number prefixed with a symbol that controls what future updates are acceptable:

🔖 Symbol

💡 Meaning

✅ Accepts

^ (caret)

Default in npm

Minor and patch updates (no major updates)

~ (tilde)

More restrictive

Only patch updates

(no symbol)

Exact version only

No automatic updates at all

📝 Example in package.json

"slugify": "^1.3.4"

This means: accept any version from 1.3.4 up to (but not including) 2.0.0.

🔍 Step 1: Checking for Outdated Packages

npm outdated

  • Displays a table of packages that have newer versions available than what's currently installed.

  • Shows columns like:

    • 📌 Current — the version you have installed.

    • 🎯 Wanted — the highest version allowed based on your package.json symbol (^ or ~).

    • 🚀 Latest — the absolute latest version available on npm (regardless of what you've configured to accept).

📥 Step 2: Installing a Specific Version

  • 🎯 You can install an exact version of a package using @:

npm install slugify@1.0.0

  • 📦 This installs version 1.0.0 specifically, even if a newer version exists.

  • 📊 Running npm outdated afterward will now show:

  • 📌 Current: 1.0.0

  • 🎯 Wanted: depends on your version symbol setting (e.g., 1.3.4 if using ^, or a lower patch-only version if using ~).

🔄 Example: Changing the Version Symbol

  • ✅ With ^1.0.0 → wanted version becomes 1.3.4 (accepts minor + patch updates).

  • 🛡️ With ~1.0.0 → wanted version becomes something like 1.0.2 (only patch updates accepted, since 1.3.4 is a minor version bump).

🔄 Step 3: Updating Packages

npm update slugify

  • This updates the package to the highest version allowed by the symbol in package.json.

  • Example: If set to ~1.0.0, running update might bring it to 1.0.2 (patch-only).

  • If you then change the symbol back to ^1.0.0 and run update again, it can jump further — e.g., to 1.3.4 (now allowing minor updates too).

⚠️ Even minor updates (new features, no intended breaking changes) can sometimes introduce undiscovered bugs. For maximum safety, some developers prefer sticking to ~ (patch-only updates).

🗑️ Step 4: Uninstalling (Deleting) Packages

  • ❌ To remove a package you no longer need:

npm uninstall express

✅ What This Does

  • 🗂️ Removes the package's files from the node_modules folder.

  • 📝 Removes its entry from "dependencies" (or "devDependencies") in package.json.

💡 Best practice: Whenever you stop using a package in your code, uninstall it to keep your project clean and avoid unnecessary bloat.

📁 Step 5: Understanding node_modules and Sharing Code

🚫 Never Share the node_modules Folder

  • 📂 node_modules can contain tens or even hundreds of thousands of files (since it includes not just your direct dependencies, but all of their dependencies too).

  • 🚫 Never upload this folder to GitHub, Dropbox, or anywhere else when sharing your code.

🔄 How to Restore node_modules on a New Machine

  • 💻 If you download/clone a project without its node_modules folder:

npm install

  • 📥 This command reads package.json, looks at the listed dependencies, and downloads and rebuilds the entire node_modules folder automatically.

🔒 The Role of package-lock.json

  • 📄 This file records the exact version numbers of every package installed — including all the nested dependencies of your dependencies.

  • 🎯 Example: it will specify precisely that slugify is at version 1.3.4, not just "some version starting with 1.3."

💡 Why package-lock.json Matters

  • 🤝 Ensures that every developer working on the project (or even yourself on a different computer) ends up with the exact same package versions — preventing "it works on my machine but not on yours" problems.

📤 What to Always Share

When sharing your project (via GitHub, Dropbox, etc.), always include:

  1. 📄 package.json — lists your direct dependencies and their accepted version ranges.

  2. 🔒 package-lock.json — locks in the exact versions used, for consistent reinstallation.

  • ✅ These two files are enough for anyone (including future-you) to run npm install and perfectly reconstruct the node_modules folder.

🎯 Key Takeaways

📌 Concept

💻 Command / Detail

🔢 Semantic versioning format

MAJOR.MINOR.PATCH (e.g., 1.18.11)

🐞 Patch version

Bug fixes only — safest updates

✨ Minor version

New features, no breaking changes (in theory)

⚠️ Major version

Can include breaking changes

🔼 ^ (caret, default)

Accepts minor + patch updates

🔹 ~ (tilde)

Accepts patch updates only (safer)

🔍 Check outdated packages

npm outdated

📥 Install specific version

npm install <package>@<version>

🔄 Update a package

npm update <package>

🗑️ Uninstall a package

npm uninstall <package>

📦 Restore all dependencies

npm install (reads package.json)

🚫 Never share

node_modules folder

📤 Always share

package.json and package-lock.json