Node.js and npm: Running JavaScript Outside the Browser

In the Beginner course, every line of JavaScript ran in a browser tab. That's fine for making a page react. But most JavaScript projects you'll meet at work also run outside the browser: build tools, test runners, small scripts that clean a CSV, servers. All of that runs on Node.js. If you can't run Node and npm, you can't run the project, and you can't run its tests. So this comes first.

What Node.js and npm actually are

• Node.js is a program that runs JavaScript on your computer, without a browser. It uses the same engine as Chrome (V8), so the language is the same.
• npm comes with Node. It downloads packages (code other people wrote) into your project and runs your project's scripts.

You don't need to know how Node works inside. You need to know what's the same as the browser and what isn't.

Check that you have it

Open a terminal (PowerShell or Command Prompt on Windows, Terminal on macOS or Linux) and type:

node -v
npm -v

You should get two version numbers, something like v24.21.0 and 11.19.0. If you get "not recognized" or "command not found", Node isn't installed or isn't on your PATH. Install the LTS version from nodejs.org. The tutorial Install Node.js and Check It Actually Works walks through it, including the PATH problem.

Run your first file

Make a folder, put this in a file called hello.js:

const items = ["rice", "eggs", "coffee"];
console.log(`You have ${items.length} items.`);
console.log(`Node version: ${process.version.startsWith("v")}`);

You have 3 items.
Node version: true

Then run it from that folder:

node hello.js

That's it. No HTML page, no script tag, no reload. The output goes to the terminal instead of the browser console.

Browser JavaScript vs Node.js

Same language, different surroundings. This is where people get confused.

• Only in the browser: document, window, alert, the DOM, click events. There is no page in Node.
• Only in Node: reading and writing files (node:fs), process (arguments, environment variables, exit codes), starting servers.
• In both: the language itself, console.log, fetch, setTimeout, JSON, Math, Date.

So if you copy browser code into a Node file, this happens:

try {
  document.querySelector("h1");
} catch (error) {
  console.log(`${error.name}: ${error.message}`);
}

ReferenceError: document is not defined

That error doesn't mean your code is wrong. It means you're running page code where there's no page.

npm: installing a package

Make a project folder, then create a package.json file (the project's ID card) and install one package:

mkdir order-report
cd order-report
npm init -y
npm install dayjs

npm creates three things:

1. package.json now lists dayjs under dependencies.
2. package-lock.json records the exact version that was installed.
3. node_modules/ holds the package code itself.

The next lesson covers what those files are for. For now, the rule: never edit node_modules by hand, and never commit it to Git. It can always be rebuilt from package.json and the lock file. Add it to .gitignore.

npm scripts

Instead of remembering long commands, put them in package.json:

{
  "name": "order-report",
  "version": "1.0.0",
  "scripts": {
    "report": "node report.js",
    "test": "vitest run"
  }
}

Then anyone on the team runs npm run report or npm test. They don't need to know which file or which flags. This is how most projects are run, so when you open a new project, look at scripts first.

npx: run a tool without installing it globally

npx runs a command from a package. If the project has it installed, it uses that version. If not, it offers to download it temporarily. For example, npx vitest --version runs the project's own Vitest. This matters because two projects can need two different versions of the same tool. Installing tools globally with npm install -g makes every project share one version, and sooner or later one project breaks.

Common mistakes

• Running node hello.js from the wrong folder and getting Cannot find module. Check the folder with cd and dir (Windows) or ls.
• Using document or window in a Node script.
• Committing node_modules to Git. It's huge and machine-specific.
• Installing everything with -g "so it works everywhere".
• Ignoring the version: a tutorial written for Node 14 may not behave the same on Node 24.

What happens if you skip this

Every tool in the rest of this course (modules, tests, fetch from a script) runs on Node. If you skip it, you'll copy commands from READMEs without knowing why npm install changed three files, and the first "Cannot find module" will cost you an afternoon.

Open a terminal now and run node -v. What version do you have, and is it an LTS?