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…
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.
Sometimes when I edit a CSS value, like changing the font size, it doesn't get picked up. I have to build again.
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.
The heading changes size. Both rules were made.
What does the flag -rf do?
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.
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?
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.
- [0]
- Which program. Found through PATH, in /bin
- [1]
- Two flags bunched: r, go into folders; f, don't ask
- [2]
- What to remove
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.
What are some common /bin tools, their flags and what they mean? And /usr/local/bin?
- 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.
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?
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.
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?
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.
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!
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.
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) 🤯
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.
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.
But something small I forgot to ask about CSS… @theme? And @theme inline??
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.
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.
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.
- 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
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.
Yes, talk about React Server Components. They sound similar to SSR and CSR.
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.
How this site is built. The page stays on the server; the note view and all under it ship.
SSR is about when the HTML is made. Server Components are about how much code crosses to the browser.
Continue.
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.
Load it, then press Like before the line reaches the end.
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.
Code splitting? What now??
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.