npm and package.json Explained — A Beginner's Complete Guide

Every professional JavaScript project you'll ever work on uses npm. It powers over 2 million packages and is downloaded billions of times every week. When you land a junior dev role and someone says 'just run npm install', you need to know exactly what's happening under the hood — not just how to type the command.

Before npm existed, sharing code between projects was painful. You'd copy-paste files manually, lose track of versions, and when a bug fix came out you'd have no way of knowing. npm solves all of that by giving every project a single source of truth: the package.json file. It tracks what external code your project depends on, what version of it you need, and even how to run your app.

By the end of this article you'll be able to create a project from scratch, install packages, understand every key field in package.json, and explain the difference between a dependency and a devDependency — the question that trips up a surprising number of candidates in junior dev interviews.

What npm Actually Is and Why It Was Built

npm stands for Node Package Manager. It ships automatically when you install Node.js, so if Node is on your machine, npm is already there.

The core job of npm is simple: let developers share and reuse code. That reusable chunk of code is called a 'package'. A package could be anything — a tool to format dates, a full web framework, a utility to send emails. Instead of writing all of that yourself, you pull in someone else's tested, maintained package.

npm has three parts that work together. First, there's the registry — a huge online database at registry.npmjs.org where packages live. Second, there's the CLI (command-line interface) — the npm commands you type in your terminal. Third, there's the website (npmjs.com) where you can search for and read about packages.

Think of the registry as the supermarket's warehouse, the CLI as your shopping trolley, and npmjs.com as the store's website where you browse before you go. You don't need to think about all three at once — most of the time you're just typing commands in the terminal and npm handles the rest.

# First, verify that Node.js is installed on your machine
# This prints the version of Node you have
node --version

# Now verify npm is installed — it comes bundled with Node
# This prints your npm version
npm --version

# If you see version numbers printed, you're good to go.
# If you see 'command not found', visit nodejs.org and install Node first.

Creating Your First package.json — The Project's Identity Card

Every npm project needs a package.json file sitting at its root. This file is the heart of your project. It records your project's name, version, which packages it depends on, and useful scripts for running or testing your app. Without it, npm has no idea what your project needs.

You create it by running 'npm init' inside your project folder. npm will ask you a series of questions — project name, version, description, entry point, and so on. If you just want sensible defaults and don't want to answer every question, use 'npm init -y' (the -y flag means 'yes to everything').

The resulting file is plain JSON — just text. You can open it in any code editor and edit it by hand. That's one of the things beginners find surprising: it's not magic, it's just a config file you can read and change.

Every field in package.json has a specific meaning. The two most important are 'name' (what your package is called, lowercase, no spaces) and 'version' (which follows a three-number system called Semantic Versioning, or semver, like 1.0.0). We'll look at what those numbers mean in a moment.

# Step 1: Create a new folder for your project
mkdir my-first-node-project

# Step 2: Move into that folder
cd my-first-node-project

# Step 3: Create a package.json with all default values
# The -y flag skips the questionnaire and accepts all defaults
npm init -y

# Step 4: Look at what was created
cat package.json

Installing Packages — Dependencies vs devDependencies

Now for the fun part: pulling in other people's code. When you run 'npm install ', npm downloads that package into a folder called node_modules and automatically records it in your package.json under a field called 'dependencies'.

But not all packages are equal. Some packages your app needs to actually run in production — like express (a web server) or axios (for making HTTP requests). These go in 'dependencies'. Other packages are only needed while you're developing — like jest (a testing tool) or eslint (a code quality checker). Your end users will never need these. These go in 'devDependencies'.

To install a production dependency: 'npm install axios' To install a dev-only dependency: 'npm install jest --save-dev'

The '--save-dev' flag is the difference. Get this right and your production deployments only install what they actually need, which makes them faster and leaner.

Semantic versioning controls which version gets installed. The version number '1.4.2' means: major version 1, minor version 4, patch 2. A caret symbol (^1.4.2) means 'install 1.4.2 or any compatible minor/patch update'. A tilde (~1.4.2) means 'install 1.4.2 or any patch update only'. Most of the time you'll see the caret and that's fine for beginners.

// First, in your terminal run:
// npm install axios
// npm install chalk --save-dev

// Now let's use axios — a package for making HTTP requests
// This is a PRODUCTION dependency (your app needs it to run)
const axios = require('axios');

// Fetch a public post from a free test API
async function fetchBlogPost(postId) {
  try {
    // axios.get sends an HTTP GET request to the URL
    const response = await axios.get(
      `https://jsonplaceholder.typicode.com/posts/${postId}`
    );

    // response.data contains the actual JSON returned by the API
    const post = response.data;

    console.log('Post Title:', post.title);
    console.log('Post Body:', post.body);
  } catch (error) {
    // If the request fails, catch and print the error
    console.error('Failed to fetch post:', error.message);
  }
}

// Fetch the first blog post
fetchBlogPost(1);

npm Scripts — Your Project's Command Centre

The 'scripts' field in package.json is one of the most underappreciated features for beginners. It lets you define shortcut commands for your project that anyone on the team can run without knowing the underlying tool or its exact flags.

For example, instead of everyone having to remember 'node --watch src/index.js', you define a 'start' script once and everyone just types 'npm start'. Instead of 'jest --coverage --verbose', you write a 'test' script.

There are two special script names: 'start' and 'test'. These run with 'npm start' and 'npm test'. Any other custom script name you invent runs with 'npm run ' — note the extra 'run' keyword.

Scripts can also chain commands together using '&&' (run second command only if first succeeds) or '&' (run both simultaneously). This is how teams build, lint, and test their code in one command. It's also how CI/CD pipelines (automated deployment tools) know how to build your project on a server.

Think of scripts as the user manual for your project. A new developer clones your repo, reads the scripts section, and immediately knows how to start, test, build, and deploy the app — without asking you.

{
  "name": "my-first-node-project",
  "version": "1.0.0",
  "description": "A demo project to learn npm and package.json",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",

    "dev": "node --watch index.js",

    "test": "jest --coverage",

    "lint": "eslint src/**/*.js",

    "build:and:lint": "npm run lint && node index.js"
  },
  "dependencies": {
    "axios": "^1.6.7"
  },
  "devDependencies": {
    "chalk": "^5.3.0",
    "eslint": "^8.56.0",
    "jest": "^29.7.0"
  },
  "keywords": ["demo", "nodejs", "npm"],
  "author": "Your Name <you@example.com>",
  "license": "MIT"
}

Frequently Asked Questions