npm and package.json — EACCES Permission Error Without sudo

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 <package-name>', 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 <script-name>' — 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"
}

Understanding node_modules and package-lock.json

When you run npm install, npm downloads every package and its own dependencies (sub-dependencies) into a folder called node_modules. This folder is the runtime environment for your project. It's also massive — a typical React project can have 200,000+ files in node_modules. That's why you never commit it to Git.

Instead, npm created package-lock.json. This file records the exact version of every single package and every sub-package that was installed. It's a complete snapshot of your dependency tree. When someone else clones your repo and runs npm install, npm reads the lockfile and installs the exact same versions, down to the sub-dependency. This eliminates "works on my machine" problems.

Without package-lock.json, if package 'A' depends on package 'B' with range ^1.0.0, and 'B' releases version 1.1.0 after you last ran install, your teammate gets B@1.1.0 while you have B@1.0.0. The lockfile locks everything.

You should ALWAYS commit package-lock.json to Git. Never delete it, never add it to .gitignore. Some old tutorials say to delete it because it's "magical" — that's terrible advice. Keep it.

{
  "name": "my-first-node-project",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "my-first-node-project",
      "dependencies": {
        "axios": "^1.6.7"
      }
    },
    "node_modules/axios": {
      "version": "1.6.7",
      "resolved": "https://registry.npmjs.org/axios/-/axios-1.6.7.tgz",
      "integrity": "sha512-...",
      "dependencies": {
        "follow-redirects": "^1.15.4"
      }
    },
    "node_modules/follow-redirects": {
      "version": "1.15.5",
      "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.5.tgz",
      "integrity": "sha512-..."
    }
  }
}

Semantic Versioning: The Contract Your package.json Signs

Every dependency in your package.json carries a version string like ^4.17.21. That caret isn't decorative. It's a promise. Semantic versioning (semver) is the unspoken contract between you and every package author. The format is MAJOR.MINOR.PATCH. Bump the major for breaking changes. Minor for new features (backward-compatible). Patch for bug fixes. The caret (^) locks the major version but allows minor and patch updates. The tilde (~) locks the major AND minor, only permitting patches. No symbol means a deadlock — exact version only. In production, you never want to pin exact versions for everything (fork management nightmare). But you also never want * (any version). That's chaos. Practically: use ^ for most deps, ~ for tools like formatters, and exact for deployment-related packages. Your CI pipeline will thank you. Understanding semver in your package.json saves you from the dreaded "works on my machine" syndrome across environments.

{
  "dependencies": {
    "express": "^4.18.2",  // allows 4.x.x updates
    "lodash": "~4.17.21", // only 4.17.x patches
    "left-pad": "1.3.0"    // exact, never changes
  }
}

Peer Dependencies: The Ticking Time Bomb in Your package.json

Most developers understand dependencies and devDependencies. Few grasp peerDependencies. This field says: "I need this package to work, but you — the consumer — must provide it." Think React plugins. If you build a UI component library, you shouldn't bundle React inside it. Your consumers already have React. Bundling duplicates it (and breaks hooks). That's where peerDependencies shine. They declare compatibility without installation. But here's the trap: npm v6 and earlier installed peer deps automatically. npm v7+ does not. Your library installs silently, then explodes at runtime with Cannot find module 'react'. The fix? Specify peerDependenciesMeta to mark optional peers. And always test your library in a fresh project. Another pattern: use peerDependencies for plugins (Webpack loaders, ESLint configs, Babel presets). They declare a shared interface. Misuse them, and you get version collisions that require --legacy-peer-deps to resolve. That flag is a code smell.

{
  "name": "my-react-grid",
  "version": "2.0.0",
  "peerDependencies": {
    "react": ">=16.8.0",
    "react-dom": ">=16.8.0"
  },
  "peerDependenciesMeta": {
    "react-dom": {
      "optional": true  // for server-side rendering
    }
  }
}

The `exports` Field: Modern package.json's Best Kept Secret

For years, the main field was the only entry point. Then came browser, module, and a rat's nest of bundler-specific fields. The exports field in Node.js 12.7+ cleaned it all up. It defines a single source of truth for module resolution. Specify one entry point, or map multiple (like import vs require). It also enables subpath exports — exposing internal modules without leaking your entire src folder. This is huge for library authors. Without exports, consumers can require('your-package/internal/secret') and break encapsulation. With exports, only explicitly listed paths are accessible. The catch? It's strict. If you define exports, the main field is ignored. Misconfigure it, and your library becomes unimportable. Always test both require() and import syntax. A pattern I use: expose a clean API surface, hide implementation details, and provide a package.json conditional export for different environments (Node vs browser vs React Native).

{
  "name": "my-utils",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    },
    "./date": {
      "import": "./dist/date.mjs",
      "require": "./dist/date.cjs"
    }
  },
  "main": "./dist/index.cjs",  // fallback for older Node
  "type": "module"
}