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 ', 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"
}

The Fields Nobody Reads: browser, private, engines, homepage, bugs, files

Your package.json is cluttered with metadata fields that most developers skip. But ignoring them is a mistake. The browser field tells bundlers like webpack or Rollup which module to use in browser environments. If you maintain a library that works both server-side and client-side, this field prevents bundlers from pulling in Node.js-specific code. The private field is a safety switch: set it to true to prevent accidental npm publish. This is mandatory for internal projects. The engines field declares which Node.js and npm versions your package supports. It's advisory, not enforced, but tools like engine-strict config or yarn can fail the install if the host doesn't match. The homepage and bugs fields are for users: homepage should point to your project's website or repo, and bugs to an issue tracker. Without them, users have to hunt for support. The files field whitelists which files are included when your package is published. By default, npm includes everything except .gitignore-listed files. Use files to ship only what's needed: "files": ["dist", "README.md"]. This reduces install size and avoids leaking tests or source maps. Pro tip: combine files with .npmignore for fine-grained control. These fields are small but critical for maintainability and user experience.

{
  "name": "my-library",
  "version": "1.0.0",
  "private": true,
  "engines": {
    "node": ">=14.0.0",
    "npm": ">=6.0.0"
  },
  "browser": {
    "./index.js": "./browser.js"
  },
  "homepage": "https://github.com/user/my-library#readme",
  "bugs": {
    "url": "https://github.com/user/my-library/issues"
  },
  "files": [
    "dist",
    "README.md"
  ]
}

npx vs npm: When to Use Which

npm is the package manager; npx is the package runner. The confusion stems from npx being bundled with npm since version 5.2. Use npm to install packages globally or locally. Use npx to execute a package without installing it globally. For example, npx create-react-app my-app downloads and runs the latest version of create-react-app without polluting your global installs. npx also resolves locally installed binaries: npx eslint . runs the local eslint from node_modules/.bin. This is cleaner than using npm scripts or global installs. Another use case: running a one-off tool like npx http-server to serve a directory. npx checks the local node_modules first, then the npm cache, then downloads if needed. It also supports specifying a version: npx eslint@7 .. The downside: npx adds a slight overhead for downloading if the package isn't cached. For frequently used tools, install them locally and run via npm scripts. Never use npx in production scripts—use npm scripts with local binaries instead. The rule of thumb: install what you depend on, run what you need once.

# Install a package locally
npm install eslint --save-dev

# Run it via npx (finds local binary)
npx eslint .

# Run a one-off tool without installing
npx create-react-app my-app

# Specify a version
npx eslint@7 .

package-lock.json lockfileVersion: What Each Version Means

The lockfileVersion in package-lock.json determines how npm resolves dependencies. It's an integer that has changed across npm versions. Version 1 (npm 5 and 6) uses a flat structure with requires and dependencies fields. It's human-readable but can cause issues with hoisting and duplication. Version 2 (npm 7+) introduced a more deterministic tree structure with packages and dependencies sections. It's stricter about hoisting and includes metadata like link for workspaces. Version 3 (npm 9+) is similar to v2 but drops the legacy dependencies field, relying solely on packages. This reduces file size and complexity. The lockfile version is auto-generated based on your npm version. If you upgrade npm, the lockfile may be upgraded. This can cause merge conflicts in teams with mixed npm versions. To enforce a consistent lockfile version, use an .npmrc file with lockfile-version=2. Or use npm install --lockfile-version=2. In practice, stick with v2 for npm 7+ projects. Avoid committing lockfiles generated by different npm versions—it leads to non-reproducible installs. Always regenerate the lockfile with a consistent npm version in CI.

// lockfileVersion 1 (npm 5-6)
{
  "name": "my-app",
  "lockfileVersion": 1,
  "requires": true,
  "dependencies": {
    "lodash": {
      "version": "4.17.21",
      "resolved": "...",
      "integrity": "sha512-..."
    }
  }
}

// lockfileVersion 2 (npm 7-8)
{
  "name": "my-app",
  "lockfileVersion": 2,
  "packages": {
    "node_modules/lodash": {
      "version": "4.17.21",
      "resolved": "...",
      "integrity": "sha512-..."
    }
  },
  "dependencies": {
    "lodash": {
      "version": "4.17.21",
      "resolved": "...",
      "integrity": "sha512-..."
    }
  }
}

// lockfileVersion 3 (npm 9+)
{
  "name": "my-app",
  "lockfileVersion": 3,
  "packages": {
    "node_modules/lodash": {
      "version": "4.17.21",
      "resolved": "...",
      "integrity": "sha512-..."
    }
  }
}

Pre/Post Script Hooks: Automate Without Extra Tools

npm scripts support pre and post hooks that run automatically before and after a named script. For example, if you define prebuild, build, and postbuild, running npm run build triggers prebuild → build → postbuild. This is built-in, no plugins needed. Common uses: lint before test (pretest), build before deploy (predeploy), or clean after build (postbuild). The hook names are derived by prepending pre or post to the script name. They work for any script, including lifecycle scripts like prepublishOnly. Be careful: hooks can chain unexpectedly. If you have pretest and test scripts, and pretest itself has a prepretest hook, it will run. This can lead to confusion. Keep hooks simple and avoid deep nesting. Also, hooks run even if the main script fails? No—if prebuild fails, build and postbuild are skipped. This is useful for validation. For example, a prebuild script that checks for environment variables can prevent a broken build. Use hooks to enforce workflows without external tools like Husky (though Husky is still useful for git hooks).

{
  "scripts": {
    "prebuild": "echo 'Running prebuild checks'",
    "build": "webpack --mode production",
    "postbuild": "echo 'Build complete, running cleanup'",
    "pretest": "eslint .",
    "test": "jest",
    "predeploy": "npm run build",
    "deploy": "aws s3 sync dist/ s3://my-bucket"
  }
}