Lesson 2 of 6

Node.js and npm

About 15 minutesRun JavaScript on your own computer and borrow other people's code.

JavaScript is the language of web pages. Node.js is a program that runs JavaScript files directly on your computer, outside the browser. It's the engine under most of the tools you'll use to vibe code, including the deploy tool in lesson 4.

Every AI tool you want runs on this

  • Gemini CLI? A Node program.
  • Claude Code? JavaScript, the language Node runs.
  • Codex? One npm command and it's yours.
  • The tools that are changing how software gets made are, under the hood, mostly Node.
  • And npm is the door: type one line, and a program someone spent years building lands on your computer, ready to run.

Skip this lesson and those tools stay magic boxes. Do it, and you'll know exactly what you're running.

What “runtime” means

A .js file is just text: bytes that spell out instructions. Something has to read those instructions and carry them out. That something is a runtime.

  • In a browser, the runtime is built in. JavaScript there can change the page, but it can't touch your files.
  • Node is a runtime you install. JavaScript there can read and write files, start a web server, and run in your terminal like any other command.

Same language, different place it runs. When people say “a Node app”, they mean a folder of .js files that Node runs.

Install it

Go to nodejs.org, download the version marked LTS (long-term support, the stable one), and run the installer. Then open a new terminal and check:

Terminal
$ node -v
v24.22.1
$ npm -v
11.19.1

Your numbers will be different, and that's fine. If you see command not found, close the terminal and open a fresh one so it picks up the new program.

Your first script

Go into the hello folder you made in lesson 1 and create a file. On Mac or Linux you can do it in one line; on any computer you can also make hello.js in a text editor and save it into that folder.

Terminal
$ cd ~/hello
$ echo 'console.log("hello, world");' > hello.js
$ node hello.js
hello, world

node hello.js means: run the Node program, and give it the file hello.js. Notice the file path is relative, so it only works if you're standing in the folder that holds hello.js. Lesson 1 in action.

npm: other people's code

Node comes with npm, the Node package manager. A package is a program, or a piece of one, that someone else wrote and published so you don't have to. There are millions of them, and npm installs any of them with one command.

Every Node project has a file called package.json that describes it. Make one:

Terminal
$ npm init -y
Wrote to /Users/you/hello/package.json

Then install a package. cowsay is a silly one that draws a talking cow:

Terminal
$ npm install cowsay
added 41 packages, and audited 42 packages in 1s

Three things just happened, and you can see all of them with ls:

  • A folder called node_modules appeared. It holds the package and everything it needs (that's why it says 41 packages). It can get huge; you never edit it and you never upload it.
  • package.json got a new dependencies entry naming cowsay.
  • package-lock.json appeared. It records the exact versions installed, so the project installs the same way on another computer.
cow.js
const cowsay = require("cowsay");
console.log(cowsay.say({ text: "I live in node_modules" }));
Terminal
$ node cow.js
 ________________________
< I live in node_modules >
 ------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Read a package.json

You'll see this file in every project an AI builds for you. Click any line to see what it means.

Scripts: the project's own commands

The scripts section gives names to commands. Instead of remembering node server.js, everyone just types npm start. Anything else runs with npm run and its name:

Terminal
$ npm start
$ npm run dev

When you open a project you didn't write (or that an AI wrote), the first thing to do is ls, then read package.json, then run npm install to fetch its node_modules, then look at scripts to see how to start it.

npxnpx runs a package's command without adding it to your project. You'll use it in lesson 4: npx wrangler deploy runs Cloudflare's deploy tool on the spot.

A web server on your own computer

One more script, because it's the bridge to deploying. This one makes your computer answer web requests.

server.js
const http = require("http");

http.createServer((request, response) => {
  response.writeHead(200, { "content-type": "text/html" });
  response.end("<h1>hello from my computer</h1>");
}).listen(3000);

console.log("open http://localhost:3000");
Terminal
$ node server.js
open http://localhost:3000

Open that address in your browser and there's your page. localhost means “this computer”, and 3000 is the port, like a door number. It keeps running until you press Ctrl C in the terminal. Only you can see it, for now. Lesson 4 is about letting everyone else see it too.

You download a project from GitHub and run npm start. It fails with “Cannot find module”. What's the most likely fix?

Projects are shared without node_modules (it's too big). npm install reads package.json and downloads everything listed in it.

Remember
  • Node is a runtime: it runs .js files on your computer. node file.js.
  • package.json describes a project: its name, its packages, its scripts.
  • npm install fills node_modules. Never edit or upload that folder.
  • npm start / npm run name run the project's scripts. Ctrl C stops them.