Vibe coding with Claude Code course Β· Module 2: A Next.js project with Claude Code
Node.js and npm: the ship's engine
In this lesson10
Welcome to the second location! In the first one Claude Code wrote a single HTML file for you. Now we start a real project: the "Kraken's Call" game site in Next.js. Before Claude sets it up in the next lesson, the ship needs an engine.
What you will learn
- check whether you have Node.js and npm, and judge whether their versions are enough for Next.js;
- understand the npm commands Claude will ask about in this course, before you click Yes;
- read the
package.jsonfile and say what each script will run; - recognise a permission request at which you must stop.
Problem: code without an engine stays in port
Claude Code installed natively does not need Node.js: it is a separate program that runs on its own. A Next.js project does. The site Claude writes in .tsx files will not open in the browser by itself: somebody has to build it and start a server. That somebody is Node.js. Without it Claude will save the files, but every command that is supposed to run them will end with a command not found message.
The engine and the quartermaster
Node.js is an environment that runs JavaScript outside the browser, on your computer. On our ship it is the engine: it powers the development server, the TypeScript type checking and the tools that build the site.
npm (Node Package Manager) is a package manager, our quartermaster with a cargo hold. A package is a ready-made library or tool written by somebody else, for example react, next or tailwindcss. npm downloads packages from a public registry, stows them in your project and keeps track of their versions. It installs together with Node.js: one installer, two tools.
You install it yourself, once
In lesson 0_3 you met Node.js in a nutshell. If the node --version command answered command not found back then, it is time to install:
- Go to https://nodejs.org and open the download page.
- Keep the version labelled LTS (Long Term Support), the one with long-term support. State as of November 2026: the newest LTS is the 26 line, and the version labelled Alpha is for testing only.
- Lower down, among the ready-made installers, download the file for your system:
.msion Windows,.pkgon macOS. On Linux choose your system on the same page and follow the instructions that appear. - Run the installer and click through the screens with the default settings.
Captain's advice: you install system programs such as Node.js yourself from the official site, and you do not hand them to Claude. The installer asks for the administrator password, and the decision about administrator rights, that is about sudo from lesson 0_3, belongs to you, not to the agent. After installing, close the terminal in Cursor and open a new one so that it sees the new commands.
Test: let Claude inspect the engine room
Open the pirate_ship folder from the previous location in Cursor, run claude in the terminal and check the mode indicator. For now we stay on Manual so that you see every command.
Request for Claude Code:
Check which versions of Node.js and npm I have and tell me whether they
are enough for the Next.js 16 project we will set up in the next lesson.
Before you run a command, say in one sentence what it will do. Do not
install anything.The request has a goal (check the versions), a constraint ("do not install anything") and a description of what you want at the end, namely an assessment. You know these building blocks from lesson 0_5. Claude will answer that it will run two commands:
node -v
npm -v-v is short for --version, so node -v and node --version do exactly the same thing. If Claude asks for permission, read calmly: both commands only print a version number and change nothing on disk. You can do the same check yourself, without Claude, by typing ! node -v in the session.
The result looks roughly like this, the first line is Node.js and the second is npm:
v26.13.1
11.20.0That is how a freshly installed Node.js from the LTS line answered, together with the npm bundled with it; on your machine the numbers may be higher. What counts is the minimum: Next.js 16 requires Node.js 20.9 at least. Claude will compare this for you, but it is worth knowing the rule, because an old version from a long-gone project can sit on a disk for years.
npm commands you will see in permission requests
From the next lesson on Claude runs the npm commands and you approve them. You approve only what you understand, so learn the four most common ones. The first installs the packages your project needs:
npm installnpm reads the list of dependencies from the package.json file, downloads the packages from the registry and stows them in the node_modules folder. Without a package name it installs only what is already on the list and adds nothing new to the project. With a name, for example npm install zod, it adds a new package, and that is a request you read more carefully.
The second starts the development server, on which you view the site while you work:
npm run devnpm run runs the script with the given name from package.json, here the dev script. In a Next.js project it starts a server that shows the site at http://localhost:3000 and refreshes it after every file change. The server runs until you stop it with Ctrl+C, and the site does not go onto the internet.
The third builds the production version, the one you will deploy later:
npm run buildThe build compiles the whole project and checks the TypeScript types. If there is an error in the code, the command ends with a red message, and if it passes, you have hard proof that the project holds together. That is why in this course npm run build will be the check you ask Claude for after changes. A build deploys nothing: the finished version stays on your disk.
The fourth is npx, the younger brother of npm, which runs a tool without installing it permanently:
npx create-next-app@latest krakens-callnpx downloads the create-next-app tool, runs it once and leaves nothing in your system. @latest means the newest version, and krakens-call is the project name. With this command, plus a few extra flags, Claude will set up the project in the next lesson.
package.json: the ship's card
Every JavaScript project has a package.json file. It is the ship's card: a name, scripts and a list of dependencies. In the next lesson you will open it in Cursor, and this is how it looks in a fresh Next.js project created in November 2026:
{
"name": "krakens-call",
"version": "0.1.0",
"private": true,
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "eslint"
},
"dependencies": {
"next": "16.4.6",
"react": "19.3.0",
"react-dom": "19.3.0"
},
"devDependencies": {
"@tailwindcss/turbopack": "4.3.3",
"@types/node": "^20",
"@types/react": "^19",
"@types/react-dom": "^19",
"eslint": "^9",
"eslint-config-next": "16.4.6",
"tailwindcss": "4.3.3",
"typescript": "^5"
}
}The scripts section holds named orders: npm run dev runs next dev, npm run build runs next build, npm run start runs the built version, and npm run lint runs eslint, a program that looks for errors and risky patterns in the code. When Claude asks for permission for npm run with some name, look into scripts: there you will read what will really be executed.
dependencies are the packages the app needs to run, that is Next.js and React. devDependencies are tools needed only while working on the code: TypeScript, Tailwind, ESLint. The version numbers on your machine may be newer, and the shape of the file stays the same.
node_modules and package-lock.json: the hold and the cargo list
After npm install a node_modules folder with the downloaded packages appears in the project. It can be huge, hundreds of megabytes, and anyone can recreate it with one command, so it does not go into Git. A project from create-next-app has this covered already, because its .gitignore file contains this line:
/node_modulesThe slash at the start means a folder in the project's root directory. Thanks to this line Git skips the hold, and in the Source Control panel in Cursor you will not see thousands of files from other people's packages.
Next to package.json lies package-lock.json, the exact cargo list: the specific versions of all packages, including those that other packages need. You commit this file, because thanks to it anyone who downloads the project gets exactly the same versions after npm install. You do not read it line by line, but when Claude installs something, you will see changes in both files in Source Control.
Captain's review: permission requests for npm
Before you click Yes on an npm command, check three things:
- Was this package in the request?
npm installwith a name adds a new dependency. If you did not ask for it, ask Claude why it needs it and whether it can be done without. - Does the command contain
-gorsudo? The-gflag installs a package globally, for the whole system, not for the project. Such an installation reaches beyond the ship, so before you agree, ask why it is needed. - What changed in the files? After the installation open Source Control and read the changes in
package.json: a new line independenciesordevDependenciesmust match what you asked for.
A typical agent mistake: it installs a library "just in case" or gives a command from memory, from an older version of the tool. You catch it most easily at point 3. A package you cannot justify is a signal to stop Claude with the Esc key and ask questions.
Next step
You have an engine and you know what the orders for the engine room do. In the next lesson you will give Claude Code a request that sets up a whole Next.js project, and you will read in Cursor every file that appears.
Remember: you mount the engine yourself, but you read every order for the engine room before you sign it.
Spotted a mistake in this lesson?
Check yourself
Answer the questions from this lesson. Pick an answer to see right away whether it is correct.
1. What is Node.js?
2. Which command installs all dependencies from package.json?
3. What is npm?
4. What does the package.json file contain?
5. What is the npx command used for?
6. Why don't we commit the node_modules folder to Git?
Hands-on tasks in the game
- Code editor
Check the Node.js version in the terminal and write the command you used in the commands.sh file.
- Click in order
Build the command that checks the Node.js version:
- Vertical ordering
Arrange the typical steps for running a downloaded npm project:
- Horizontal ordering
Arrange the parts of the command that creates a new Next.js project (left to right):
Tasks after this lesson
- QuestionQuiz: What is Node.js?
- QuestionQuiz: npm Commands
- Coding taskPractice: Check Node.js Version
- Click in orderOrdering: Node.js version command
- QuestionQuiz: What is npm?
- QuestionQuiz: The package.json file
- Put in orderOrdering: Project commands
- QuestionQuiz: The npx command
- Put in orderOrdering: Next.js project creation command
- QuestionQuiz: The node_modules folder