Setting Up Node.js and npm for Beginners

A new Node.js project often begins with a command that looks harmless: `npm install`. Minutes later, a beginner sees `package.json`, `package-lock.json`, `node_modules`, scripts, versions, and an error about an executable that cannot be found. The failure is rarely that npm is random. The project’s layers were never named.

Node.js is the runtime that can execute JavaScript outside the browser. npm is the package manager and command runner used across the Node ecosystem. `package.json` describes the project, the lockfile records a resolved dependency tree, `node_modules` contains installed packages, and npm scripts provide repeatable commands. Setup becomes easier when each object has one job.

Start with the runtime, not the project

Install Node.js, then confirm what the shell can see:

node --version
npm --version
which node
which npm

On Windows, use `where node` and `where npm`. The important result is not a specific version number in a beginner article; it is that the commands resolve consistently in the terminal where the project will run.

The official Node.js introduction calls npm the standard package manager for Node.js and explains that it installs, updates, and manages dependencies in its package manager guide.

Create the manifest before adding complexity

Make an empty project and initialize the manifest:

mkdir weather-cli
cd weather-cli
npm init -y

The `-y` flag accepts default answers. For a learning project, open the resulting `package.json` immediately:

{
  "name": "weather-cli",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  }
}

The file is not merely a formality. It is a contract that tells tools what the project is called, which entry point it has, which commands it supports, and which packages it needs.

Add one dependency and inspect the effect

Install a package that the project actually needs. The example uses a common HTTP client only to demonstrate the files npm changes:

npm install axios

After the command, expect three changes: a `dependencies` entry in `package.json`, a `package-lock.json` file or update, and a local `node_modules` directory. npm’s documentation distinguishes runtime dependencies from development dependencies; use `–save-dev` for tools needed during development, such as a test runner, rather than by the application in production.

Do not commit `node_modules` to a typical application repository. Commit the manifest and lockfile according to the project’s policy, then let each environment install the declared tree.

The lockfile records more than the top-level name

A package can depend on other packages, which can depend on more packages. The lockfile records the resolved tree so that another installation does not have to make every version decision again. It can be large and unfamiliar; that is normal. Do not edit it by hand to “fix” a dependency mismatch unless the project’s documentation specifically requires it.

When a teammate clones the project, the repeatable setup is usually:

git clone https://example.com/weather-cli.git
cd weather-cli
npm install

The result is a new `node_modules` directory built from the project declarations. The operating system path to the directory may differ, but the dependency contract should be consistent.

Scripts turn memory into a project interface

Long commands are easy to mistype and hard to remember. Add names that describe the project’s actions:

{
  "scripts": {
    "start": "node index.js",
    "check": "node --check index.js",
    "test": "node --test",
    "format": "prettier . --check"
  }
}

Run them with:

npm run check
npm test
npm start

The npm documentation explains that the `scripts` property supports arbitrary scripts and lifecycle events, and that `npm run <name>` executes a named script in the official scripts reference. Some names, such as `test` and `start`, have convenient npm commands.

Where local executables come from

When you install a development tool locally, its executable is typically placed in `node_modules/.bin`. npm adds that directory to the PATH while running a project script. That is why `npm run format` can find a locally installed formatter without requiring a global installation.

npm install --save-dev prettier
npm exec prettier . --check
npm run format

A command that works only after a global install can hide a project dependency. Prefer local, declared tools for project commands so a teammate and a CI system can reproduce the setup.

A setup failure map

Our articles on package managers, environment variables, and coding environment setup connect npm to the wider project lifecycle. The central rule remains: diagnose the layer before reinstalling everything.

Fresh-machine rehearsal

To test whether the setup is documented, clone the project into a new directory or ask a teammate to follow the README:

1. Confirm the required Node version and package manager.
2. Clone the repository and enter the project directory.
3. Run `npm install` or the project’s documented clean-install command.
4. Run the check, test, and start scripts.
5. Record any required environment variables without committing their values.
6. Open the application and verify one user-visible path.

If the setup fails because only the original author knows an undocumented command, the project has a documentation problem, not just a beginner problem.

Questions about Node.js and npm

Make setup a repeatable experiment

A Node project is ready for another developer when its runtime, manifest, lockfile, dependencies, and commands form a visible contract. Do not memorize a ritual of `npm install` and hope. Inspect what the command changes, run the named scripts, and rehearse the setup away from your original machine.

Turn the setup contract into a README another person can follow →

Version drift is a project problem

Two developers can run the same `npm test` command and receive different results because their Node versions, operating systems, environment variables, or lockfile states differ. The first fix is not to delete `node_modules` immediately. Capture the evidence:

node --version
npm --version
npm config get registry
npm ls --depth=0
npm run

The output shows the runtime, package manager, top-level installed packages, and scripts available to the project. Compare it with the README and CI configuration. If the project requires a particular Node release, record that requirement in a version file or setup documentation rather than relying on a teammate’s memory.

Use a clean installation when the project’s policy calls for reproducibility. `npm ci` is commonly used in automated environments because it installs from the lockfile and expects the manifest and lockfile to agree. It is not a universal repair command; if the lockfile is stale or the project does not support it, fix the declaration process first.

Do not solve every setup difference by installing packages globally. Global state hides the project’s actual contract and makes a fresh machine harder to reproduce.

Make the command contract explicit

A useful `package.json` does not force a new developer to guess which command starts the project. Name the common paths and keep them small:

{
  "scripts": {
    "dev": "node src/server.js",
    "check": "node --check src/server.js",
    "test": "node --test tests/"
  }
}

Now the project exposes a visible contract: `npm run dev` is for local work, `npm run check` catches a syntax error, and `npm test` runs the test directory. If a script needs an environment variable, document the name and a safe example value in the README, never the real secret. A fresh machine should be able to discover the first command by reading the manifest and documentation together.

When a script fails, read its exit code and output before installing another package. A missing module, a wrong working directory, an unavailable environment variable, and an unsupported Node feature require different corrections. Reinstalling everything can hide the original evidence and make the next failure harder to classify.

Alex Carter

Alex Carter is the editorial name behind Vandutz Academy, a programming blog for beginners. Alex reviews and tests the examples and explanations published on the site, with a focus on making Python, JavaScript, web development, and developer tools easier to understand.