Next.js turns your code into pages at two times

What does Next.js do with your code? It is a program inside your project, run by Node. It turns your code into pages at two times, build and request, and decides for each page where its HTML is made and how much of its code reaches the browser.

  1. 01The question
  2. 02Where the Next server is
  3. 03Two times: build and request
  4. 04Who makes the HTML, and when
  5. 05Server Components
  6. 06Hydration
  7. 07Code splitting

01The question

npm run dev doesn't do anything itself. It runs the dev script in package.json, and that script is next dev. So a Next server is running while you work, and its round N sits in the corner of the page. Between the files in the project and the page in the browser there is a .next folder, CSS that gets bundled and served, and for most people no clear picture of any of it. What is Next.js doing with your code?

Three things, in order. It is a program in your project, run by Node. It works at two times: once when you build, and again when a browser asks. And for each page it decides who makes the HTML and how much code the browser has to download. This picks up from Your shell finds a tool by searching folders in order, on how the shell finds a tool, and Bun is one file that does every job, on what Node and Bun are.

02Where the Next server is

Node and Bun are installed for the whole machine. Next.js isn't installed anywhere you'd look. It is in the project: npm install read package.json and put Next into node_modules/next, beside React and everything else the project lists.

npm run finds it with the trick from Typing a name. While a script runs, it puts the project's node_modules/.bin at the front of , so the word next in next dev is found there first. In a project that uses pnpm, node_modules/.bin/next is a short shell script pnpm wrote, and its last line runs node on Next's own starting file. So every project carries its own Next, at its own version, and two projects never fight over one.

Then the layers stack. Your pages are code Next.js calls. Next.js is a , a JavaScript program that decides when your code runs: it routes requests, renders pages, bundles files. Next.js runs on Node, the from Bun is one file that does every job: V8 to execute the JavaScript, and a harness in C++ for files, network and the HTTP server. Next doesn't rebuild Node's layer. It uses it, the way your pages use Next. Bun can mostly sit in Node's place, because it copies Node's harness.

Fig 01

Node is V8 with a harness round it. Each tool is a function your code can call that does the touching for it, and Next.js is JavaScript that calls them.

A runtime is an engine and its tools. Take the harness away, or change the engine behind it.

Node runs Next, and Next runs your code. The dev server is a Node program that lives in the project's own folder.

Running locally, that is one Node process answering every request. Deployed on Vercel it isn't one server at all: pages made ahead of time are files on a CDN, and what runs per request runs as functions, as Vercel and serverless functions describes.

03Two times: build and request

Next.js works at two times. At build time, before anyone visits, it turns the project into what a browser and a server can use. At request time, when a browser asks for a page, it answers with HTML and the files that page needs.

The build is mostly a 's work, here Turbopack. TypeScript becomes JavaScript. Hundreds of source files become a few . The CSS runs through Tailwind into a couple of files. Every file gets a name made from its contents, so a browser can keep a copy for ever and still notice when it changes. It all goes into .next, which is output, never edited, and safe to delete. The site you are reading builds into 15 JavaScript and CSS files in .next/static/chunks, its fonts in .next/static/media, and an HTML file for every page that could be made ahead, in .next/server/app.

next dev doesn't build everything first. It compiles a route the first time you open it, which is why the first visit to a page is slow and the second isn't. While you work, swaps the changed code into the open page without a reload.

04Who makes the HTML, and when

Rendering is turning components into HTML. <h1>Hello {user.name}</h1> is not HTML until something runs it. SSR, SSG and CSR are three answers to who runs it and when, and that's all the letters mean.

  • CSR, client-side rendering: the browser does it, on every visit. The server sends a nearly empty page and the JavaScript, and the content appears when that has run.
  • SSR, server-side rendering: the server does it, on every visit. The page arrives with its content, made fresh for that request.
  • SSG, static site generation: the build does it, once. Every visitor gets the same finished file, as fast as a file can be sent, and nothing new appears until the next build.
Fig 02
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.

In the App Router, Next.js decides per page. A page is made at build time unless it needs something only a request has, such as cookies, headers or the query in the address, and then it is made per request. A build says which each page got: on this site /notes is ○ static, each note is ● made ahead from the list generateStaticParams gives, and a 404 that can't know its address in advance is ƒ dynamic. (getServerSideProps, often seen in older examples, belongs to the Pages Router.)

05Server Components

Server rendering had a catch. The page arrived made, but then the JavaScript for every component on it followed, even a footer that would never do anything, so React in the browser could take the page over. Fast HTML, and still the whole download.

React Server Components split the components in two. A , the default in the App Router, runs only on the server or at build. Its code never reaches the browser, so it can read a database or a file directly, and it can't hold state or answer a click. A starts with "use client". It is still rendered on the server for the first HTML, then its code is sent so it can come alive in the browser.

"use client" draws a line, not a label. Everything that file imports and renders is on the browser's side of it too. Where the line sits decides how much code travels.

Fig 03

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.

Server Components don't send nothing, though. Their rendered result goes to the browser as the , with a placeholder where each client component goes and the files it needs. For this note it is .next/server/app/notes/nextjs.rsc, a few kilobytes beside the HTML, listing chunk files by name. React uses it to fit the two halves together, and Next.js fetches it alone when you move between pages.

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

06Hydration

Server-made HTML arrives looking finished and does nothing. Buttons don't press, nothing has state. is React taking it over: once the JavaScript has loaded, it runs the client components, matches what they produce against the HTML already on screen, and attaches the event handlers to the elements that are there. It doesn't draw the page again.

Fig 04
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.

Matching is the rule that bites. What the browser renders on its first pass has to be what the server rendered. Anything that differs between the two (the time, Math.random(), window, which doesn't exist on a server) breaks the match, and React reports a hydration error. The way out is useEffect, which only ever runs in the browser and only after hydration, so the first pass can agree and the browser-only part arrives a moment later.

Server Components skip all of this. They sent no code, so there is nothing to hydrate, and React only walks the client parts.

07Code splitting

The last piece is already in the folder names. The bundler doesn't make one file of the whole site: it splits the code into chunks, and a page asks only for the ones it uses. A route's own code is its own chunk. Code shared by many pages, React among it, is a chunk that every page reuses. Because each name comes from the contents, the browser keeps the shared ones between pages and between visits, and fetches only what's new.

A component can be split off further with next/dynamic, so its code loads only when it is first shown. This site does it once: its dials panel is loaded with dynamic(), and only on the dev server, so a visitor never downloads it.

Next.js builds what it can ahead, makes the rest when it is asked, and sends each page only the code that has to run in the browser.

Connected

Side threads

Questions that came up once the main idea began to hold, kept as they were asked. Each opens beside the paragraph it grew from.

Terms

Checked

What the chat had wrong or only half right, against sources. The note above already says the corrected thing.

  1. The Next.js logo on the dev server is Next's own welcome page, served from node_modules.The round N in the corner is the dev indicator, shown only by next dev. The starter welcome page is a page.tsx in your own project, written by create-next-app.Next.js docs, devIndicators
  2. rm -rf / deletes your entire operating system.rm on a Mac refuses to remove /, and the system volume is read only. Pointed at your home folder, it would do real damage.macOS, man rm
  3. SSG puts ready-made HTML in .next/static.Prerendered pages go in .next/server/app, as an .html file and an .rsc payload each. .next/static holds the JavaScript, CSS and fonts.rogerkinoti.design's own build, 23 October 2026
  4. A page uses getServerSideProps to be server-rendered.That is the Pages Router. In the App Router a page is made at build time unless it reads request data, such as cookies or headers.Next.js docs, Caching
  5. A 'use client' component runs in the browser only.It is rendered on the server for the first HTML as well, then hydrated in the browser. The chat says so itself a message later.Next.js docs, Server and Client Components
  6. Server Components send nothing to the browser.Their code isn't sent, but their rendered result is, as the RSC payload, with placeholders and file references for the client components.Next.js docs, Server and Client Components
  7. @theme inline keeps variables off :root, so Tailwind won't fight next/font over fonts.inline makes the class use the variable's value, such as var(--font-inter), because a variable that refers to another is resolved where it is defined. It isn't about a conflict.Tailwind CSS docs, Theme variables
  8. .next/static/chunks holds framework.js, main.js and a pages folder with a file per page.That was the Pages Router built with webpack. With the App Router and Turbopack the chunks are named only by hash; this site has 15.rogerkinoti.design's own build, 23 October 2026
  9. When someone visits your site, a Node.js process in your project answers.Locally, yes. On Vercel, prerendered pages come from a CDN and the rest run as functions; no one process serves the site.Vercel docs, Functions