Vibe coding with Claude Code course Β· Module 2: A Next.js project with Claude Code
Claude Code sets up a Next.js project
In this lesson12
The engine runs time to launch the ship. In this lesson Claude Code will set up the project of the "Kraken's Call" game site, and you will read in Cursor everything that appears and demand proof that the project builds.
Problem: the wizard asks twelve things
A new Next.js project is set up by the create-next-app wizard. Started without flags, it asks questions one by one: about the name, about the recommended settings, and after you choose your own settings about ten more things, from TypeScript to files for agents. Each one waits for an answer from the keyboard. The second one looks like this:
? Would you like to use the recommended Next.js defaults? βΊ - Use arrow-keys. Return to submit.
β― Yes, use recommended defaults
TypeScript, ESLint, No React Compiler, Tailwind CSS, No src/ directory, App Router, Cache Components, AGENTS.md, Agent feedback
No, customize settingsThe recommended settings are almost right, but they turn on two things we do not want in this course: Cache Components and Agent feedback. Instead of clicking through the wizard, you will give Claude all the answers up front and it will turn them into flags. With flags the wizard asks not a single question, and you know in advance what will be created.
What Next.js is
Next.js is a framework for building web apps in React. It gives you ready-made what plain React makes you assemble by hand: pages as files, rendering on the server and a development server. The React documentation (react.dev) lists it first among the frameworks recommended for new apps.
Next.js has two ways of laying out pages. The App Router keeps pages in the app/ folder and is recommended in new projects. The Pages Router keeps them in the pages/ folder: it is the older way, still supported. In the course we use the App Router.
Request for Claude Code
Create a new, empty projects folder in Documents, separate from pirate_ship, because the wizard creates its own Git repository in a new project. Open it in Cursor (File, Open Folder), run claude in the terminal and switch the session to Manual.
Request for Claude Code:
Set up a new Next.js project called krakens-call in this folder with
npx create-next-app@latest, so that the wizard asks no questions at all:
TypeScript, ESLint, Tailwind CSS, App Router, no src/ folder, with the
AGENTS.md file, without Cache Components, without agent feedback, npm as
the package manager. Before you run the command, show it and explain
every flag. At the end run npm run build in the new project and show
the result.The request has a goal, a complete list of requirements, a demand for an explanation before running, and a check at the end. The last sentence is the most important: "done" from an agent is a report, and the build result is proof.
What Claude proposed: the command with flags
Claude will explain the flags and ask permission for a command similar to this one:
npx create-next-app@latest krakens-call --ts --eslint --tailwind --app --no-src-dir --no-cache-components --agents-md --no-agent-feedback --use-npmRead it flag by flag before you click Yes:
krakens-callis the name of the project and of the folder that will appear;--tsturns on TypeScript,--eslintthe ESLint linter, and--tailwindTailwind CSS;--appchooses the App Router, and--no-src-dirkeeps the code inapp/, without an extrasrc/folder;--no-cache-componentsturns off Cache Components;--agents-mdadds anAGENTS.mdfile with instructions for agents;--no-agent-feedbackturns off agents preparing anonymous feedback about Next.js;--use-npminstalls the packages with npm.
The --no- prefix reverses a default option, and the wizard's documentation shows it with the example of --no-ts. There is no bundler flag, because Turbopack, the Next.js bundler, is the default. Agent feedback is off with flags anyway, but we write it out so that the command says everything by itself.
Why without Cache Components
Cache Components is a new caching model in Next.js: a page is prepared in advance by default, and everything that depends on a specific request has to be wrapped in <Suspense> or marked to be remembered. Since version 16.4 the wizard turns this model on in the recommended settings (state as of November 2026).
The examples in the following locations are written in the model without Cache Components. The page of a single post in a Twitter clone, for example, reads the number from the address at the very top of the component, just like this simple ship page. params are the parameters from the address, and PageProps is a type that Next.js prepares for every page:
export default async function ShipPage({ params }: PageProps<"/ships/[id]">) {
const { id } = await params;
return <h1>Ship {id}</h1>;
}In a project with Cache Components npm run build stops on this page with the message "Next.js encountered uncached or runtime data during prerendering". Without Cache Components the same page builds without an error as a dynamic page. The Next.js team announces that in version 17 this model will become the default, so we will come back to it in due time. Today we turn it off knowingly and we know why.
What the wizard printed
After you agree, the wizard works for about a minute. At the start it prints the options you did not give and the values it took for them:
Using defaults for unprovided options:
--no-react-compiler No React Compiler (use --react-compiler for React Compiler)
--import-alias "@/*"React Compiler stays off, and the import alias @/* lets you write @/app/... in imports instead of paths with dots. Then the wizard installs the packages, creates a Git repository and makes the first commit "Initial commit from Create Next App". You will know it is over by the line Success! Created krakens-call. npm warnings about a deprecated package and vulnerabilities are information, not an error. Do not agree to npm audit fix --force: npm itself says this command introduces breaking changes.
Where Claude works now
The project was created in the krakens-call subfolder, and the Claude session still works one folder up, in projects. The next requests should go into the project, so move the port: close the session with the /exit command, open the krakens-call folder in Cursor (File, Open Folder) and run claude in a new terminal. If you prefer to stay in the same terminal, after /exit type:
cd krakens-call && claudecd moves the terminal to the project folder, and && from lesson 0_3 runs claude only if the move succeeded. Check the working directory above the request field: the path must end with krakens-call.
What appeared: reading in Cursor
The file tree on the left will show this project. I leave out the node_modules/ folder, the .next/ folder that appears after the first build, and the images in public/:
krakens-call/
βββ app/
β βββ favicon.ico
β βββ globals.css
β βββ layout.tsx
β βββ page.tsx
βββ public/
βββ .gitignore
βββ AGENTS.md
βββ README.md
βββ eslint.config.mjs
βββ next-env.d.ts
βββ next.config.ts
βββ package-lock.json
βββ package.json
βββ tsconfig.jsonThe app/ folder is the App Router: every page.tsx file in it is a separate page. public/ keeps files available directly under the site's address, for example images. Notice also what is missing here: a CLAUDE.md file, a tailwind.config file and postcss.config.mjs. Tailwind 4 is set up in CSS, more about that in the next lesson.
Open app/page.tsx. This is the home page, that is the / address. The Home component returns what you see in the browser, and in short it looks like this:
export default function Home() {
return (
<div className="flex flex-col flex-1 items-center justify-center bg-zinc-50 font-sans dark:bg-black">
<main className="flex flex-1 w-full max-w-3xl flex-col items-center justify-between py-32 px-16 bg-white dark:bg-black sm:items-start">
{/* Next.js logo, heading and links */}
</main>
</div>
);
}export default function tells Next.js that this function is a page. The long strings in className are Tailwind classes, exactly the kind Claude will write for you; you will learn to read them in the next lesson. The full file also contains the heading "To get started, edit the page.tsx file.".
app/layout.tsx is the common frame of all pages, the hull in which the successive decks sail. In it you will see the metadata object described by the Metadata type and the RootLayout function, which receives children described by the LayoutProps type:
export const metadata: Metadata = {
title: "Create Next App",
description: "Generated by create next app",
};
export default function RootLayout({ children }: LayoutProps<"/">) {
return (
<html
lang="en"
className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
>
<body className="min-h-full flex flex-col">{children}</body>
</html>
);
}metadata is the title and description of the page, visible among other places on the browser tab. children is the content of the current page, which the layout puts into <body>, and geistSans and geistMono are the Geist fonts loaded at the top of the file.
Now the file that confirms the flags worked. Open next.config.ts, the Next.js configuration:
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
/* config options here */
turbopack: {
rules: {
"*.css": {
loaders: ["@tailwindcss/turbopack"],
as: "*.css",
},
},
},
};
export default nextConfig;The only option set is a Turbopack rule that passes CSS files through Tailwind. There is no cacheComponents: true line or partialPrefetching: true, which the recommended settings add, and no experimental block with agentFeedback. The absence of these lines is proof that both --no- flags worked.
Finally AGENTS.md, a file with instructions for agents such as Claude Code. The wizard put one block into it with the heading "This is NOT the Next.js you know". The block warns the agent that this version of Next.js differs from what the model may have learned, and tells it to read the documentation from the node_modules/next/dist/docs/ folder before writing code. Claude Code reads AGENTS.md when the project has no CLAUDE.md file, so this hint reaches every session in this folder. The block is also recreated by next dev itself, so do not delete it. You will add your own project rules later in this location.
Proof instead of a word: npm run build
The last sentence of the request told Claude to build the project. In the result you look for lines like these:
β² Next.js 16.4.6 (Turbopack)
β Compiled successfully in 1562ms
Running TypeScript ...
Finished TypeScript in 803ms ...
β Generating static pages using 5 workers (4/4) in 220ms
Route (app)
β β /
β β /_not-found
β (Static) prerendered as static content"Compiled successfully" means the code compiled, and the lines about TypeScript mean the types agree. The Route table lists the pages: / is the home page, /_not-found is the 404 error page added by Next.js, and the circle means a page prepared in advance. The build does not run the linter, though, so errors caught by ESLint pass through it unnoticed. Lint is a separate command, npm run lint, which with clean code prints nothing but its own name. From today you ask for both checks after every bigger change.
The page in the browser and Fast Refresh
You start the development server yourself, in a second terminal in Cursor (Control+Shift+` on a Mac, Ctrl+Shift+` on Windows and Linux). Captain's advice: it is more convenient this way, because the server runs until you stop it, and you want its messages in front of your eyes. In the krakens-call folder type npm run dev and wait for this result:
β² Next.js 16.4.6 (Turbopack)
- Local: http://localhost:3000
- Network: http://192.168.1.10:3000
β Ready in 170msOpen the address from the Local line in the browser: you will see the Next.js starter page. The Network address works only in your home network.
Now the first change in the project, in the Claude session:
Request for Claude Code:
In @app/page.tsx change the text of the h1 heading to "Ahoy, Pirates!"
and change nothing else.When Claude saves the file, look at the browser: the heading changes by itself, with no refresh. In Next.js this feature is called Fast Refresh, colloquially hot reload. In Cursor open Source Control: the change list contains only app/page.tsx, and the diff shows the old and new heading. If another file changed, Claude did more than you asked.
The wizard already made the first commit, so this will be the second entry in the logbook. Tell Claude "Make a commit describing this change" and read the commands before you agree, just like in lesson 0_6.
Captain's review
Before you consider the ship launched, check four things:
- next.config.ts has no
cacheComponents: true. If it does, the wizard got different flags than you asked for. - The working directory of the session ends with
krakens-call, not withprojects. - The build result you saw with your own eyes, not only in Claude's summary.
- package.json contains only the packages from the wizard: nothing was installed without your request.
Typical agent mistakes in this task: it runs the wizard with --yes, which takes previously saved settings or the recommended ones, and the recommended ones have Cache Components on, or it sets up the project in the wrong folder, for example inside pirate_ship. You catch both in the permission request if you read the command and the directory before you click Yes.
Next step
The project stands, the page works, and the logbook has two entries. In the next lesson Claude will build the first section of the Kraken's Call page in Tailwind CSS, and you will learn to read its classes. In the editor below you will see a simple page and a layout in the App Router style.
Remember: a good order at the start of the voyage saves weeks of patching the hull.
Code for this lesson: page.tsx
// Next.js 16 App Router - Basic page structure
export default function Home() {
return (
<main className="min-h-screen p-24">
<div className="max-w-5xl mx-auto">
<h1 className="text-4xl font-bold mb-8">
Welcome to Next.js 16!
</h1>
<div className="grid grid-cols-1 md:grid-cols-2 gap-6">
<div className="border border-gray-300 p-6 rounded-lg">
<h2 className="text-2xl font-semibold mb-4">
App Router
</h2>
<p className="text-gray-600">
This is a page in the app/ folder. Each page.tsx file is a separate page.
</p>
</div>
<div className="border border-gray-300 p-6 rounded-lg">
<h2 className="text-2xl font-semibold mb-4">
Server Components
</h2>
<p className="text-gray-600">
By default, all components in App Router are Server Components.
</p>
</div>
<div className="border border-gray-300 p-6 rounded-lg">
<h2 className="text-2xl font-semibold mb-4">
TypeScript
</h2>
<p className="text-gray-600">
Next.js has built-in TypeScript support out-of-the-box.
</p>
</div>
<div className="border border-gray-300 p-6 rounded-lg">
<h2 className="text-2xl font-semibold mb-4">
Tailwind CSS
</h2>
<p className="text-gray-600">
Styling through utility classes directly in JSX.
</p>
</div>
</div>
</div>
</main>
);
}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. In which folder are pages located in Next.js App Router?
2. Which command starts the development server in Next.js?
3. What is Next.js?
4. What is the app/page.tsx file in Next.js App Router?
5. What is the app/layout.tsx file responsible for?
6. What does Fast Refresh (colloquially hot reload) mean in Next.js?
7. Which Next.js router is recommended for new projects?
Hands-on tasks in the game
- Code editor
Ask the AI in Cursor how to create a Next.js project and write the npx command you get in the commands.sh file.
- Vertical ordering
Arrange the steps after which you see Claude's change in the browser without a refresh:
- Click in order
Build the command that starts the development server:
- Vertical ordering
Arrange the steps of setting up a project with Claude Code, from request to proof:
- Horizontal ordering
Arrange the command that moves the terminal to the new project and starts Claude Code in it (left to right):
- Click in order
Build the command Claude uses to check that the project builds:
- Horizontal ordering
Arrange the parts of the local Next.js application address (left to right):
Tasks after this lesson
- QuestionQuiz: Next.js App Router
- QuestionQuiz: Development server
- Coding taskPractice: Create a Next.js Project
- Put in orderOrdering: Fast Refresh in practice
- Click in orderOrdering: Start server command
- QuestionQuiz: What is Next.js?
- Put in orderOrdering: From request to proof
- QuestionQuiz: The page.tsx file
- Put in orderOrdering: Session in the project folder
- QuestionQuiz: Application layout
- Click in orderOrdering: Build check command
- QuestionQuiz: Fast Refresh
- Put in orderOrdering: Local application address
- QuestionQuiz: App Router vs Pages Router