Create the Next.js app and see it running on your laptop

This is where the real project starts. By the end of this lesson you have a working web app on your laptop. It will not do anything useful yet. It will exist, run, and be under version control, which is more than most abandoned side projects ever manage.

Step 1: Generate the project

Open a terminal:

cd ~/projects
npx create-next-app@latest client-tracker

npx runs a program without permanently installing it. create-next-app is the official Next.js project generator. The first time, it may ask “Ok to proceed? (y)”: type y and press Enter. Then it asks one question:

Would you like to use the recommended Next.js defaults?

Choose Yes, use recommended defaults. Press Enter. It creates a folder called client-tracker, downloads what it needs (a minute or two), and finishes with a short “Success!” message.

Those defaults are TypeScript, ESLint, Tailwind CSS and the App Router. You do not need to know what any of those are. They are the choices a senior engineer would make today, and they are the choices Claude Code is best at working with.

It also did two things quietly. It made the folder a Git repository with a first commit, and it added a file called AGENTS.md (plus a CLAUDE.md that points to it) with up-to-date notes for AI coding tools about how this version of Next.js works. Both are gifts. Leave them.

Step 2: Run it

cd client-tracker
npm run dev

The terminal prints a few lines and then something like:

▲ Next.js 16.x
- Local:   http://localhost:3000

Open a browser and go to http://localhost:3000. You see the Next.js welcome page. That page is your app, running on your laptop, served by the process in that terminal window.

Two things to understand about this window:

• It has to stay open. Close it, or press Ctrl + C in it, and the app stops. When you come back tomorrow, you run npm run dev again.
• It is now busy. You cannot type other commands in it. This is why the next step opens a second terminal.

Step 3: The two-terminal setup

You will work like this for the rest of the course:

• Terminal 1 runs npm run dev. You mostly ignore it, except when it prints red errors, which are useful.
• Terminal 2 runs Claude Code.

Open a second terminal window. On Mac, Cmd + N in Terminal. On Windows, open PowerShell again from the Start menu. Then:

cd ~/projects/client-tracker
claude

Claude Code starts inside the project. Say yes to trusting the folder, and press Shift + Tab until the bar says manual mode on. It can now see every file the generator made.

Step 4: Let Claude Code learn the project

/init

This asks Claude Code to look through the project and write down what it finds in CLAUDE.md. Since create-next-app already made one, it will offer to update or improve it. Approve. From now on, every session starts with Claude reading that file, so it does not have to rediscover the project each time.

Then ask:

Give me a tour of this project for someone who has never seen a web app. Which folder holds the pages? Which file is the home page? Which files should I never touch by hand?

The answer you want to remember: the app folder holds the pages, and app/page.tsx is the home page.

Step 5: Your first change

Press Shift + Tab until plan mode is on. Then:

Replace the contents of the home page with a simple placeholder: a heading that says "Client Tracker", a one-line subheading "Every client, one screen.", and nothing else. Keep the existing layout and fonts. Remove the Next.js logo and links. Tell me the plan first.

Read the plan. It should touch one file, app/page.tsx, and maybe the global stylesheet. Approve it with manually approve edits, then approve the change. Then look at your browser tab. It updates on its own; you do not need to refresh. That is the dev server’s job, and it is one of the nicest things about working this way.

If the page did not change, refresh once. If it still did not change, look at Terminal 1 for a red error and paste it into Claude Code.

Step 6: Open it in VS Code and look

Open VS Code, choose File → Open Folder, and pick client-tracker inside your projects folder. The project appears on the left. Click into app, then page.tsx. You are looking at the file Claude just edited. You do not need to understand it. You need to know that it exists, where it is, and that when Claude says “I edited app/page.tsx,” this is what it means.

(Terminal shortcut for later: code . inside a project folder opens it in VS Code. If that does not work on Mac, open VS Code, press Cmd + Shift + P, type “shell command,” and choose Install ‘code’ command in PATH.)

Close VS Code or leave it open; either is fine.

Step 7: Commit and publish

Back in Claude Code:

Commit everything with the message "Placeholder home page".

Then publish it to GitHub the same way you did in Lesson 5: GitHub Desktop → File → Add Local Repository → choose client-tracker inside projects in your home folder → Add Repository → Publish repository, private. This is the project that will eventually go live, so it needs to be on GitHub. From here on, “commit and push” from Claude Code keeps it current.

Stopping and coming back

Every lesson from here on starts with “everything running.” Here is what that means, so you can stop at the end of any lesson and pick up tomorrow.

To stop: in Terminal 1, press Ctrl + C. In Terminal 2, type /exit. Close the windows.

To come back:

1. Terminal 1: cd ~/projects/client-tracker then npm run dev.
2. Terminal 2: cd ~/projects/client-tracker then claude, then Shift + Tab to manual mode.
3. From Lesson 8 on, also: open Docker Desktop, wait for the whale to settle, and in a third terminal run cd ~/projects/client-tracker then docker compose up -d before step 1.

Bookmark this section. It is the one people come back to.

Check your work

• Terminal 1 is running npm run dev and http://localhost:3000 shows “Client Tracker.”
• Terminal 2 has Claude Code running inside ~/projects/client-tracker, in manual mode.
• CLAUDE.md exists in the project folder (you can see it in VS Code).
• The commit history shows the generator’s first commit and your “Placeholder home page” commit.
• The repository is on github.com, private.

If something went wrong

npx create-next-app fails or hangs. Check node --version prints v22 or higher. Check your internet. If it complains about an existing folder, you already ran it; cd client-tracker and carry on. On Windows, if it says running scripts is disabled, see Lesson 2, Step 2.

localhost:3000 shows “This site can’t be reached.” Terminal 1 is not running the dev server, or it crashed. Look at it. Run npm run dev again. If it says port 3000 is in use, another copy is running somewhere; close other terminal windows and try again, or use the different port it suggests.

Red errors in Terminal 1 after a change. Copy the whole error and paste it into Claude Code with: “The dev server printed this error after your change. Fix it.” This is the normal loop, not a disaster.

The browser shows an old version. Hard refresh: Cmd + Shift + R on Mac, Ctrl + Shift + R on Windows.

Claude Code cannot see the files. Check the folder shown above the prompt. If it is not client-tracker, /exit, cd ~/projects/client-tracker, claude.

Next

Lesson 7 builds the actual screen: the client list, the add form, the status pills. With fake data first, so you can get the screen right before the database complicates things.