What is Next.js doing with my project?

A chat over four days, kept as it went: the questions as they were asked, tidied, the answers cut down, figures put in, and what turned out wrong marked where it was said.

  1. 01How Next.js builds a site
  2. 02Edits that don't show
  3. 03What -rf does
  4. 04How flags work
  5. 05Common tools and their flags
  6. 06Fonts and next/font
  7. 07The @ in CSS
  8. 08Where the Next server is
  9. 09Next on top of Node
  10. 10@theme
  11. 11SSR, SSG and CSR
  12. 12Server Components
  13. 13Hydration
  14. 14Code splitting
Left outThe opening turn, picking up from the two chats before, and its recap.
01 · You

I'm getting interested in how Next.js builds and loads your website. There's a .next folder in my project, but I want a mental model, something that makes me understand generally what's happening. Like, yesterday I didn't realise npm run dev runs the dev script, which was "next dev", meaning run the Next server. That's why there's a Next logo on my site on the dev server. I want to know the nuts and bolts! But I don't know exactly what to ask. Then there's CSS being bundled and served, blah blah…

Claude

Two times. At build time, before anyone visits, Next.js turns your project into what a browser can load: TypeScript into JavaScript, CSS through Tailwind, hundreds of files bundled by a , Turbopack or webpack, into a few , each with a hashed name so a browser knows when it changed. At request time, a browser asks for a page; Next.js works out which page, makes or fetches its HTML, and sends it with links to the chunks and CSS it needs. Then React in the browser brings it to life.

.next is the output of all that: static/ for what the browser loads, server/ for what runs on the server, cache/ for what's already compiled. You never edit it; it's rebuilt.

02 · You

Sometimes when I edit a CSS value, like changing the font size, it doesn't get picked up. I have to build again.

Claude

Usually one of two things. Tailwind didn't see it. Tailwind only makes CSS for class names it finds written out whole in your source; build one from pieces, "text-" + size, and it never sees the finished name, so the rule is never generated. The cache is stale. Next.js keeps compiled output in .next to rebuild fast, and it can fall out of step. Stop the server, rm -rf .next, start again, and everything compiles fresh.

Fig 01

The heading changes size. Both rules were made.

Tailwind reads the source as text. A class name it can't find whole gets no CSS.
03 · You

What does the flag -rf do?

Claude

Two flags at once. -r, recursive: go into the folder and delete everything inside (without it, rm won't delete folders). -f, force: don't ask, and don't complain if it isn't there. There's no bin to fish things out of, so read the path twice.

04 · You

How do these flags work? 🤔 I know rm is a command-line tool, like ls or claude. But how does a flag change how the tool works?

Claude

The doesn't know what -rf means. It splits the line into words and hands the list to the program as its : rm, -rf, .next. Then rm's own code checks: did I get an r? an f? Whoever wrote rm chose what each letter means.

Fig 02
[0]
Which program. Found through PATH, in /bin
[1]
Two flags bunched: r, go into folders; f, don't ask
[2]
What to remove
Pick a command. The shell only splits it into words; what each word means is up to the program.

The rest is convention most tools keep. Single letters after one dash can be bunched, so -rf is -r -f. Most have a long form for scripts, --recursive.

05 · You

What are some common /bin tools, their flags and what they mean? And /usr/local/bin?

Claude
  • In /bin: ls -la (long list, hidden files too), rm -r, cp -r, mv (which also renames), mkdir -p (nested folders in one go), cat, echo.
  • In /usr/bin: grep -rin (search text: in folders, ignoring case, with line numbers), find . -name "*.css", curl -o (save what it fetched), which (where a command lives).
  • What you installed: git status, git log --oneline, npm install -g, npm run dev, brew install, brew doctor.

The pattern holds across them: short flags, bunched; long forms; the target last. man rm or rm --help lists what a tool accepts.

06 · You

On to the next. I think there's a bit of CSS involved, but I get confused how fonts work nowadays. And I hear there's a next/font, something like that. Can you break down the nuts and bolts and how they connect?

Claude

A font on the web is a file, usually .woff2. The old way to use Google Fonts was a <link> to Google: the browser fetched a stylesheet from Google, which sent it back to Google for the font file, while the text showed in a fallback font and then jumped when the real one arrived.

next/font moves that to build time. It takes the font files, from Google or your own project, serves them from your site, writes the @font-face rules itself, and sizes the fallback font to take up the same room, so the swap barely moves anything. The visitor's browser never talks to Google. You apply the class or variable it gives you to <html>, and everything inherits.

07 · You

Yes. What the hell is @font-face? I've seen @media… this @ symbol. What does it tell CSS to do? What are the nuts and bolts?

Claude

A rule starting with @ is an : not a style for an element, but an instruction to the browser's CSS engine. @font-face registers a font: when anything asks for this family, here's the file, like adding a contact before you call it. @media applies what's inside only when a condition holds, such as a narrow screen. @import fetches more CSS; @keyframes names an animation. An engine skips at-rules it doesn't know, which is how new ones arrive without breaking old browsers.

08 · You

Then another question. Where is the Next server when you do npm run? We've talked about Bun and Node, which are installed globally. I didn't install a Next dev server!

Claude

It's in your project. npm install read package.json and put Next.js in node_modules/next, beside React. When npm runs a script it puts the project's node_modules/.bin at the front of , so the word next in next dev is found there. So every project carries its own Next, at its own version, and two never fight.

Node runs Next. Next runs your code.

09 · You

Ahhh, Next.js is the framework on top of Node! We said the JavaScript engine is C++, and there's a layer on top for file handling, networking and so on, also C++, and we compared that to Bun's, which is Zig. So Next.js takes Node's layer and makes its own framework. So every project has a Node server, but Next-customised (the Next.js framework) 🤯

Claude

Exactly. Your code, then Next.js, a in JavaScript that routes, renders and bundles; then Node, its C++ layer for files, network and the HTTP server; then V8, which runs the JavaScript. Each layer only talks to the one below. Bun is the same shape in different materials, Zig and JavaScriptCore, which is why Next.js can run on it. So a Next.js project is a small web server from Node, with a request handler from Next, serving your pages.

You

Damnn!! That mental model is solid now. I have a better understanding of what Next.js is 😭 Now we can go down rabbit holes, starting with SSR vs SSG vs CSR.

10 · You

But something small I forgot to ask about CSS… @theme? And @theme inline??

Claude

Tailwind 4's, not the browser's: read at build time and never sent. The variables inside @theme are your design tokens, and Tailwind makes its classes from them, so --color-primary there is why bg-primary exists. Tailwind 3 kept the same tokens in a JavaScript config file.

@theme inline makes the class use the value instead of a reference to the variable. That answer said it exists so Tailwind won't fight next/font over the font variables.

11 · You

I have an idea of each, but with this new knowledge I want to relearn them. Those words are confusing too, SSR and the rest. So I'd like to know what part of rendering makes it SSR or SSG or CSR! Let's debunk.

Claude

Rendering is turning your components into HTML. <h1>Hello {user.name}</h1> isn't HTML until something runs it. The letters only say who runs it, and when.

  • CSR, client-side: the browser, on every visit. The server sends a nearly empty page and the JavaScript; the content appears when that has run.
  • SSR, server-side: the server, on every visit. The page arrives with its content, made fresh.
  • SSG, static generation: the build, once. Every visitor gets the same finished file, as fast as a file can be sent, frozen until the next build.
Fig 03
First thing on screen
The whole page, made before anyone asked
Data is fresh
Only at the next build
On this site
Every note and the home page
Pick one and follow a page from the build to the screen. Ink is where the HTML is made.

And Next.js lets each page be different: the cook who makes everything in the morning, the one who cooks when you order, and the table where you cook it yourself, in one restaurant.

12 · You

Yes, talk about React Server Components. They sound similar to SSR and CSR.

Claude

They blur the two on purpose. Server rendering had a catch: the page arrived made, then the JavaScript for every component on it followed anyway, even a footer that never does anything. So React split components in two. A , the default in the App Router, runs only on the server; its code never reaches the browser, so it can read a database directly, and it can't hold state or answer a click. A starts with "use client"; it's rendered on the server for the first HTML too, then its code is sent.

"use client" draws a line: everything that file imports and renders crosses to the browser with it.

Fig 04

How this site is built. The page stays on the server; the note view and all under it ship.

Move the line. Ink ships JavaScript to the browser; outlined parts arrive as HTML only.

SSR is about when the HTML is made. Server Components are about how much code crosses to the browser.

13 · You

Continue.

Claude

Server-made HTML looks finished and does nothing: a photograph of the page. is React taking it over. Once its JavaScript has loaded, it runs the client components, matches what they produce against the HTML already there, and attaches the event handlers. It doesn't draw the page again.

Fig 05
Nothing yet

Load it, then press Like before the line reaches the end.

Load the page and press the button straight away. The JavaScript is slowed down so the gap can be seen.

The rule that bites: the browser's first pass has to match the server's. The time, Math.random() or window, which a server doesn't have, break the match, and React reports a hydration error. useEffect only runs in the browser after hydration, so the browser-only part goes there. Server Components don't hydrate at all: they sent no code.

14 · You

Code splitting? What now??

Claude

You've met it already. Next.js doesn't send one file of the whole app; it splits the code into chunks, and a page asks only for those it uses. Each route is its own chunk; code shared by many pages, React among it, is one every page reuses. Because the names come from the contents, the browser keeps the shared ones between pages and visits.

A component can be split off further with next/dynamic, so a heavy chart's code only downloads when someone opens it.

Terms