DEV Community: Viktor Lázár

The Page Root Was the Wrong Unit

Viktor Lázár — Fri, 22 May 2026 15:37:46 +0000

For a long time, React server rendering came with a quiet bargain. The server would give the browser HTML early, so the user would not stare at a blank page. Then, once JavaScript arrived, React would come back and take ownership of that HTML from the root down.

That sounded like an implementation detail, but it was really an architectural claim: the page is one thing. It has one root. It becomes interactive as one program.

For some pages, that is true enough. A dashboard, an editor, or a dense application shell often wants to become one connected client-side system. But the web is full of pages that are not shaped that way. A product page has a buy box, reviews, recommendations, badges, media, a map, a few accordions, maybe a carousel nobody touches. A documentation page has mostly text and a search box. A marketing page has long stretches of server-rendered content with a few points of behavior scattered through it. Hydrating all of that through the same root was convenient for the framework, not necessarily honest about the page.

This is the thread that connects React 18 selective hydration, TanStack Start deferred hydration, and @lazarv/react-server hydration islands. They are all reactions to the same old bargain. But they are not the same reaction.

Scheduling the same root

React 18 selective hydration was the first big break in the waterfall. Before it, SSR in React had an awkward sequence: gather the data, render the HTML, load the JavaScript, hydrate the tree. Each step wanted to finish for the whole app before the next one could really begin. If comments were slow, the shell waited. If the comments bundle was large, the navigation waited. If hydration was expensive, even already-visible controls could feel stuck behind unrelated work.

Suspense changed the shape of that sequence. Once the server can stream HTML through Suspense boundaries, the ready parts of the page no longer have to wait for the slow parts. Once the client can hydrate through those same boundaries, the ready JavaScript no longer has to wait for every other bundle. And once React can notice that the user clicked inside a still-dry boundary, it can move that boundary to the front of the hydration line.

That is a real shift. The comments widget can arrive late without preventing the rest of the page from becoming useful. A sidebar can hydrate after a post. A user interaction can pull a boundary forward. Hydration stops being a single uninterrupted march from the root through the entire tree.

But React did not change who owns the page. It changed how the owner schedules work.

A Suspense boundary is a scheduling unit inside one React root. It lets React stream, pause, resume, prioritize, and preserve server HTML while code is still loading. It does not mean "this part of the document is no longer React's problem." If the boundary was server-rendered as part of the app, React still expects to reconcile it eventually. If parent state or context changes in a way that makes the preserved HTML stale, React has to protect consistency. If the code arrives and the boundary matters, hydration remains part of the plan.

That is why the old React WG question about stopping hydration for part of the document is such a useful hinge. The proposed trick was to suspend a boundary forever, mostly to keep static JSX-heavy content from entering the initial client work. The answer was essentially: that is not a stable ownership boundary. Updates can still force React to inspect it, context can still matter, and you may still have downloaded the code. The real direction, React maintainers suggested, was Server Components.

That answer points at the deeper issue. The desire was not only to hydrate later. It was to stop pretending the entire document had to belong to the client root in the same way.

A gate inside the app

TanStack Start's deferred hydration lives in the space just before that deeper shift. It accepts the single-root app model, but gives the developer a way to keep certain server-rendered subtrees out of the initial hydration queue until there is a reason to admit them.

import { Hydrate } from "@tanstack/react-start";
import { visible } from "@tanstack/react-start/hydration";

export function ProductPage() {
  return (
    <Hydrate when={visible({ rootMargin: "400px" })}>
      <Reviews />
    </Hydrate>
  );
}

The important thing in this example is not that reviews become lazy. They are still in the HTML. The server still rendered them. Users can read them. Crawlers can index them. CSS can style them. What changes is that the client tree does not have to hydrate that boundary during the first pass. The boundary can wait for visibility, idle time, interaction, a media query, a condition, or it can intentionally remain static for the initial document with never().

This is more than React selective hydration. React decides the order of hydration work that exists. TanStack Start can decide whether that work should be in the initial queue at all. Its compiler can also split the boundary's children into a deferred chunk, so the browser may avoid fetching that JavaScript until the boundary is close to hydrating. That changes both CPU timing and network timing.

The subtle part is that the server HTML is not treated like a loading placeholder. It is the thing the user sees while the boundary is waiting. In TanStack Start, fallback on <Hydrate> is not the skeleton shown during initial document hydration if server HTML already exists.

<Hydrate when={visible()} fallback={<ReviewsSkeleton />}>
  <Reviews />
</Hydrate>

On the first page load, if <Reviews /> was rendered into the document, the user keeps seeing the rendered reviews. The skeleton is for a different situation: the app is already running, a boundary first appears through client-side navigation or conditional rendering, and there is no preserved server HTML for that boundary. The same prop has to serve the post-startup client world, not replace the initial server world.

That distinction gives TanStack's model its character. Deferred hydration is not "show a spinner until the component wakes up." It is "preserve the server-rendered thing until the client has a reason to own it."

Still, the root remains the root. TanStack Start is explicit about that. A deferred boundary sits inside one React tree. Parent updates can force it to hydrate earlier if correctness requires it. Nested boundaries hydrate parent-first. Context and state are still part of the surrounding app model. This is not Astro-style island composition, where separate roots are dropped into a mostly static page. It is one React application with doors that can stay closed for a while.

That is a good model when the page really is one app, but some regions are non-urgent. Reviews below the fold, recommendation carousels, media-heavy embeds, comparison tables, maps, and rarely used panels are all good candidates. They belong to the app. They should be server-rendered. They just do not need to consume startup work before the user gets anywhere near them.

A real island

The RSC version of the story starts from a more complicated default. Server Components run on the server and their component code does not become part of the client bundle, but the page can still be one React tree on the client. The static output produced by Server Components is still represented through the RSC payload and can still sit under the page root that React hydrates and reconciles. In that model, "server" does not automatically mean "outside the client React tree." It often means "rendered on the server, then represented inside the client-owned page tree."

That is already useful, because it keeps server-only code and browser code separate. But it does not, by itself, break the old root-level bargain. A static paragraph rendered by a Server Component may not ship its component implementation to the browser, but if it is part of the page root, it still belongs to the client React app's tree shape.

@lazarv/react-server pushes that further with "use hydrate" islands. A component can mark a server-rendered subtree as a hydration island:

function ReviewsIsland() {
  "use hydrate: visible; rootMargin=600px; id=reviews";

  return <Reviews />;
}

The runtime renders the island as normal server HTML, but it also writes an island-specific RSC payload and later calls React hydration for that island as its own root. That is the central point. The island is not a delayed region of a larger client tree. It is a separate React tree.

The page root does not have to be a client root just because this part of the page eventually becomes interactive. The static content above the island, below it, and around it does not participate in a React app on the client at all. It remains document HTML. There is no root-level React owner waiting to reconcile it, no page-wide hydration pass that has to account for it, and no fiction that the entire document is one client program with a few slow parts.

The page can have no client components at the root, no root RSC hydration payload, and still contain an island that wakes up later.

That is not merely deferred work. It is a true island.

With React selective hydration, a Suspense boundary inside the main root gets scheduled more intelligently. With TanStack Start deferred hydration, a subtree inside the main root waits at a gate. With an @lazarv/react-server hydration island, a new hydrate root appears inside an otherwise non-React document. Once hydrated, that island may also behave as a local outlet and use primitives such as Link local and Refresh local, but that is downstream of the more important fact: it is not owned by the page root.

This is the part that makes "use hydrate" more than a trigger syntax. The familiar strategies are there: load, idle, visible, interaction, media, and never.

function AccountMenuIsland() {
  "use hydrate: interaction; events=pointerenter,focusin; id=account_menu";

  return <AccountMenu />;
}

But the strategy is not the architecture. visible is just when the door opens. The architectural question is what is behind the door. In TanStack Start, it is a deferred part of the same app root. In @lazarv/react-server, it is a separate React hydrate root with its own payload, mounted into a document whose surrounding content is not part of the client React tree. That difference matters when you are deciding whether the page itself should become client-owned.

Fallbacks are part of the contract

It also changes how fallback should be understood. React's Suspense fallback is a rendering fallback: what should appear when content is not ready. TanStack Start's Hydrate fallback is mostly a client-mount fallback: what to show when no initial server HTML exists for a boundary that appears after the app is already running. In @lazarv/react-server hydration islands, some of the most important fallbacks are operational. If IntersectionObserver is unavailable for a visible island, hydrating immediately is safer than leaving visible UI permanently inert. If matchMedia is unavailable for a media island, eager hydration is again the better failure mode. If an interaction island wakes on the first click, you should not assume that exact click will replay into the newly hydrated component; for controls where the first click must perform the action, earlier intent events like pointerenter or focusin are better triggers.

These details are easy to treat as API trivia, but they are where the model becomes real. A user does not care that a section is governed by an elegant hydration strategy if the first click disappears. They do not care that the page saved JavaScript if a visible control never wakes up on their browser. Deferred hydration is only a performance feature when its failure modes preserve trust.

Ownership, not laziness

That is why I think the comparison has to be framed around ownership, not around laziness.

React selective hydration is not "less hydration." It is hydration with better scheduling. It keeps the single-root app model and makes it far less wasteful.

TanStack Start deferred hydration is not "Suspense but later." It is an admission gate for preserved server HTML inside one React app. It lets the app say: this part is visible now, but client ownership can wait.

@lazarv/react-server hydration islands are not just "defer this component." They are a way to keep the page root out of the client React app entirely while giving selected subtrees their own client life. That is the RSC-native answer to the discomfort behind the old forever-suspending Suspense idea.

Once you see the difference, the design question changes. It is no longer "how do we hydrate the page faster?" Sometimes the right answer is to hydrate sooner. Sometimes it is to hydrate later. Sometimes it is to stop making the page root responsible for hydration in the first place.

The better question is: which part of this page needs client ownership, and when?

If the page is an application shell, React's selective hydration is the base layer. Use Suspense boundaries, stream what is ready, code split what is heavy, and let React prioritize the interaction path.

If the page is one app with non-urgent regions, TanStack Start's deferred hydration is the sharper tool. Keep the HTML. Delay the JavaScript. Let visibility, idle time, media, condition, or intent decide when the boundary becomes interactive.

If the page is mostly server-owned with a few islands of behavior, an RSC island architecture is the cleaner shape. Do not hydrate the root just to support a filter, a menu, or a counter. Give that subtree its own hydrate root and let the surrounding document remain outside React on the client.

Hydration used to be described as the tax paid after SSR. That was always too blunt. Hydration is not one tax. It is a set of ownership decisions that happen over time. React 18 made those decisions schedulable. TanStack Start made them deferrable inside the root. @lazarv/react-server makes them separable enough that the root can sometimes stop being a client React root at all.

The page root was a useful default. It should not be the only unit we are allowed to think with.

What We Lose When Everything Is a Wrapper

Viktor Lázár — Sun, 17 May 2026 20:27:49 +0000

What a 14-year-old HTML5 Wolfenstein 3D port taught me about owning the stack

A recent Primeagen video sent me back into an old feeling: the strange discomfort of realizing how much of modern software is now built around things we do not really own.

Not in the legal sense. In the practical sense.

We install a package, which installs other packages, which wrap lower-level packages, which hide runtime behavior behind conventions, build steps, plugins, adapters, loaders, and generated code. The result works. Often it works beautifully. But there is a quiet moment, usually during debugging, where the shape of the thing becomes hard to hold in your head. You are no longer asking, "What does my program do?" You are asking, "Which layer is currently doing this on my behalf?"

That is not always a problem. Abstraction is one of the reasons software can grow at all. Nobody should rewrite a font renderer to build a settings page. Nobody should reimplement TLS because they want an API endpoint. Most dependency-free manifestos eventually collapse into a kind of performance art where the programmer is very proud, very tired, and still missing Unicode.

This is not that argument.

This is not an argument against dependencies. It is an argument for knowing when they are helping you build, and when they are quietly becoming the thing you are building around.

The Game With No Dependencies

Fourteen years ago, I ported Wolfenstein 3D to HTML5.

No engine. No framework. No package manager. No third-party runtime dependencies.

Just JavaScript, canvas, and a very specific obsession.

There was a production build step, because the web has always had its rituals. The release build went through Google's old Java-based Closure Compiler. But that was packaging, not architecture. It made the output smaller. It did not define the shape of the program.

That distinction matters. It was not a small raycasting demo inspired by Wolfenstein. It was an actual browser port of the game, built directly on the platform the browser gave me at the time. This is the same idea I was circling around in The Browser Was the Engine: for that project, the browser was not just a deployment target. It was the engine.

I am open-sourcing it now, and the thing that feels most surprising in 2026 is not that it still exists. It is that there is almost nothing underneath it that can have gone stale. There is no abandoned package to replace. No transitive dependency tree to audit. The old minifier is a historical detail, not a living dependency graph. No ecosystem era is trapped in amber around it.

It is just code.

That sounds smaller than it is. A complete game is not a toy problem. Even a simple raycasting engine needs a loop, input, collision, map parsing, rendering, textures, sprites, timing, state, audio, UI, and all the little bits of glue that turn a technical demo into something that feels like a game. You do not get to skip complexity by avoiding dependencies. You only choose where the complexity lives.

In that project, the complexity lived in the project.

That made the code less general. It was not a reusable game engine. It did not have an extension system, a plugin API, a renderer abstraction, or a roadmap. It was not trying to become a platform. It was trying to be one thing.

That narrowness was the feature.

The renderer did not need to serve every possible game. The input layer did not need to become an input library. The map representation did not need to model the universe. Every piece of the program could be shaped around the exact problem in front of it. The code had no ambition beyond the game, and because of that, the game could be completely itself.

Fourteen years later, that still matters.

This used to be much more normal. On the C64 and the Amiga, on MS-DOS machines, and especially on old consoles from Nintendo, Sega, and the rest of that era, software was often written as a direct answer to a specific machine. A game was not usually a thin layer over a general engine over a general runtime over a general abstraction of hardware. It was a peculiar little organism fitted to the memory layout, graphics modes, timing behavior, controller shape, and limits of the target. The constraints were brutal, but they made the program concrete. You could feel the machine in the code.

I do not want to pretend that era was better in every way. It was harder, narrower, less portable, and full of tricks nobody should be forced to rediscover for ordinary application work. But it had one quality that is easy to miss now: the program and the platform had an intimate relationship. The software did not float above the machine. It negotiated with it directly.

The Shelf Life of Small Surfaces

Software ages in strange ways.

Sometimes code ages because the problem changes. Sometimes it ages because the platform changes. But a huge amount of modern code ages because the stack around it moves.

The package manager changes. The bundler changes. The framework changes. The framework's compiler changes. The plugin ecosystem changes. The lockfile format changes. The version of Node you need becomes a small archaeological site. You do not just maintain the application. You maintain the ability to assemble the application.

There is a real cost hidden there.

Dependencies do not only add code. They add motion. They add release notes, security advisories, migration guides, incompatible peer ranges, deprecated APIs, and small future obligations that are easy to accept because they arrive wrapped in convenience.

That convenience is often worth it. But it is not free.

The dependency-free Wolfenstein source has a different aging profile. It depends on the browser, of course. Every web program does. The production build once depended on Closure Compiler. But the game itself does not depend on a cultural moment in the JavaScript ecosystem. The old build step can be replaced, skipped, or recreated because it was only an output step. The source does not need a 2012 toolchain to remember how to be itself. Its surface area is small enough that the future had fewer places to break it.

This is one of the underrated virtues of writing something directly: you reduce the number of external clocks your project has to keep time with.

Every dependency is a clock. Some tick slowly and responsibly. Some tick chaotically. Some stop. Some are taken over by someone else. Some are still correct but no longer fashionable. Some become infrastructure so deeply embedded that nobody remembers choosing them.

The fewer clocks you attach to a project, the longer it can sit quietly without turning into an incident.

Generality Has a Price

A dependency is usually a package of generality.

That is its value. The author solved a problem broadly enough that you can reuse the solution in a context they did not know about. A good library is a small miracle of compression: years of thought hidden behind a function call.

But generality has a shape, and that shape enters your program.

If you use a game engine, your game starts to inherit the engine's idea of a game. If you use a framework, your application inherits the framework's idea of an application. If you use a router, a state manager, an ORM, a component library, a testing framework, and a build system, your program becomes partly an expression of all their assumptions.

Again, this can be good. Shared assumptions are how teams move. Conventions are how projects become legible. A framework can save you from wasting your life on plumbing that has nothing to do with the thing you are trying to build.

But every general-purpose layer also asks you to pay for cases that are not yours.

Sometimes you pay in bytes. Sometimes in indirection. Sometimes in concepts. Sometimes in the strange helplessness of reading code that looks simple while knowing that the real behavior lives somewhere else.

This is the wrapper feeling.

Not abstraction itself. Abstraction is a tool. The wrapper feeling is what happens when the abstraction no longer disappears. It stays visible. It stands between you and the material. You can feel yourself programming the wrapper's model of the problem instead of the problem.

At that point, the dependency may still be doing useful work, but it has also become a design constraint. You are building with it, but you are also building around it.

The Good Kind of Dependency

I should be careful here, because I build dependencies too.

I work on react-server. At Level 0x40 Labs, I build open-source tools and primitives, including things like virtual-frame. Some of my work is explicitly about making reusable layers for other programs. I care about composable runtimes, shared primitives, and the boring miracle of code that lets other code exist more easily.

So no, I do not believe the purest program is the one that imports nothing.

The good dependency does something more interesting than save keystrokes. It gives you a stable primitive. It makes a hard boundary understandable. It removes accidental complexity without stealing the shape of the thing you are building.

The best dependencies feel less like wrappers and more like materials.

Canvas is a material. SQLite is a material. A focused parser can be a material. A well-designed runtime primitive can be a material. You can build with them while still feeling that the program is yours.

The dangerous dependency is different. It does not merely provide capability. It brings a worldview. It decides the architecture, the vocabulary, the lifecycle, the extension points, the error model, the deployment model, and the kinds of solutions that feel natural. You can still build something good inside it, but you are no longer only building your thing. You are also participating in its theory of software.

That may be exactly what you want.

If I am building a product with a team, I want shared machinery. I want boring defaults. I want the dependency graph to absorb problems that are not central to the product. I want the project to move because not every layer deserves to be handmade.

But if I am building the core mechanic of a game, or the central abstraction of a runtime, or the part of a system that defines what the system is, I want a different relationship to the code.

I want ownership.

Ownership Is a Design Constraint

Ownership is not the same as authorship.

You can write every line of a program and still not own it, because the design is copied from a framework you are no longer using. You can also depend on a library and still own your system, because the boundary is clear and the library is just a tool in your hand.

Ownership means you understand the important consequences of the system's shape.

You know where time is spent. You know where state lives. You know what happens when input arrives. You know which layer can fail and how failure moves. You know the constraints because you chose them, or at least because you have looked at them directly enough to accept them.

This is what dependency-heavy development can erode. Not skill in the macho sense. Not the ability to write a linked list on a whiteboard. Something more practical: the habit of tracing behavior all the way down until the system becomes concrete again.

When everything is a wrapper, the bottom keeps moving away.

You learn the public API. Then the plugin API. Then the framework convention. Then the generated output. Then the bundler behavior. Then the runtime behavior. Every layer may be reasonable on its own, but the stack as a whole can become a place where nobody quite knows what is happening. The program works because the ecosystem works. Until it does not.

The cost is not only reliability. It is imagination.

If you only build inside other people's abstractions, you start to think in the shapes they make convenient. Your ideas arrive pre-filtered by the tools. You ask, "How do I do this in this framework?" before you ask, "What is this thing, actually?"

That question matters.

The New Game

The game I am working on now also uses no third-party code.

Not because I have become allergic to packages. Not because I think every line must be sacredly handcrafted. It is simpler than that: the game has a specific shape, and a purpose-built implementation fits that shape better than a general engine would.

A game engine would give me a thousand solved problems. Some of those solutions would be useful. Some would be irrelevant. Some would slowly bend the game toward the engine's strengths. I would move faster at the beginning, and then spend part of that saved time negotiating with decisions made for other games.

For this project, that trade does not feel right.

I want the renderer to know exactly what this game is. I want the update loop to carry exactly the concepts the game needs. I want the asset pipeline, the state model, and the interaction rules to be small enough that they can stay in my head. I want the implementation to be shaped by the game, not by the possibility space of all games.

That is not a universal recommendation. It is a local one.

The mistake is treating dependency decisions as identity. Dependency-free does not mean serious. Dependency-heavy does not mean sloppy. The useful question is always more specific:

What part of this system needs to be mine?

Choosing the Layer

There are layers where depending on other people is a sign of maturity.

Cryptography. Databases. Protocol implementations. Image codecs. Font shaping. Accessibility primitives. Hard-won platform knowledge that would be arrogant or irresponsible to casually recreate.

There are layers where depending on other people is mostly a business decision.

Admin UI, routing, deployment glue, test runners, analytics, documentation tooling, forms, dashboards, the parts of a product whose correctness matters but whose originality does not.

And there are layers where depending too early can cost you the thing you are trying to discover.

The core interaction of a game. The execution model of a runtime. The data model of a creative tool. The editor behavior of a text surface. The small strange thing that made the project worth building in the first place.

Those layers deserve suspicion. Not because dependencies are bad, but because premature generality can erase the local shape before you have understood it.

Sometimes the right move is to build the first version directly. Learn the material. Discover the constraints. Let the project teach you what abstractions it actually wants. Then, if a dependency fits, you will know where it fits. You will be choosing it from knowledge rather than reaching for it from reflex.

That difference is everything.

The Muscle

The reason I still care about from-scratch projects is not nostalgia.

It is maintenance of a muscle.

The muscle is the ability to look at a problem without immediately asking which package owns it. The ability to draw the smaller machine inside the larger machine. The ability to build a narrow implementation without apologizing for its lack of generality. The ability to recognize when a dependency is a material, when it is a tool, and when it is slowly becoming the architecture.

Modern software needs dependencies. It also needs people who remember what the layers are made of.

That is what the old Wolfenstein project gives me now. It is not impressive because it avoided packages. It is not morally superior because the dependency list is empty. It is useful because it is a reminder that a complete thing can still be built as a complete thing.

No engine. No framework. No package graph.

A game.

That possibility is worth keeping alive.

Not for every project. Not for every layer. Not as a purity test.

Because sometimes the only way to know what you are building is to build enough of it yourself that it can answer back.

The Browser Was the Engine

Viktor Lázár — Sun, 17 May 2026 19:57:20 +0000

How a Wolfenstein 3D HTML5 port worked in April-May 2012

In April-May 2012, I ported Wolfenstein 3D to HTML5. The port is still available at wolf3d.wadcmd.com.

Not as a small raycasting demo. Not as a framework exercise. Not as a canvas toy that borrowed the feeling of the original. It was a browser port built from the platform that existed at the time: JavaScript, HTML, CSS, Canvas, XHR, audio elements, a little localStorage, and the patience to make those parts behave like a game.

There was no engine underneath it.

That sentence sounds simple now, but it is the most important architectural fact about the project. No game engine meant there was no inherited world model. No package manager meant there was no dependency graph quietly deciding what the program wanted to become. No framework meant there was no lifecycle to adapt to, no plugin interface to satisfy, no build-time abstraction standing between the game and the browser.

The browser was the engine.

That did not make the implementation easier. A complete game does not become simple because you avoid dependencies. You still need a renderer, resource loading, maps, collision, enemies, animation, input, sound, save games, menus, HUD, transitions, and timing. The complexity does not disappear. It moves closer.

In this port, that was the point. Every piece of the implementation could be shaped around one problem: make Wolfenstein 3D run in the browser that existed in 2012.

Internet Explorer 9 mattered. Chrome and Firefox mattered. Current browsers still run it today, but the architecture was formed by the constraints of that earlier browser landscape. Canvas 2D was the stable rendering target. Audio was fragmented. JavaScript engines were fast, but not generous enough to waste work casually. WebGL could not be the foundation if the goal was broad compatibility. The project had to be static, direct, and careful.

So it became a game made of ordinary browser parts.

Before Browser Ports Felt Normal

It is easy to forget how unusual this felt at the time.

Today, seeing an old game run in a browser is not surprising. We have WebAssembly, mature WebGL, better audio APIs, faster JavaScript engines, and a decade of examples proving that the browser can host serious ports. In 2012, that expectation was not really there yet.

Classic game ports to the browser were not a common thing in my memory. I remember a great Lemmings port from that period, but not a long list of comparable projects. The browser was becoming capable, but the idea that you could take the structure of an old game and make it feel at home in HTML5 still had a little bit of improbability around it.

That was part of the attraction.

The question was not only "can I draw a raycaster?" The question was whether the browser could carry the whole feeling of a game: the menus, the timing, the input, the sound, the little transitions, the data loading, the save slots, the sense that you were not looking at a web demo but playing something complete.

That question stayed with me after this port. Since then I have also ported DOOM and Another World, partially ported other smaller games, and I have been occasionally working for years on a Morrowind game port. The projects are different, but the underlying fascination is the same: what does it take to move an existing game into the browser without losing the thing that made it feel like itself?

Wolfenstein 3D was the project where I first answered that question seriously.

Static Files as an Architecture

The entry point is just index.html.

It loads a stylesheet and then a list of JavaScript files with script tags. The order of those tags is the dependency graph. There is no module loader to explain, no bundler contract, no runtime manifest. The files appear in the page in the order the program needs them.

That may look old-fashioned now, but it was also liberating. The deployment model was almost impossible to simplify further: serve the folder and open the page. The application did not need a server-side process to define itself. It did not need a compilation step before it could be understood. A browser could load it because the browser already knew the primitives it was made from.

The code is organized around global subsystem objects: game, raycast, maps, resources, player, ai, audio, controller, and a few smaller systems around animation, doors, secrets, scripts, fonts, and menus. Each file adds a part to the whole.

The pattern is plain:

game.extend({
    newGame: function(map, difficulty, speed, callback){
        ...
    }
});

Today, we would usually reach for imports. In 2012, for a static browser game targeting IE9, this was the smallest reliable module system available: objects, files, and load order. It was not elegant in the modern packaging sense, but it was concrete. You could read the HTML and know what the program was made of.

That concreteness shows up everywhere else.

Screens are not generated by a UI framework. They are small HTML fragments under html/. When the game needs the menu, the difficulty screen, the game view, the high score table, the sound settings, or a message dialog, it loads the fragment with XMLHttpRequest, puts it into the document, converts its text into the game’s bitmap-style text, and fades it in.

The game shell is therefore static, but not monolithic. It is a set of browser-native pieces, loaded only when the game asks for them.

That is the kind of architecture that comes from trusting the platform directly. There is no router. There is no component tree. There is no templating runtime. There is an HTML file, a request, a DOM node, and a screen.

The View Is Layered, Not Abstracted

The game screen is a stack of canvases and DOM elements.

At the back there is a canvas for the background. Above it there is the main view, where the raycaster draws walls and sprites. Above that is the weapon hand. Another canvas handles the fizzle-fade mask. A transparent control layer catches touch and mouse input. The HUD sits at the front with small canvases for score, floor, lives, face, health, ammo, keys, and weapon state.

This is not a general renderer. It is a layout for this game.

The separation matters because not every part of the screen changes for the same reason. The 3D view changes every frame. The HUD changes when a value changes. The weapon canvas changes when the weapon animation advances. The mask changes during transitions. By giving those concerns their own surfaces, the code avoids pretending that the whole screen is one thing.

That is a recurring theme in the port. There are abstractions, but they are local. They exist where the game has repeated behavior, not where a future engine might want an extension point.

The raycaster does not know about menus. The HUD does not know about wall rendering. The mask does not know about enemies. The DOM can still be used for layout where layout is the problem, and Canvas can be used where pixels are the problem.

This was one of the advantages of writing directly against the browser. The browser already had multiple materials. HTML was good for screens and menus. CSS was good for layering and transitions. Canvas was good for the game view. There was no need to force all of it through one abstraction.

Turning Images Into Game Data

The resource loader is small but important.

Wolfenstein-style rendering wants textures in predictable square cells. The port uses sprite sheets for walls and objects, then cuts them into 128-by-128 images at load time. An offscreen canvas draws one cell from the sheet, turns it into a data URL, and stores it in a lookup table.

After that, the renderer can ask for things in the shape it needs:

resources.walls[textureIndex][side]
resources.sprites[itemIndex][frameIndex]

That preprocessing step keeps the inner loop simple. The renderer does not want to think about sprite sheet layout every time it draws a wall column. It wants a texture image, a texture coordinate, and a destination column.

This is one of those small decisions that tells you what kind of program it is. The code does not build a generic asset pipeline. It prepares the assets into the exact form the renderer wants. Work that can happen once at startup is moved out of the frame loop. The frame loop stays narrow.

Again, the implementation is direct: generate the pixels, cache the pixels, put the pixels on screen.

Bitmap Font Rendering

The text rendering deserves its own place because it is one of those details that makes the port feel like a game instead of a web page.

The menus and HUD could not simply use browser fonts. A browser font would have been easy, but it would also have been wrong in a very visible way. Font rendering differed between platforms, antialiasing differed between browsers, and the original game had a very specific bitmap character. If the menus used normal DOM text, the illusion would break before the player even reached the first level.

So the port renders text as images.

There are two paths in the font system. font.BitmapFont uses a bitmap image that contains glyphs laid out horizontally. A small map tells the renderer where each character begins and how wide it is. When text is needed, the font renderer draws the matching glyph slices into an offscreen canvas, then turns that canvas into a data URL and inserts it into the DOM as an image.

The other path, font.Font, is even more direct. The small and large menu fonts are stored as compact bitmap data in JavaScript. Each glyph is a set of integer rows. Rendering a character means walking those bits, painting colored pixels into an ImageData buffer, and writing the result to the offscreen canvas.

That gives the code several useful properties.

Text can be colored without needing separate image files for every color. The same glyph data can become grey menu text, selected menu text, disabled text, read-this text, or high score text. It also means the game can process ordinary HTML fragments after loading them. A screen can contain readable text in the source, and game.processFont() replaces that text with generated bitmap images when the screen enters the game.

The renderer also caches the result by font and text value. Once a phrase has been turned into pixels, the same generated image can be reused. That matters because menus redraw and update, but the words themselves usually do not change. The port pays the text-rendering cost when it has to, not every frame.

It is a small system, but it captures the spirit of the whole port. The browser is still doing the work. There is still no external text rendering library. But the program refuses to let the browser's default presentation leak into the game. It takes the platform primitive, Canvas, and uses it to produce the exact kind of pixels the game needs.

Getting the Game Data Into Browser Shape

The browser port also needed the original game data in a form the JavaScript runtime could use.

That part did not happen by hand. The assets were converted from a Wolfenstein 3D editor format using a custom C# converter utility. The converter extracted the images and maps and turned them into browser-friendly files: PNG sprite sheets and JavaScript map data that the static app could load directly.

This was an important part of keeping the runtime simple. The browser code did not need to understand the original game data formats. It did not need a binary parser for every source file. It did not need to do expensive conversion work during startup. By the time the browser saw the assets, they were already shaped for the port.

Images became image files the browser could load normally. Wall textures and sprites became sheets the resource loader could slice into 128-by-128 cells. Maps became JavaScript files that populated wolf3d.maps, which meant a level could be loaded with a simple XHR request and evaluated into the same data structures the engine already expected.

That split made the architecture cleaner. The C# converter was an offline tool. The browser runtime was the game. The conversion step absorbed the awkwardness of extraction, while the game stayed static and dependency-free.

The open-source repository intentionally does not include those extracted game assets. The point of mentioning the converter is architectural: the port was not loading original game files directly in the browser. It used an offline conversion step to transform the data into web-native assets, then kept the runtime focused on playing the game.

The Raycaster at the Center

The heart of the port is the raycaster.

Wolfenstein 3D is built on a grid. The world is not arbitrary polygons. It is cells: empty space, walls, doors, secrets, objects, enemies. That makes it a perfect fit for a column renderer. For every vertical column of the screen, the engine casts a ray from the player into the grid, walks cell by cell until it hits something solid, computes the distance, and draws one vertical slice of texture.

The camera is just two vectors: the direction the player is facing, and the camera plane used to spread rays across the screen.

var cameraX = 2 * x / width - 1;
var rayDirectionX = player.direction.x + player.plane.x * cameraX;
var rayDirectionY = player.direction.y + player.plane.y * cameraX;

That is the beautiful thing about this kind of renderer. Once the math is in place, the world becomes very cheap to describe. A wall is a number in a map array. A ray walks the array. A texture slice becomes a one-pixel crop stretched vertically with drawImage().

The renderer does this hundreds of times per frame, once per screen column. It also records the distance of each wall hit in a z-buffer. That z-buffer becomes the truth for everything drawn after the walls. Sprites are projected into screen space, sorted from far to near, and each visible stripe is tested against the wall distance for that column.

This is how enemies disappear behind walls. It is also how weapons know what they are aiming at.

When an enemy sprite is visible in a column, the renderer stores that enemy in the player’s fireBuffer for that stripe. A hitscan weapon does not need a separate picking engine. It looks near the center of the screen, checks the same visibility information the renderer already computed, and damages the first visible target.

That reuse is one of my favorite parts of the implementation. The renderer is not only drawing. It is producing spatial knowledge. The weapon system uses that knowledge instead of inventing a parallel world.

Doors Are Not Walls

In a simple raycaster, a wall is just the first solid cell the ray hits.

Wolfenstein doors complicate that. A door is visually inside a grid cell, but it slides open. It can be partly open, fully open, closing, blocked by the player, blocked by an enemy, or locked behind a key. Treating it as a normal wall would be too crude.

The port gives doors their own state: position, texture, slide amount, action, delay, and optional key. During raycasting, doors encountered before the final wall hit are kept in a buffer. If a door is closer than the wall and its slide amount still blocks the ray, the renderer draws the visible door slice and writes that distance into the z-buffer.

The door has not moved through the map. Its texture has moved inside the cell.

Secret walls are the opposite. They really move through the map. When pushed, the starting cell becomes empty. The secret wall advances by a fractional state until it crosses into the next cell, then continues until it has moved two cells or is blocked. The map keeps separate secret-wall state so collision and rendering can both understand the wall while it is in motion.

This is where a lot of game code lives: not in grand abstractions, but in the difference between two things that look similar until you implement them. A door and a secret wall are both moving obstructions. Architecturally, they are not the same thing at all.

The implementation lets them be different.

The Main Loop Is a Set of Small Clocks

The game loop is driven by requestAnimationFrame, with vendor-prefixed fallbacks and finally setTimeout. The target tick is roughly 33 updates per second. Each frame calculates how much time has passed and turns that into a capped timeFactor.

The cap matters. If the browser stalls for a moment, the game should not respond by letting a guard sprint through the map or a door jump through its entire animation. Time compensation is useful only until it becomes a bug.

Inside the frame, the code updates the world in a straightforward order. Doors process. Secret walls process. Animations process. AI processes. One-frame script events are cleared. Positional audio events are played at a volume based on distance. Controls are processed. The player HUD updates. The raycaster renders.

There is no big scheduler.

There are arrays:

doors.process
secret.process
animation.process
ai.process
audio.process

If a door is moving, it is in doors.process. If an animation is active, it is in animation.process. If a sound should be played from a map position, it is queued in audio.process until the frame loop turns distance into volume.

This is the kind of simplicity that is easy to underestimate. A more general engine might have a unified entity lifecycle. This port does not need one. A door is not an enemy. A sound event is not a sprite. An animation is not a map script. Each small system gets the loop it needs.

That does not make the game less complete. It makes the completeness local.

Enemies Are Sprites With Intent

The enemy system starts from sprites and adds intent.

An enemy has a position, a texture resource, an animation set, hit points, a direction, a current action, and a process method. The current action is just a function reference: ready, moving, attack, fire, dying, dead, or a specialized behavior for a boss or projectile.

That turns each enemy into a small state machine.

The shared base handles the things every enemy needs: calculating which sprite direction should face the player, testing line of sight, choosing movement directions, walking through the grid, opening doors, taking damage, and advancing the current action.

The visibility check is not magic. It walks a line through the grid between enemy and player. If a wall or a closed door blocks the line, the player is not visible. If the enemy sees the player, or hears activity in the same floor area, it can wake up and begin attacking.

Movement is similarly local. Enemies choose chase, dodge, or run directions from nearby cells. They avoid blocked tiles, avoid reversing direction when appropriate, consider doors, and use a bit of randomness. It is not a general pathfinding library. It is the kind of movement model a Wolfenstein 3D enemy needs.

That is the point. The AI code is not trying to be generally intelligent. It is trying to create the pressure the game needs: guards noticing you, moving through corridors, opening doors, firing when visible, reacting to damage, and becoming part of the scene the raycaster knows how to draw.

The enemy is both a visual thing and a behavioral thing. It is a sprite with intent.

Input Is State, Not Events

Keyboard input is translated into game actions and stored as active or inactive key state.

That distinction matters because games do not usually want to respond to a key event once. They want to know what is currently true. Is the player holding forward? Is run active? Is strafe active? Was fire released? Should left/right mean rotation, or should they mean strafing because Alt is down?

The controller maps key codes to named actions, then the game loop processes those actions. Some actions are continuous. Some are single-fire. Some cancel each other. Some have release behavior.

Touch input uses the same idea. The game view contains a transparent table of control regions. Entering or touching a region activates actions like forward, left, right, or combinations. The input surface is crude, but it has one important property: it feeds the same controller state as the keyboard.

The rest of the game does not need to care where the input came from.

That is the right kind of abstraction. It does not invent a framework. It simply normalizes the one fact the game needs: which actions are active right now.

Audio Had to Be Pragmatic

Browser audio in 2012 was not one clean API.

The port uses WebKit AudioContext when it is available. In that path, sound effects are requested as array buffers and decoded into audio buffers. If that API is not available, the code falls back to HTML audio elements and checks whether the browser can play MP4 or OGG.

Music is handled as a looping audio element with multiple sources. Sound effects are loaded lazily and cached. Positional sound is deliberately simple: game systems queue a sound with map coordinates, and the main loop compares that position to the player. The farther away the event is, the lower the volume.

That is enough.

The game does not need a full audio engine. It needs doors to sound like they are nearby or far away. It needs enemies to make noise from their position. It needs music to loop. It needs guns, pickups, doors, secrets, and death sounds to happen at the right time.

The implementation solves exactly that.

State Lives in the Browser

A static game still needs persistence.

The port uses localStorage for settings, controls, graphics detail, sound volume, music volume, save slots, highscores, and zoom state. Save games serialize enough information to reconstruct the level: map name, difficulty, player position and direction, health, ammo, lives, score, keys, weapons, map and hit state, sprites removed or added, secrets, doors, and other level progress.

That choice preserved the static deployment model. No backend. No account. No database. No server session. The browser already had a small persistence layer, and the game used it.

This is another place where directness helped. The storage format did not have to serve multiple clients, sync across devices, support migrations for a live service, or survive hostile input. It had to remember a local game. The shape of the solution matched the shape of the problem.

Why No Dependencies Worked

No dependencies worked because the project was narrow.

It was not trying to create a reusable game engine. It was not trying to support arbitrary maps from arbitrary games. It was not trying to become a framework for browser shooters. It was trying to port one game to the browser, with enough fidelity that the browser disappeared and the game remained.

That narrowness made the absence of dependencies practical.

Canvas handled pixels. XHR handled files. HTML handled screens. CSS handled layout and fades. Audio APIs handled sound. localStorage handled persistence. JavaScript objects handled systems. The missing part was not a library; it was the code that made those browser materials behave like Wolfenstein 3D.

This is the line I still find important.

Dependencies are often useful when they provide a material or a stable primitive. But the core shape of a game is not a generic problem. The renderer, loop, collision, enemy behavior, resource model, and input feel define the game. If those layers come from a general engine too early, the game begins by negotiating with someone else’s idea of what a game should be.

Here, the negotiation was with the browser itself.

That is a very different relationship. The browser gives you primitives, not a game theory. Canvas does not tell you what an enemy is. XHR does not tell you what a map is. localStorage does not tell you how saving should work. Those decisions remain yours.

The port feels old in some ways because it belongs to its time. But it also feels unusually durable because there is so little around it that can expire. There is no abandoned framework version trapped underneath it. There is no engine upgrade path to follow. There is no transitive dependency tree to audit before the source can be understood.

It is just the program and the platform.

What I Would Preserve

If I were polishing the repository today, I would not rewrite it into modern JavaScript.

That would make the code look more familiar to current readers, but it would also remove part of what makes the project valuable. The source shows how a complete browser game was structured when the platform had become capable enough, but before the modern frontend stack became the default answer to every problem.

The globals matter. The script order matters. The direct XHR matters. The vendor-prefixed requestAnimationFrame fallback matters. The audio fallback matters. The little local process arrays matter. They show the shape of the browser as it was, and the shape of a program built close to it.

What I would add is explanation around the code, not a new identity inside the code.

Because the interesting thing is not that the implementation is perfect. It is not. The interesting thing is that the game is complete, understandable, and still runnable as static files. It owns its important layers. It can be opened without resurrecting a vanished ecosystem.

That is rare now.

What I Would Use Today

If I were building the same port from scratch today, I would not reproduce the 2012 structure exactly.

I would still keep the project small. I would still avoid a game engine. I would still avoid a framework. The core of the game would remain mine: the raycaster, the loop, the map representation, the resource model, the input layer, the enemy behavior, the save format. Those are the parts that define the game, and I would still want them shaped by the game rather than by a general-purpose engine.

But I would use modern packaging where it helps without changing the architecture.

I would use Vite. Not because the game needs a framework, but because Vite is a good way to run a local development server, use native-style imports, and produce a clean static output. The important distinction is that Vite would be tooling around the source, not the architecture inside the source. The game should still be understandable as browser code. The build tool should make development smoother, not become the thing the program is written for.

I would use imported modules instead of global objects and script order. In 2012, script tags were the simplest cross-browser module system available for this target. Today, import is the obvious way to make dependencies explicit. The same subsystems would probably still exist: renderer, resources, maps, player, AI, audio, input, screens. They would just be connected by imports instead of shared globals.

I would also use a formatter and a linter.

That was not really part of the workflow when this port was written. The code carries the habits and unevenness of that time: manual formatting, local conventions, and whatever discipline I brought to each file by hand. Today I would not rely on that. A formatter would remove style decisions from the work, and a linter would catch the boring mistakes before they became debugging sessions. That kind of tooling would not change the architecture of the game. It would simply make the source easier to maintain.

I would not use TypeScript.

That is not because TypeScript is bad. For many projects, especially larger application codebases, it is valuable. But for this kind of small, self-contained game, I would rather keep the source close to the runtime language. The important correctness boundaries here are not mostly type boundaries. They are behavioral and spatial: does the ray hit the right wall, does the sprite sort correctly, does the door block the player, does the enemy see through a closed door, does the save state restore the map exactly? TypeScript can document some shapes, but it would not be the thing that makes those systems true.

Plain JavaScript would also keep the source closer to the spirit of the port. The browser is the material. Vite and modules would clean up the development experience, but I would avoid turning the project into a modern stack demonstration.

The version I would build today would be more modular, easier to navigate, and easier to serve locally. But it would still be a static browser game. It would still be Canvas. It would still have no runtime dependencies. It would still choose ownership over generality at the layers where the game becomes itself.

The Port Still Runs

The open-source release does not include copyrighted game data. The source references images, maps, sounds, and music by relative path, but those files are intentionally excluded from the repository.

The source is available on GitHub at lazarv/wolf3d.

For local testing, the folder can still be served with a static server that proxies missing files to the hosted copy:

npx http-server . -p 8080 -c-1 --proxy https://wolf3d.wadcmd.com/

That keeps the source boundary clean. The repository contains the browser port. The game data stays outside it.

And the architecture still works because it was always just static files and browser APIs.

The Thing I Still Like About It

Looking back at this port, the thing I like most is not the raycaster, although I still like the raycaster. It is not the no-dependency choice by itself. It is not the fact that the code still runs.

It is the relationship between the program and its materials.

The implementation does not float above the browser. It touches it directly. It asks Canvas for pixels, HTML for screens, CSS for layering, XHR for files, audio for sound, localStorage for persistence, and JavaScript for the small machines that hold the game together.

There is very little pretending.

That kind of software has a particular feeling. You can follow it down. You can see where time is spent. You can see where state lives. You can see why a door opens, why a wall renders, why an enemy sees you, why a shot hits, why a sound is quiet, why a save game restores the room you left behind.

Modern software often hides those answers behind tools that are powerful, useful, and sometimes necessary. But there is still value in a program where the answers are close to the surface.

This port is one of those programs.

It is a game built from the browser, not from a stack around the browser. It belongs to April-May 2012, but it still says something I believe now: sometimes the best architecture is not the one with the most reusable layers. Sometimes it is the one that lets the thing you are building stay closest to the material it is made from.

For this port, that material was the browser.

And the browser was enough.

Music and Code Ask the Same Thing of Me

Viktor Lázár — Sun, 17 May 2026 15:25:49 +0000

I have had this feeling for a long time: music, and especially composition, is much closer to software development than we usually admit.

The obvious explanation is mathematics. That part is true, of course, but it is also the easiest place to stop: music has numbers behind it, code has numbers behind it, so the two must be related.

I think that is true, but I also think it is the least interesting version of the truth.

The deeper connection, for me, is not mathematics. It is the feeling of parts trying to find their place.

When I write music, I rarely feel like I am simply inventing a song from nothing. It feels more like different pieces slowly reveal what they want to be in relation to each other. A motif begins as a small gesture. A chord progression may feel important for a while, then turn out to be only a passage. A melody can work on its own and still not belong in the center. The song keeps asking where each thing should live.

I feel almost the same thing when I write code.

A module begins as a piece of behavior. A function does not yet know where it belongs. An API has not found its natural shape. Sometimes something works technically, but it has not found its role. It is inside the system, but it does not sit there well. Like an instrument playing the right notes in the wrong place.

One of the most beautiful moments in composition is when a part finally lands where it belongs. Not because it became louder, or more complex, or more impressive. Because suddenly it becomes clear why it is there. The song does not merely contain it. The song needs it. The part is not decoration, not a clever idea, not a little display of skill. It has a role.

The same thing happens in good software.

What impresses me in a beautiful system is not that it contains many things. It is that everything has a reason to be there, and the parts are not fighting each other. Names clarify instead of merely labeling. Boundaries feel calm. The system starts to feel proportionate from the inside.

That sense of proportion is why beautiful code feels musical to me.

I do not mean that only as a metaphor. There really is such a thing as rhythm in a piece of code. There is breath. There is tension and release. Sometimes a refactor feels exactly like removing an unnecessary voice from a song: the result is not poorer, but clearer. Sometimes an abstraction behaves like a good variation on a theme. It does not hide the original idea. It reveals that the same form has been working in more than one place.

And there is code that works, but feels musically false.

It is not necessarily buggy, or slow, or even badly written according to any objective checklist. But something is off. The emphasis is in the wrong place. One part asks for too much attention while another has no room to breathe. The system is full of decisions that can each be justified in isolation, but together they do not sound right.

This is hard to explain to someone who sees programming only as the production of solutions. In the same way, it is hard to explain why a piece of music is not good merely because every note is "correct." Correctness is the price of entry. The real work begins when something already functions, but is not yet true. When the song can be played, but does not yet say what it is supposed to say. When the code runs, but has not yet found the form in which I can leave it alone.

I think composition and software development demand the same kind of care from me.

They ask for a kind of attention that is not satisfied by the fact that something exists. I keep asking whether it exists in the right place, whether it is speaking in the right voice, whether it leaves enough room around itself. And underneath all of that, I am asking whether the whole thing is actually moving somewhere.

This is why music and code do not feel like separate worlds to me. They feel like two different materials for the same inner work. One uses sound. The other uses running systems. One unfolds through time. The other unfolds through use. But in both, I have to listen for structure, remove what does not belong, and wait for the moment when the form begins to look back at me.

Maybe this is why bad code can hurt so much.

Not only because it is hard to work with. Because I can hear the missed music inside it. I can hear that it could be cleaner, quieter, more generous to the next person who has to enter it and keep thinking.

And maybe this is why a good system can be so joyful.

Because it is not only useful. It is not only clever. There is a beauty in it that does not come from decoration, but from the fact that its parts finally understand why they are together.

I think this is why I keep returning to both. In music and in software, I am looking for the same moment: when many separate pieces stop being separate. When the parts begin to serve the same thought. When I no longer have to force the thing to hold together, because the structure has started to carry its own weight.

I wonder how many other people feel this.

How many developers are also musicians, somewhere? Maybe only after work, inside unfinished demos and songs that were never released. And how many of them found a home in software for exactly this reason: because the same compositional pleasure was waiting there, made from different material?

The more I think about it, the less this feels like a coincidence.

Something in them seems to come from the same place.

If you feel it too, I would love to know where music and code meet for you.

Runtime Is Not the Problem

Viktor Lázár — Wed, 13 May 2026 12:21:36 +0000

The most popular story about modern UI frameworks is wonderfully clean. Svelte is small because it is compiled. React is large because it ships a runtime. One moves work to build time; the other carries a machine into the browser. If the question is why a small Svelte app often starts smaller than a small React app, that story is not wrong.

It is only too small.

The important distinction is not compiled vs runtime. The important distinction is specialized output vs packaged capability. A compiler can specialize the program because it sees the component. A runtime can be small if it is packaged as a set of capabilities the application actually uses. The waste appears when a runtime is distributed as a single old monolith: one root API makes the app pay for the whole engine, including paths that only matter to applications much more complex than the one being shipped.

That is not the inevitable cost of React's model. It is the cost of React's packaging shape.

React is not large because runtime frameworks must be large. React is large because the browser-facing React we install today is still assembled like a general-purpose engine rather than a capability graph. If that graph were exposed to bundlers and compilers as static structure, dead-code elimination and tree shaking could do much more of the work people currently credit only to compiled frameworks.

The compiler is not magic. The runtime is not the enemy. The question is where the framework pays for generality, and whether the application is allowed to decline the parts of that generality it does not use.

The Clean Story

Svelte's pitch has always been easy to understand. The official site describes Svelte as a framework that uses a compiler so components do minimal work in the browser. Older Svelte copy made the contrast even sharper: move as much work as possible out of the browser and into the build step. That is a powerful architectural statement because the browser receives code shaped around the application, not a general interpreter for a component model.

React's browser story is different. A React app calls createRoot or hydrateRoot from react-dom/client, and from that moment React owns the tree. The application ships a runtime because the runtime is the thing that keeps React's programming model true after the JavaScript has loaded.

At the scale of a counter, the contrast is almost unfair.

A compiler can look at a tiny counter and emit code that changes the text when the number changes. A runtime framework has to make even that counter an instance of a broader component language. That language is the source of React's power, but it also means the smallest program starts by importing a model built for much larger programs.

This is why small examples make compiled frameworks look so good. They are not paying for the general case before the general case appears.

But the small example also distorts the argument. A real application is not one counter. It is product pressure accumulated over time. Local decisions become global constraints. Dependencies surround the framework. Behavior that began in one place starts to matter somewhere else. At that point, "compiled vs runtime" stops being a binary and becomes a curve.

The Size Curve

The size curve begins with the floor: the amount of JavaScript you ship before the application has done anything interesting. React's floor is visible because react and react-dom are real packages with real client runtime code. Svelte's floor is lower because more of the component model has been consumed by the compiler before the browser ever sees it.

But the floor is only the beginning. The slope matters just as much, because the application does not stay at its starter size. A framework that starts tiny can grow quickly if its compiled output repeats itself. A framework with a higher floor can become relatively cheaper if its runtime amortizes shared behavior well.

Compiled frameworks often have a low floor because they emit specialized code. But specialized code can repeat. If every component carries its own little version of a pattern, the app may pay the same idea many times. Good compilers avoid this by sharing helpers and by lowering common patterns into reusable runtime pieces, which is another way of saying that compiled frameworks also have runtimes. The difference is that those runtimes have already been filtered through the compiler's view of the app.

Runtime frameworks often have a higher floor because they ship the general machine once. But after that first payment, repeated components can be cheap because they are data for the same machine. The runtime does not need a new implementation of the update model for every component. The application describes the tree; the runtime interprets the description.

So the size question should not be "which framework is smaller?" That question hides the shape of the payment. A framework has an initial fixed cost, and it has a growth rate as features are added. The architecture is healthy when the route mostly pays for what it uses. Repeated behavior should be amortized. Absent capability should remain absent from the output.

Tiny islands usually favor the compiler. Larger applications make the answer depend on the curve rather than the category. Once product dependencies dominate the bundle, the framework tax may look smaller in percentage terms, but it has become more architectural: it follows the application into every place that wanted to stay small.

The useful measurement is not the total size of node_modules. It is not even the total output directory. It is the JavaScript on the critical path for a user action. The important bytes are the ones that stand between the user and the first interactive route. After that, the question is whether new code arrives only when the user moves into new behavior, or whether the framework has forced unrelated capability onto the path.

That last question is where React becomes interesting.

React's Monolith Problem

React's public model is beautifully small. Its user-facing idea is compact enough that it survived a decade of ecosystem churn: components make UI feel like ordinary program structure.

The shipped runtime is not compact in the same way.

That is not a criticism of the React team's engineering discipline. React carries a lot because React does a lot. It has to keep a very broad rendering contract true across browsers, across rendering modes, and across years of ecosystem assumptions. The weight is not accidental. The question is whether all of that weight belongs on every route.

The problem is that the browser package is arranged around the general product, not around the current application's capability set.

A simple client-rendered widget does not ask the same question as a server-rendered application that hydrates, streams, recovers from errors, and coordinates work across a large tree. A tiny island with one click handler should be allowed to stay tiny. A component that only needs local interaction should not inherit the full mental weight of an application root.

Today, those distinctions are mostly semantic. They matter to the developer. They matter to the runtime once the app is running. But they are not exposed as a clean static import graph that a bundler can prune aggressively.

The package boundary says: this is React DOM for the client.

It does not say: this route needs the small DOM-and-state subset, while the machinery for richer rendering modes can stay out of the bundle.

That second sentence is what a capability-shaped React would need to make visible.

The Host Is Part of the Cost

There is another asymmetry hidden inside the usual Svelte-vs-React comparison. Svelte's mainstream target is the web DOM. That focus is part of why the compiler can be so effective. It knows the host it is lowering into. It can turn a component into browser-shaped code because the browser is the world the component is meant to inhabit.

That is not an insult. It is a strength. A compiler gains power when the target is narrow enough to make strong decisions.

React's abstraction boundary is different. React DOM is not React; it is one renderer for React. The component model sits above the host. PDF and canvas renderers make the point clearly: React's component approach is not inherently a DOM approach. Those targets do not make the browser bundle smaller. But they do explain why React wants to be a component model before it is a DOM compiler.

This matters because some of React's weight is the price of that separation. A framework tied closely to the DOM can specialize earlier. A framework that treats the DOM as one host among several has to preserve a more abstract contract. That contract is valuable. It lets the same mental model cross output targets in a way a DOM-first compiler does not naturally promise.

But the conclusion should not be that every DOM app must carry the full cost of host-agnostic generality. The renderer boundary is exactly where capability packaging should help. If an application is only using React as a small DOM island, it should not pay as if it were exercising the entire host-independent model. React's multi-target nature explains the need for abstraction. It does not justify an undifferentiated browser bundle.

Tree Shaking Needs Shape

Tree shaking is often described as if it were a magic vacuum that removes whatever code the app does not use. It is less magical than that. Bundlers need static structure. Webpack's own guide is blunt about the ingredients: ES module syntax, production optimizations, and accurate side-effect information are what let unused exports and whole modules disappear.

This is why library shape matters so much.

If a package exposes independent modules with pure exports, the bundler has something to understand. If a package exposes one entry point whose evaluation may affect the whole runtime, the bundler has to be conservative. In JavaScript, conservatism means bytes. If evaluating a module might matter, the module stays.

React is especially difficult here because many capabilities are not normal userland functions. They are semantics inside the renderer. The app imports the renderer, not a set of isolated implementations the bundler can reason about one by one.

That is the old monolith shape.

Not old because the code is bad. Old because the distribution model assumes that the framework is one coherent runtime and the application either uses that runtime or it does not. That assumption made sense when coarse package boundaries were normal and framework competition was mostly about programming model rather than transferred JavaScript. It makes less sense now that applications are expected to move through finer-grained delivery paths, and when build tools care deeply about static structure.

Dead-code elimination cannot remove a capability it cannot see.

What a Capability Graph Would Mean

Imagine React distributed less like a runtime blob and more like a set of capabilities.

The application root would not mean "give me the whole browser renderer." It would declare a rendering mode, and that mode would imply the runtime capabilities needed to preserve React's semantics for that part of the app.

Hooks would not be one undifferentiated runtime assumption. The common local primitives would form the base layer; coordination primitives would be added only when the app uses them. Some of that machinery would still be shared, and some of it would be impossible to remove in practice because the component model depends on it. But the graph would at least describe the difference between "this app uses local state" and "this app uses the full coordination model React exposes."

The DOM event system would follow the same rule. A form route should not pay for event families it never uses. A static island with one button should not inherit the same event surface as a canvas-heavy editor.

Hydration would be a capability, not a tax hidden behind the same import shape as client rendering. The richer runtime features would be visible in the graph instead of being treated as ambient facts of the renderer. Development diagnostics would remain development-only with a boundary that production bundlers can see without heroic inference.

The compiler would participate, but it would not replace the runtime. JSX compilation and React Compiler output could describe what the app actually uses. Framework and bundler layers could then carry that information into the package graph. This is the shape of the missing information: the app already contains the answer, but the framework does not package itself in a way that lets the build pipeline use the answer fully.

In that world, React would still be a runtime framework. It would still provide the live component semantics people choose React for. But a small app would no longer pay for the whole semantic universe before it had earned it.

That is the part the compiled-vs-runtime argument misses. A runtime can be tree-shaken if it is designed as something tree-shakable.

Compilation Is a Form of Packaging

The word "compiled" makes Svelte sound like it lives in a different category, but compilation is also a packaging strategy.

The compiler looks at the application and decides what code to emit. Its real advantage is that it filters the runtime surface through what the program can prove at build time. The result is not "no runtime." The result is a runtime surface that has already been filtered through the program.

That filtering is the real advantage.

A compiler gets to ask: what does this component actually do?

A capability-shaped runtime gets to ask almost the same question: what capabilities does this application actually use?

Those two approaches are closer than the marketing categories suggest. The best future is probably not compiled frameworks on one side and runtime frameworks on the other. It is compiler-assisted runtimes with small, explicit capability graphs. It is frameworks whose core semantics can remain general while their shipped code becomes specific.

Svelte starts from specialization and adds shared machinery when specialization would repeat too much. React starts from shared machinery and could recover specialization by making the machinery divisible. The direction is different. The destination is similar: the browser should receive the smallest faithful implementation of the app's semantics.

The App Size Conversation We Should Have

When people compare Svelte and React bundle sizes, they often compare starter apps. Starter apps are useful because they reveal the floor. They are also dangerous because they make the floor feel like the whole building.

A better comparison would walk the same frameworks through a growth path. It would start with a tiny island and keep adding the kinds of pressure real products accumulate. The point would not be to make the examples impressive. The point would be to see how the framework's fixed cost behaves as the application stops being a toy.

For each one, the measurement should separate framework cost from app cost and route cost from total build output. A framework that looks expensive at the beginning may disappear behind the product later. A framework that looks tiny at the beginning may duplicate enough specialized output to make the curve less obvious. A framework that lazy-loads well may win on the first route even if its total app output is larger.

The point of this exercise is not to crown a universal winner. The point is to see the shape of payment.

Svelte's bet is that many UI programs are better served by paying at build time and shipping specialized code. React's bet has been that many UI programs are better served by a stable runtime model that can express a very wide range of behavior. Both bets are legitimate. The problem is when React's bet is implemented as if every page needs the full runtime model up front.

That is where React's size becomes less philosophical and more mechanical.

The Smaller React That Could Exist

There is a smaller React hiding inside React.

Not Preact. Not a compatibility clone. Not a new framework with React-like syntax. React itself, if its distribution model matched the way modern applications are built.

That React would have a small root for client-only islands. Server-rendered roots would opt into hydration as a visible capability. More advanced rendering behavior would be added by use, not smuggled in as part of the default client entry point. The important change would be static structure: bundlers would be able to remove entire subtrees without understanding React's internals, and framework adapters could declare the rendering mode they need per route.

This would not be easy. React's internal semantics are deeply connected. Splitting a renderer after years of integrated design is harder than designing a small library from scratch. Some capabilities that look optional from the outside may share invariants that make them hard to separate safely. The compatibility contract is enormous, and every new boundary is another place where bugs can hide.

But difficulty is not impossibility, and it is not a rebuttal to the architectural point.

The React programming model does not require the browser bundle to be a monolith. It requires a runtime capable of preserving React's semantics for the capabilities the application uses. Those are different requirements. One is historical packaging. The other is the actual product.

If React were designed today for the way applications are delivered now, it is hard to imagine it would expose the same coarse client runtime as the only normal path. It would be capability-first from the beginning because the web now punishes undifferentiated JavaScript more visibly than it did when React's package shape hardened.

Runtime Is Still Valuable

It is tempting, after all of this, to conclude that runtimes are a regrettable compromise. They are not.

Runtimes buy consistency. They make dynamic behavior composable across the lifetime of an app and across code-splitting boundaries. They can also see more of the live application than any one compiled component can, which makes the runtime behavior richer than a pile of emitted code.

Those are real advantages. They are why React won so much mindshare in the first place.

The mistake is treating runtime value and runtime size as inseparable. A runtime is not a single object by nature. It can be layered, declared, and assisted by a compiler that proves which layers are needed. A framework can keep a high-level programming model without forcing every route to ship every lower-level mechanism.

The right criticism of React is not "React has a runtime."

The right criticism is "React's runtime is not packaged according to the capabilities of the app."

That is a much more useful criticism because it points toward a better React rather than toward a world where every framework has to become Svelte.

The Real Divide

The real divide is not compiled vs runtime.

The real divide is specific vs undifferentiated.

Specific means the browser receives code shaped around the current program. For a compiled framework, that shape comes from emitted output. For a runtime framework, it has to come from capability boundaries. Undifferentiated means the framework ships its generality before the app has asked for it.

This is the lens that makes the argument clearer.

Svelte is not small because compilers are holy. It is small because the compiler gives the package manager and bundler a more app-shaped output. React is not large because runtimes are doomed. It is large because the output is still too framework-shaped.

The browser does not care whether a byte came from a compiler or a runtime package. It cares whether the byte is necessary for the current experience. Users do not reward architectural purity. They reward pages that load quickly, become interactive quickly, and stay responsive under real product pressure.

So the question for any framework should be simple:

Can the smallest app receive the smallest faithful version of your model?

If the answer is yes, the framework scales downward. It can start small without being a toy. If the answer is no, the framework may still be powerful, mature, and worth choosing, but its size problem is not a law of nature. It is a distribution problem.

React could be small. Not by becoming Svelte. Not by abandoning runtime semantics. By admitting, in its package shape, that applications do not use frameworks all at once.

They use capabilities.

And capabilities are exactly the kind of thing a modern build pipeline can remove when they are absent, if only the framework is built to let them be absent.

RSC Is Not the Input Boundary

Viktor Lázár — Sat, 09 May 2026 18:57:17 +0000

Every major React Server Components security release seems to trigger the same little ritual. An advisory lands, someone sees the letters RSC, and a few hours later the lesson has already collapsed into: "RSC is bad."

That lesson is convenient. It is also imprecise.

The same thing happened around the Next.js security release from May 7, 2026. Vercel shipped fixes for several Next.js and upstream React issues, including a high-severity denial-of-service vulnerability affecting the React Server Components packages. But the interesting part of the advisory was not that rendering a Server Component is inherently dangerous. The interesting part was that specially crafted HTTP requests sent to Server Function endpoints could cause excessive CPU usage or out-of-memory failures while the payload was being processed.

That distinction is not a footnote. It is the center of the issue.

A Server Component is not the same attack surface as a Server Function. One sends a representation of a component tree from the server to the client. The other receives a payload from the client, asks the server runtime to deserialize it, and then invokes server-side code. They can both live inside the RSC model. They can both involve the Flight protocol. But from a security perspective, they ask opposite questions.

The Server Component question is: what are we allowing to leave the server and reach the client?

The Server Function question is: what are we allowing to enter the server from the client?

The second one is an input boundary. If that boundary is enforced too late, the failure is not that the RSC model is broken. The failure is that an RPC-shaped input surface was treated as if it were merely a framework ergonomic.

The Category Error

There is a recurring confusion in RSC discussions. People often talk about "RSC" as one thing, when in practice they are combining several distinct mechanisms:

Server Components: components that run on the server.
Client Components: components that run in the browser, while still participating in the same React tree.
Server References / Server Functions: server-side functions for which the client receives a reference and can later issue a call.
Flight protocol: the serialization format that carries component payloads, references, and a broader set of values between the server and the client.

Together, these form an architecture. They do not share the same risk profile.

When a Server Component renders, the direction of execution is primarily server to client. The server produces a payload. The client consumes it. The usual class of bug is that the server puts something into that payload that it should not have put there. That can be a data leak, a cache-boundary mistake, or a component-level authorization bug.

When a Server Function runs, the direction reverses. The client sends something to the server. The server runtime has to understand the payload, identify the action, materialize the arguments, and pass them to the handler.

That is a very different moment. The browser is no longer just a consumer. The browser, or anything capable of sending an HTTP request, is now providing input to the server.

An endpoint like that cannot be treated as a React composition detail. It is a public RPC surface. It may look like a function call to the developer. TypeScript may make it feel wonderfully local. Over the network, it is still a hostile input boundary.

What Happens in a Server Function Call?

In simplified form, a Server Function request looks like this:

client event
  -> POST request
    -> identify action id / server reference
      -> deserialize Flight payload
        -> materialize arguments
          -> invoke server function handler

Most application code focuses on the last step:

async function updateProfile(input) {
  "use server";

  const data = schema.parse(input);
  await db.user.update(data);
}

At the application level, this is better than nothing. The handler is not blindly trusting the input. But for the class of problem described in the 2026 advisory, this is already late.

By the time schema.parse(input) runs, the runtime has already done much of the risky work: it has read the request, walked the payload, materialized values, built objects, interpreted references, and potentially dealt with streams, binary values, and nested structures. If the goal of the attack is not to smuggle invalid business data into the handler, but to make deserialization itself consume too much CPU or memory, validation inside the handler does not protect the server from the relevant cost.

So "validate your input" is not specific enough.

The question is where.

If validation happens inside the handler, it protects application invariants.

If validation happens in the Server Function layer after the request has already been deserialized, it gives the developer a better contract, but it may still leave the decoder cost exposed.

If validation happens while the protocol payload is being deserialized, the runtime can know during the argument walk what it expects, what it should drop, what it should reject, and when it should stop processing the request.

That is the difference that matters.

A WAF Is the Wrong Boundary

One important line in Vercel's release was that these advisories could not be reliably blocked at the WAF layer.

That should not be surprising.

A WAF sees HTTP requests. It can inspect headers, size, URLs, known patterns, maybe parts of the body. It does not fully understand the semantics of a Flight payload. It does not know which function a given server reference points to. It does not know how many arguments that function expects. It does not know that slot zero must be a string, slot one must be FormData, slot two must be a Map<string, number>, and the file field must be at most five megabytes and either image/png or image/jpeg.

If the WAF tried to know all of that, it would effectively be reimplementing the framework protocol at the edge. That is brittle, version-dependent, and it puts the responsibility in the wrong place.

The right boundary is where the runtime already knows which Server Function it is about to call, but has not yet handed materialized input to the handler.

That is the protocol layer.

This Is Not a TypeScript Problem

Types usually enter the discussion here. A Server Function might look like this:

async function savePost(post: PostInput) {
  "use server";
  // ...
}

The developer experience suggests that post is a PostInput.

From the network's point of view, that is only a hope.

The TypeScript type does not exist in the request. It does not exist in the Flight payload. It will not tell the decoder when to stop. It will not reject an overly deep structure, an oversized string, an oversized binary value, an unexpected FormData field, or a Map whose size is itself enough to become a denial-of-service attempt.

Types are useful documentation for the contract. But if the contract protects a runtime boundary, runtime information has to exist too.

That is why the Server Function definition needs metadata that does more than narrow the handler's TypeScript type. The metadata has to reach the protocol decoder.

What Late Validation Looks Like

Consider an abstract Server Function API:

const savePost = createServerFn()
  .inputValidator(postSchema)
  .handler(async ({ data }) => {
    await db.post.create(data);
  });

This is a good direction. Validation lives at the definition site, not scattered through the handler body. The handler receives validated data. TypeScript inference moves together with the runtime schema. An API like this is much healthier than a bare async function (input: Whatever) and a comment saying "the client calls this."

TanStack Start is on this side of the line. Its createServerFn API makes the Server Function explicit, treats the input validator as part of the function contract, and documents that client-side calls become network calls. That is much better than hiding the request-shaped nature of the operation.

But it is still a different category.

A TanStack Start Server Function is not an RSC Flight Server Function in the same sense as an RSC server reference. Based on the documented API, validation is part of the Server Function layer: the function receives a data input, the runtime validates that input, and then the handler runs. That is a good application-level contract. If the runtime has already deserialized the body into a JavaScript value before the validator sees it, then the validator is working in the post-deserialization world.

This is not a criticism in the sense of "TanStack Start is bad." It is not. A definition-site validator is the right direction for a classic RPC API.

It is simply not the same protection as giving the Flight decoder the Server Function's argument-slot contract and letting validation happen during the payload walk.

For an RPC API, the question is how much work the framework's serialization layer has to do before the validator gets control. For an RSC Server Function, the question is even sharper because the Flight payload can carry a richer value space. We are not only talking about JSON objects. The protocol can represent references, form data, binary values, streams, iterables, promises, typed arrays, Map, and Set.

The richer the wire format, the less satisfying "we parse it at the top of the handler" becomes.

The react-server Approach

The @lazarv/react-server approach is not merely to provide a convenient validation wrapper around the handler.

The important part is that the Server Function definition attaches metadata to the server reference, and that metadata reaches the Flight decoder.

For example:

import {
  createFunction,
  formData,
  file,
} from "@lazarv/react-server/function";
import { z } from "zod";

export const uploadAvatar = createFunction([
  formData(
    {
      displayName: z.string().min(1).max(80),
      avatar: file({
        maxBytes: 5_000_000,
        mime: ["image/png", "image/jpeg"],
      }),
    },
    { unknown: "reject" }
  ),
])(async function uploadAvatar(form) {
  "use server";

  const displayName = form.get("displayName");
  const avatar = form.get("avatar");

  await saveAvatar({ displayName, avatar });
});

The point is not only that form.get("avatar") becomes nicer inside the handler.

The more important contract is this:

the first argument to the Server Function is FormData;
the allowed fields are known;
unknown fields can be rejected by default;
the file has a size limit;
the MIME allowlist is part of the wire contract;
the handler only runs if the decoder successfully validates that slot.

That is not business logic. That is an input boundary.

Slot-Walk Validation

The technical shape is roughly this.

When a Server Function export is wrapped with createFunction(...), the parse/validate spec associated with that wrapper is registered as server reference metadata. When a request comes in, the runtime first tries to recover the action id. For header-based action calls, that can come from the react-server-action header. For progressive-enhancement form submissions, it can be encoded in the submitted FormData. If the token is encrypted, the runtime decrypts it first so it knows which action the request is trying to call.

Then comes a small but important step: the action module has to be loaded before decoding.

That may sound incidental. It is not. The server-function metadata registry is populated by the module's top-level registerServerReference(...) calls. If the runtime deserialized the payload first and only loaded the action module later, the first call to an action could silently skip validation. So react-server preloads the action module first, then calls decodeReply with the recovered action id.

From there, the decoder is no longer walking the argument list blindly. It knows which Server Function it is decoding for. It can look up the associated metadata. It can apply parse and validate slot by slot.

If the first argument is z.string(), slot zero has to validate as a string.

If the second argument is arrayBuffer({ maxBytes: 1024 }), the decoder can reject an oversized buffer based on byte length.

If a formData(...) spec uses unknown: "reject", an injected extra field does not reach the handler.

If a file(...) spec declares a MIME allowlist and a size limit, the runtime does not wait for application code to decide whether the file is acceptable.

If a map(...) or set(...) spec has a maximum size, the collection cannot grow without bound in the pre-handler world.

If a stream or async iterable has a maximum chunk count or byte limit, the boundary remains active as the handler consumes it.

That is the key property: the shape of the Server Function input is not only TypeScript inference. It is a decoder contract.

Failure Is Structural

A protocol-level validation failure is not a business validation failure.

It is not the same as a user typing a bad email address into a form and receiving a field error. It means the wire payload did not satisfy the contract under which the server was willing to materialize a Server Function call at all.

The right response is structural rejection.

In react-server, a validation failure during the slot walk becomes a DecodeValidationError and is mapped to a 400 response. The handler does not run. The argument list is not bound. The client does not receive detailed schema diagnostics, because those details can reveal useful shape information to an attacker. The operator log can still keep the useful parts: action id, slot index, and failure reason.

Again, this is different from application-level validation.

A form validation error is a user experience concern.

A decode validation error is a protocol concern.

If we merge those two paths, we either reveal too much to an attacker or give too little feedback to a real user. They should not be the same path.

Bound Arguments Are Not Call Arguments

There is another detail that is easy to lose in RSC Server Function discussions: call arguments and bound captures are not the same thing.

A Server Function can be created with bound values. These are values carried by a server-side closure or binding and later associated with the server reference. They should not be treated the same way as runtime arguments sent by the client.

In the react-server model, bound captures are integrity-protected by the action token. That is a different kind of protection than per-argument validation. They do not need the same schema path as client input, because they are not crossing the same trust boundary.

Arguments sent by the client are hostile input.

Bound captures are integrity-protected server-side state representation.

If both are collapsed into the same "validate the input" bucket, the model becomes muddy again.

Global Decode Limits

Per-function contracts need a second layer: global resource ceilings.

There will be unvalidated legacy actions. There will be code in the middle of migration. There will be Server Functions where some slots are intentionally loose. And there are payload characteristics that should not have to be repeated manually on every function.

So the runtime needs limits such as:

maximum payload byte size;
maximum Flight row count;
maximum materialization depth;
maximum number of bound arguments;
maximum BigInt digit count;
maximum string length;
maximum stream chunk count.

These do not replace per-function validation. They are the safety floor. The function spec is the precise contract. The global limits are the ceilings that still stop obviously abusive payloads when a function has not yet been declared perfectly.

Together, they form a more meaningful defense.

Dev-Time Strictness

A runtime's behavior is not only what it does in production. It is also what it teaches during development.

If a "use server" export can be called from the client without validation, that is an attack surface that may not be visible at the call site. The developer sees a function. The browser sees an endpoint. The reviewer often reads the handler body, not the wire boundary.

That is why a dev-time warning for bare Server Functions is useful:

Server function ... called without validation

The point is not that every function needs a complex schema. Some functions have no input. Some migration paths need a temporary escape hatch. But that should be an explicit decision. The default should not be that a publicly callable Server Function has no runtime input contract and nobody notices until a security release makes the boundary visible.

In that sense, the no-spec createFunction() form is useful too. It does not add validation, but it records intent. The runtime can tell that the developer has seen the boundary and chosen not to narrow it yet.

The Missing Runtime Contract in Next.js

Next.js fixed the affected upstream React issues, and everyone affected should upgrade. That is not optional. After an advisory like this, the first correct move is always to patch.

But patching is not the same thing as learning the architectural lesson.

In the current Next.js Server Function model, there is no generally documented framework API that gives the runtime a per-function Flight decode contract. There is "use server". There is a server-side handler. You can validate inside that handler. You can build your own helper around it. But that is not the same as attaching argument-slot metadata to the server reference so the decoder knows what it is allowed to materialize before the handler runs.

That is why I consider the react-server approach stronger here.

Not because it has "schema validation." Schema validation exists in many places.

Because the validation happens in a better place.

Because the function contract appears on the Flight protocol decode path.

Because malformed payloads can be structurally rejected before handler execution.

Because the wire-aware specs cover not only application data models, but also the richer value space of the protocol: FormData, File, Blob, ArrayBuffer, typed arrays, Map, Set, streams, iterables, and promises.

And because this defense is not a WAF rule, not a convention, not "remember to parse at the top of the handler," but a runtime boundary.

A Server Function Is a Public Endpoint

The simplest way to say all of this is:

A Server Function is a public endpoint.

Not because it looks like a REST route. Not because the developer wrote a URL for it. Because the client can send a request that causes the server to attempt to invoke a function.

Once we accept that, the security consequences become clearer:

every Server Function should have an input contract;
the contract should live at the definition site, not be scattered through the handler body;
the runtime should know the contract as early as possible;
deserialization cost should be bounded;
unknown fields should not be treated as harmless by default;
file and blob inputs should have size and MIME constraints;
authorization should be explicit in the Server Function, not inferred from the surrounding component tree;
the WAF should be an extra layer, not the primary interpreter.

This is not an anti-RSC position.

It is the position that takes RSC seriously enough not to treat all of its parts as one mystical box.

RSC Is Not the Scapegoat

The interesting thing about RSC is that it gives us a formal boundary between two different execution environments. The server and the client are not the same place. They have different capabilities, different costs, different failure modes, and different security responsibilities.

That is the strength of the model.

But a boundary is only useful if we are precise about what crosses it, and in which direction.

For Server Components, the question is what the server sends to the client.

For Server Functions, the question is what the server accepts from the client.

When a Server Function input payload is validated too late, or when the runtime does too much work before it even knows what it expects, the lesson is not that Server Components are a bad idea. The lesson is that an RPC-shaped input surface was treated as framework ergonomics for too long.

That mistake is fixable. But only if we name it precisely.

Not "RSC is bad."

Not "Server Components are insecure."

This:

Server Function input payloads need protocol-level validation.

That sentence is less dramatic. It is also more true.

And if we want RSC to have a healthy future, that is exactly the kind of sentence we need: less drama around the model, and more attention on the few boundaries where the model actually meets a hostile network.

References

Dissatisfaction Is a Spark

Viktor Lázár — Sat, 09 May 2026 18:55:43 +0000

I have a particular relationship with dissatisfaction.

When something does not feel right, I rarely manage to leave it there. A library feels too heavy. A framework hides the thing I want to touch. A tool solves the wrong half of the problem. A program almost understands its own shape, but not quite. A game has a wonderful idea buried under a system that keeps getting in its own way.

Most sane people, I think, complain for a minute and move on.

I complain for a minute and open a new project.

This is not always wise. It is not always efficient. There is a whole graveyard of half-built answers behind that impulse, each one started with the private conviction that the world would be slightly better if this one irritating thing were different. But I have learned not to distrust the impulse too much, because it has carried me toward almost everything I have cared about building.

For me, dissatisfaction is not only rejection. It is attention becoming specific.

There is a kind of annoyance that is just noise. Something is broken, ugly, slow, badly named, overdesigned, underdesigned. Fine. The world is full of those. But sometimes the annoyance has a shape. It keeps returning to the same edge. I can feel, before I can explain, that the problem is not accidental. Something in the design is pointing in the wrong direction. Something wants to be inverted, simplified, pulled apart, made composable, made honest.

That feeling is dangerous in the best way.

It turns passive criticism into motion. It moves the question from "why is this like this?" to "could I make something better than this?" and then, eventually, "what would it look like if I did?" And once that question becomes vivid enough, building stops feeling like work and starts feeling like a form of thinking. The project is not a product yet. It is an argument I can run.

I think this is why so many of my projects begin as irritations. Not because I enjoy being annoyed, but because annoyance gives the mind a surface to push against. Pure satisfaction rarely asks anything of me. It closes the loop. Dissatisfaction leaves the loop open, and an open loop is where imagination gets in.

Over time, though, I have noticed that the most persistent version of this is not even about other people's tools.

Most of the time, the thing I am dissatisfied with is my own work. I build something, and then I see the compromise inside it. A decision I made too early. A boundary I drew in the wrong place. A design that seemed clean until real use put pressure on it. An implementation that works, but carries the shape of a mistake I had not yet learned how to name.

That feeling is sharper, because I cannot blame anyone else for it. The flaw is mine. I put it there, in the design or in the implementation, usually for reasons that made sense at the time. But once I can see it, I want to make the whole thing better. Not slightly patched. Better. So I open the project again. Or I start the next one, carrying the correction forward.

@lazarv/react-server came from that kind of place. Not from a clean plan, not from market analysis, not from the abstract desire to make a framework. It came from a series of small refusals. I did not want the boundaries to be there. I did not want the conventions to decide so much. I did not want the runtime to feel like a menu when it could feel like a set of primitives. At some point, the refusals became more than complaints. They became a thing I could build.

That transformation still feels a little mysterious to me. The same emotion that could have become bitterness becomes a prototype. The same frustration that could have ended in a thread becomes a repository. The same little "no" turns, if I stay with it long enough, into a more interesting "what if?"

Maybe that is the difference that matters. Dissatisfaction by itself is cheap. Everyone can see what is wrong. Everyone has taste when something fails them. The creative part begins when I let the dissatisfaction obligate me. If I really believe the thing could be better, then for a while I have to stop being only its critic. I have to become responsible for an alternative, even a small one, even a flawed one, even one nobody asked for.

That responsibility is where the energy is.

I do not think every irritation deserves a project. Life is too short, and most tools are allowed to be imperfect. But I have stopped treating dissatisfaction as a negative state I need to escape from quickly. Sometimes it is the first draft of care. Sometimes it is the mind noticing a possible world and being unable to unsee it.

When I am not satisfied, something in me starts looking for a door.

Sometimes the door is real.

What does dissatisfaction do in you?

The Master Builder, Unleashed

Viktor Lázár — Thu, 07 May 2026 06:40:36 +0000

There is a particular kind of pain in software work: sitting in a meeting about a thing you already know how to build.

Not vaguely. Not optimistically. You can see the first version. You can see the shape of the data, the awkward part of the UI, the one integration that will probably hurt, the test that should exist before anyone trusts it, the part that can be ugly for a week, and the part that must be right from the beginning. The work is not done, but the form is already present in your head.

Then the meeting continues.

The discussion moves through alignment, ownership, prioritization, stakeholder expectations, dependency mapping, launch risk, follow-up meetings, and the increasingly ceremonial question of who should "drive" the thing. None of those words are fake. Some of them point at real constraints. But the emotional fact remains: the software could have started existing an hour ago.

This is not the impatience of someone who does not understand organizations. It is the frustration of someone who understands both the work and the organization well enough to feel the gap between them.

I have spent most of my career building things that were not supposed to fit where I put them: old game engines in the browser, data protocols in JavaScript, React Server Components outside the frameworks that tried to own them.

That kind of work teaches you something uncomfortable: the hard part is rarely the first line of code. The hard part is keeping the shape of the thing intact while the world asks you to translate it into smaller, safer pieces.

This is where AI agents change the equation.

For a long time, the gap between seeing the shape of the thing and getting it built without losing that shape was just the cost of doing serious software. Big products needed big teams. Big teams needed coordination. Coordination needed meetings. The developer who could see the shape of the thing still needed designers, reviewers, frontend engineers, backend engineers, QA, release managers, platform support, security review, product sign-off, and enough calendar space for all of those people to agree that the thing should become real.

The company owned execution. The individual owned at most a piece of intent.

AI agents have started to disturb that bargain.

The master builder

The developer I am talking about is not any developer.

This is not a beginner with a prompt box. It is not a mid-level engineer asking a model to fill in the parts they do not yet understand. It is not the fantasy that software can now be produced by desire alone, where a person describes an app, accepts the first plausible artifact, and calls the result engineering.

The person at the center of this shift is closer to the old idea of the master builder.

A master builder does not merely place bricks. They understand the structure before it exists. They know what can be improvised and what cannot. They know which details are cosmetic, which details are load-bearing, and which shortcuts will become expensive only after the room is full of people. They can work with specialists without being dissolved by specialization, because they carry a model of the whole.

In software, this is the staff-level engineer, the principal engineer, the technical founder, the experienced IC with taste and ownership, the person who has built enough systems to know that implementation is never just implementation. They can read a product problem and see a system. They can read a system and see the product assumptions hiding inside it. They know when a design is under-specified, when an abstraction is premature, when a test suite is giving false comfort, when the happy path is lying, and when a release is safe enough to learn from.

That kind of developer was already valuable. AI does not create that value. It gives that value a larger surface to act on.

The agent is not the builder. The agent is a tool in the builder's workshop.

Execution used to be scarce

Most software organizations were shaped by a simple historical fact: writing, changing, and maintaining code required human time in large quantities.

If a roadmap had more work than the current team could do, the answer was usually headcount. More frontend engineers. More backend engineers. More QA. More managers to coordinate the larger group. More process to make sure the larger group did not destroy itself by moving independently. The shape of the organization followed the scarcity of implementation.

That scarcity made the company powerful. A small team might have a sharper idea, but the large company had the machinery to grind through the implementation. It could assign ten people to a problem, put a manager over them, attach design and product, run research, staff a platform dependency, and push the thing through a release train. The small team could move quickly at the beginning, but the large company could eventually bring mass to bear.

That is why the old acquisition story made sense. A small company found a shape the market wanted. A large company bought it, copied it, or slowly surrounded it with distribution and resources. The small company had clarity. The large company had execution capacity.

AI agents do not eliminate the large company's advantages. Distribution still matters. Trust still matters. Compliance, support, procurement, brand, data access, sales channels, regulatory knowledge, and operational maturity still matter. A bank is not replaced by a weekend app. A payments company is not replaced by a clever clone. NASA is not made less capable at space exploration because a web page could be more inspiring.

But a particular advantage has weakened: the assumption that serious software requires organizational mass before it can be executed.

That assumption is what Theo was circling in "Software engineering is dead now". The provocative title is less interesting than the operational shift underneath it. When code becomes cheaper to produce, the bottleneck moves. The important question stops being "how many engineers can we assign?" and becomes "who understands the problem well enough to direct the work?"

That is a very different question.

The agent changes the unit of leverage

The most important thing about AI coding agents is not that they write code.

It is that they let one coherent intent remain coherent across more of the work.

Before agents, even a strong engineer had to break their intent apart to get enough capacity. One person could hold the whole shape, but the work had to be distributed across a team. That meant translation. The product shape became tickets. The tickets became implementation slices. The slices moved through people with different contexts, incentives, calendars, and levels of taste. Review tried to recover coherence after the fact.

Sometimes that worked beautifully. Good teams are real. Collaboration can improve an idea. A second pair of eyes can catch the thing the builder missed. The point is not that teams are bad.

The point is that teams are expensive, not only in salary but in semantic loss.

Every handoff risks changing the idea. Every meeting turns part of the artifact back into language. Every approval step asks the work to justify itself before it has had a chance to become visible. Every person added to the loop increases capacity and coordination at the same time. When implementation was scarce, that trade was often worth it. When implementation becomes cheaper, the cost becomes easier to see.

An AI agent changes the trade because it adds execution without adding a second will.

That sentence is dangerous if read carelessly, so it needs the adult version immediately: the agent adds mistakes, hallucinations, overconfidence, style drift, security risk, and an endless appetite for plausible wrongness. It must be constrained, reviewed, tested, and corrected. It does not remove engineering discipline.

But it also does not need to be aligned in the human sense. It does not need a career path, a meeting, a roadmap narrative, a title, a territory, or a week to build context from office politics. It can be pointed at a narrow part of the system, given constraints, corrected when it drifts, and asked to try again. It is not autonomous in the way a teammate is autonomous. That is precisely why it is useful as leverage.

For the master builder, this is new. The builder can keep the whole artifact in view while delegating pieces of execution to tools that do not dilute the intent. The work still needs judgment. It needs more judgment, not less. But the distance between judgment and execution shrinks.

This is not vibe coding

This distinction matters because the public language around AI-assisted development has been polluted by "vibe coding."

Vibe coding is useful as a name for a real phenomenon: someone repeatedly prompts an AI system, accepts whatever looks close enough, and moves forward without deeply understanding the result. It can be fun. It can produce charming prototypes. It can help people explore personal software. It can also produce systems nobody should be asked to maintain.

Syntax has been good on this distinction. In "Vibe Coding Is a Problem", the problem is not that AI helps write code. The problem is the absence of close review, the willingness to stay at the surface, and the illusion that running software is the same thing as understood software. Their later episode, "How to Fix Vibe Coding", points in the better direction: deterministic tools, linting, quality analysis, headless browsers, task workflows, observability, and tighter feedback loops.

That is the line.

The future worth taking seriously is not vibe coding. It is developer-led AI engineering.

The developer supplies the intent. The developer supplies the taste. The developer supplies the constraints. The developer decides where the agent is allowed to roam and where it must stay on rails. The developer reads the diff. The developer runs the tests. The developer notices when the solution is locally correct but globally wrong. The developer decides whether the artifact deserves to exist.

The agent accelerates the loop. It does not own the loop.

This is why AI does not flatten all developers equally. It amplifies what is already there. A developer without judgment can now produce more code than before, which mostly means they can produce more unresolved consequence than before. A developer with judgment can produce more finished thought than before.

The difference is not typing speed. The difference is taste under acceleration.

Quality was never guaranteed by size

One of the quiet revelations of this era is that large institutions do not automatically produce better artifacts.

They can produce extraordinary things. They can coordinate missions, operate infrastructure, satisfy regulators, support millions of users, and preserve knowledge across decades. But the artifact in front of the user is not always where that strength appears.

NASA's Ignition page is a useful object to look at for this reason. The underlying subject is enormous: Artemis, commercial lunar transportation, moon base capabilities, lunar terrain vehicles, procurement strategy, timelines, technical ambition. The page itself is largely a resource hub: PDFs, videos, advisories, requests for information, presentations, links. That may be the correct institutional shape for NASA's internal and public obligations. It is not the same thing as a product experience that makes the ambition legible.

This is not a dunk on NASA. NASA can do things that no web developer can do.

The point is more specific: institutional seriousness does not automatically become interface quality. A large organization can have the facts, the mission, the budget, the experts, and the public mandate, and still produce a web artifact that feels assembled by process rather than shaped by taste.

That is exactly the kind of gap an AI-amplified master builder can attack. Not because they know more about lunar transportation than NASA. They do not. Because they can take a pile of material, infer the narrative shape, build an explorable interface, tighten the hierarchy, improve the pacing, test the interactions, and iterate before the institutional process has finished deciding which department owns the page.

The same pattern shows up in developer tooling. T3 Code is interesting not only as a tool for coding agents, but as an artifact of the new workflow. It is a minimal web GUI around agents like Codex, with sessions, git integration, worktrees, runtime modes, and a developer-facing surface designed around actual agent use. Whether or not that particular product becomes the winner is beside the point. Its existence is a sign of the tempo change. A small team can feel a workflow problem, build directly into it, and ship a tool that makes the new loop more usable.

The old world made this kind of thing harder. The new world makes it common.

The small team becomes dangerous again

The small team always had one advantage: fewer people had to agree before the work moved.

That advantage used to be balanced by a brutal limitation: fewer people could build. A small team could choose quickly but execute slowly once the surface area grew. A large team could choose slowly but execute with force once the organization aligned.

AI changes the ratio. It gives the small team, and sometimes the single master builder, access to execution capacity that used to require organizational size. It does not give them the large company's distribution, trust, legal department, customer base, or operational maturity. But for many software products, the first decisive question is not "who has the biggest organization?" It is "who can turn a clear product judgment into a working artifact fastest?"

That is where the small team becomes dangerous.

Not because bureaucracy is stupid. Bureaucracy is often memory. It is risk encoded as procedure. It is how large systems avoid repeating failures that individuals would happily rediscover. But bureaucracy becomes pathological when it continues to price execution as scarce after execution has become abundant.

That is the source of the meeting pain.

The master builder is not angry because other people exist. They are angry because the organization is still spending days converting intent into permission while the toolchain has made it possible to convert intent into a prototype, a test, a diff, a demo, or a shipped internal version. The old process insists on discussing the work in the abstract because it was designed for a world where making the work concrete was expensive.

In the new world, concreteness is cheap enough to be part of the conversation.

Instead of six meetings to decide whether an idea is viable, the builder can return with a working version. Instead of arguing about a flow in a document, they can put the flow in front of users. Instead of writing a speculative architecture proposal for a small feature, they can branch, build, test, measure, and throw it away if it fails. The artifact can arrive earlier in the decision process.

That should make organizations better. Often it will make them uncomfortable first.

What still belongs to the team

There is an easy but wrong conclusion here: if agents give execution back to individuals, teams no longer matter.

Teams still matter. They matter most where reality is wider than the artifact.

A master builder can build a remarkable first version, but production software lives in obligations. Security matters. Accessibility matters. On-call matters. Data retention matters. Customer migration matters. Billing matters. Support matters. Legal review matters. Incident response matters. The larger the promise a product makes to the world, the more the work extends beyond the person who first saw the shape.

The mistake is not having a team. The mistake is using the team as a substitute for clear intent.

A healthy team around a master builder should sharpen the artifact, not dissolve it. It should bring constraints into the work at the moment those constraints become real. It should catch risks, improve taste, protect users, and make the result operable. It should not turn every act of building into a negotiation over whether building may begin.

That is the organizational challenge of AI-assisted engineering. The best teams will learn to let artifacts arrive earlier, then apply discipline around them. The worst teams will keep demanding consensus before concreteness, and they will slowly discover that the builders with the clearest intent have stopped waiting.

Some will leave to start companies. Some will stay and route around the process. Some will become the people inside large organizations who quietly change the operating model. But the psychological shift is already here: the experienced engineer no longer has to accept that execution belongs somewhere else.

The work after code gets cheap

When code gets cheap, software does not get easy.

The hard parts move. Understanding users becomes harder to fake. Taste becomes more visible. QA becomes more important, because the amount of code that can be produced now exceeds the amount of code anyone should trust. Architecture becomes less about preventing people from typing the wrong thing and more about preserving coherence under acceleration. Product judgment becomes load-bearing.

This is why the master builder matters more, not less.

The builder is the person who can keep asking the questions the agent cannot answer by itself:

Is this the right problem?
Is this the right shape?
Did the implementation preserve the intent?
What did we make harder by making this easy?
Where is the hidden coupling?
What would a user misunderstand?
What will break when the happy path ends?
Is this good, or merely complete?

Those questions were always part of engineering. AI makes them more central because it makes the lower layers faster. When implementation slows down, weak judgment can hide inside the schedule. When implementation speeds up, weak judgment becomes visible almost immediately.

That is good news for the kind of developer who has spent years building taste, systems sense, and ownership. It is bad news for organizations that treated those people as interchangeable implementation capacity.

The master builder was never just a ticket processor. The ticket processor is the part AI threatens most directly. The builder is the person who knows what the tickets should have been, which tickets should not exist, and what artifact the tickets are failing to describe.

Permission was the bottleneck

The deepest change is not that one person can now write more code.

The deepest change is that one person can now carry an idea farther before asking an organization to believe in it.

That changes the emotional contract of software work. A developer with a clear idea used to need permission early, because execution required resources. They needed time from other people. They needed a sprint slot. They needed a team. They needed the machinery. The idea had to survive as language long enough to earn the right to become software.

Now the idea can become software sooner.

That does not mean it deserves to ship. It does not mean it is correct. It does not mean the builder gets to ignore everyone else. It means the first artifact no longer has to wait for the full social machinery of production software to assemble around it.

This is the thing many corporate developers feel before they can name it. The meeting hurts because the artifact is now closer than the organization thinks it is. The work is waiting behind a door that used to require a team to open. The builder now has tools in their hands.

AI agents do not make developers optional. They make engineering judgment more important. They do not remove the need for teams. They remove the automatic advantage of organizational mass. They do not turn software into vibes. They give execution capacity back to the people who can already see the whole thing.

The master builder is not unleashed because the machine became smart enough to replace them.

The master builder is unleashed because the machine became useful enough to follow them.

A Framework Is Not a Platform

Viktor Lázár — Wed, 06 May 2026 18:32:23 +0000

For most of the time we have been writing web applications, two different teams answered two different questions. The framework team decided what the application looked like. The platform team decided where it ran. The line between the two questions held quietly for thirty years, and it held because nobody seriously challenged it.

Rails decided how a controller talked to a model. Spring decided how a bean was wired. Express decided what a route handler looked like. None of them decided what database, proxy, cache, message bus, CDN, or regional topology the organization bought.

That separation was not an accident. It was a property of how those frameworks were built. They produced a process. The process did its job. The infrastructure around the process — the CDN, the cache, the queue, the database, the function runtime, the regional layout — was someone else's job, and that someone else worked on a different review cycle, with different KPIs, accountable to different parts of the org chart.

The line is being erased, and the cleanest place to see it being erased is Next.js 16. Cache Components did not just change caching. They moved an infrastructure decision into a framework API.

The handshake we used to have

A Node.js web application running on Kubernetes is a clean handshake. The application produces a request handler. The platform team picks the cluster, the ingress, the CDN, the cache backend, the secrets store, the regional topology, the function runtime if there is one. They pick those things based on cost, security posture, vendor portfolio, contractual obligations, the team's existing operational expertise, and whatever standards the org has already paid down.

The framework's job, in that handshake, is to be agnostic about all of it. The same code runs behind any reverse proxy. The same code uses whatever cache the platform team chose to put in front of it. The same code can be moved between vendors without changes that touch the application's source — only the deployment surface changes, and the deployment surface is a thin layer the platform team owns end-to-end.

This is what Incremental Static Regeneration looked like in practice. A Next.js application built with ISR produced HTML files and a small revalidation loop. A CDN sat in front. The CDN served the file. Occasionally, on a stale-while-revalidate window, a function regenerated the file in the background. The shape was familiar to every CDN-fronted Node host. Vercel hosted it; Netlify hosted it; Kubernetes with Cloudflare in front hosted it; a bare VPS with nginx and a cron job hosted a recognizable version of it. The economics were similar everywhere because the architecture was platform-neutral, built from a CDN-and-function shape every platform team already understood.

That shape is what Cache Components walks away from.

What v16 changed

Cache Components, the headline feature of Next.js 16, replaces the route-segment caching model with a directive-based one. A page is dynamic by default. The developer marks regions with 'use cache' to opt those regions into caching. The framework prerenders a static shell where it can, streams the dynamic regions when they resolve, and stitches the response together at request time. Inside the page, the model is elegant. I have written about it from the directive-design angle in The Cache Belongs to the Function and will not repeat that argument here.

The argument here is not about what 'use cache' looks like to the developer writing it. It is about what the runtime requires of the infrastructure underneath, once the flag is on.

A page that uses Cache Components is, mechanically, a page whose response is produced per request by the framework's renderer, with cached fragments spliced in. In the general case, the CDN can no longer serve the full response without invoking the renderer. The static parts of the page exist as cached fragments, not as cacheable artifacts. The renderer must run, even on a request where every fragment is a hit, because the renderer is what knows how to assemble the fragments into a streamed response.

This is a small architectural change with large consequences. It moves the unit of caching from "a complete response a CDN can serve" to "a piece of a response the renderer assembles." A CDN is the infrastructure that serves complete responses. It is not the infrastructure that assembles responses from pieces. The framework, in choosing the second model, has chosen to be the assembler — which means the framework has become a piece of infrastructure that did not used to exist between the application and the CDN.

Once the framework is in the request path on every request, three secondary requirements appear, each of which used to be the platform team's choice and is now the framework's demand. A cache backend has to exist, because the default in-memory cache is per-process; in practice, the framework expects a cacheHandlers implementation pointing at a real backing store such as Redis. Tag invalidation has to be coordinated across instances, typically by refreshing a local view of shared invalidation state on the request path; in a clustered deployment, that becomes a round trip to shared storage the application did not used to make. The function runtime starts to matter in ways it did not before, because the dynamic-by-default model only amortizes its renderer cost on a platform that multiplexes concurrent requests across warm function invocations; on a platform without that, the cost is paid linearly with traffic.

None of these requirements are illegitimate as choices. They are illegitimate as framework outputs. The team did not pick Redis because it wanted Redis; the team did not put a per-request lookup on the request path because it wanted one there; the team did not select a function-runtime billing model because it had a view about how Cache Components should amortize. Redis is not the problem. The problem is when Redis stops being an application choice and becomes part of the framework's performance contract.

The escape hatches that closed

In Next.js 15, the team that wanted to keep the platform-neutral economics had options. Mark a route force-static. Enable Partial Prerendering per route with experimental_ppr. Set a route's revalidate value. Each of those decisions was visible at the route-segment level, and each one was a way for the developer to opt a route into a model the platform team's existing infrastructure already knew how to host.

In v16, with cacheComponents: true, those options are gone. The migration guide tells you to delete force-dynamic and force-static. The experimental_ppr segment configuration is removed. The revalidate and fetchCache exports are replaced by cacheLife inside 'use cache' boundaries. The route-segment escape hatches that used to let an application express "this page is static, please serve it as a file" are no longer in the API.

The flag is opt-in, today. A team that wants the v15 economics can leave it off. But the docs already treat Cache Components as the recommended path, the dedicated PPR test suites in the repository are migrating away from a separate identity, and the trajectory of any flag that the framework team owns and recommends is well-known. Within a release or two, the recommended path becomes the default. Within a release or two after that, the legacy path becomes deprecated. The ability to refuse the new model is on a clock, and the clock is the framework team's.

Technically portable, economically captive

The runtime is open source. The contract is documented. The adapters work. By the strict definition of vendor lock-in — you cannot leave — there is no lock-in. Every claim a salesperson would make about the framework's portability is true.

The honest definition of lock-in is not the strict one. The honest definition is: you can leave, but the cost of leaving is large enough to change the build-vs-buy decision. Under that definition, Cache Components introduces a soft form of capture that ISR did not have. The runtime runs anywhere; the cost-effectiveness lives on one platform. Off that platform, the same code shape produces a meaningfully worse cost profile, a meaningfully higher operational burden, and a meaningfully lower performance ceiling.

The performance ceiling is the part that is hardest to recover. On a platform that owns both the proxy and the function runtime, the static shell of a Cache-Components page can be served from the edge before the renderer is even invoked, with the dynamic stream stitched into the same response over a single connection. This is not a standard CDN primitive. It is not the contract a generic CDN signs with the application in front of it — serve a complete response, or proxy through to the origin and serve that. The handoff between a static shell and a function-produced stream, on the same connection, mid-response, is a vendor-aware proxy/runtime product. It can be built; it has not been standardized; and the team that wants it on Kubernetes is not picking it from a menu of CDN features. They are integrating bespoke pieces, or they are accepting a TTFB floor of "pod-reachable plus first render byte" instead of "edge node plus first static byte." The gap is structural, not operational.

The question is not whether another platform can build the missing machinery. The question is whether an application framework should require that machinery to recover the economics it used to preserve by default.

None of this is impossible to operate. It is only impossible to operate optimally, because the optimum has been moved to a place only one vendor lives.

The pattern, beyond Next.js

Next.js is the most aggressive case, but it is not the only framework being pulled in this direction, and the direction is the more interesting story than any one framework.

Remix and React Router 7 sit at the other end of the spectrum, partly by inheritance and partly by deliberate choice. The cache contract has historically been a headers() function on a loader returning standard Cache-Control directives. The CDN does what CDNs do; the framework does not need a backing store, a tag manifest, or a request-time invalidation hook. Whether that posture survives future product pressure is an open question, but today the cache story is platform-neutral by construction.

SvelteKit and Astro preserve the older bargain through adapters and static-first output. The application produces a generic artifact; the adapter materializes it into a deployment-specific shape only when the application has earned a dynamic runtime. The specifics stay at the deployment seam rather than seeping into the application source.

Nuxt sits in the middle. Nitro's caching primitives are function-level and storage-pluggable rather than render-coupled, so a Nuxt application can express a cached value without dragging the rendering pipeline into the request path. The framework has caching, but it has not annexed caching as infrastructure.

TanStack Start sits on a different axis altogether. It is router-and-query first, not renderer-and-cache first. Its primitives — TanStack Router, TanStack Query, server functions, loaders — describe what data should flow where, not what infrastructure should hold the cache. The cache lives with the query, function-level and storage-pluggable, the way TanStack Query has always shipped it. The framework does not need a Redis backing store, a tag manifest, or a request-time invalidation hook to be correct; the application's freshness is a property of its queries, not of the framework's renderer. It is a different architecture from Next.js, not a competing implementation of the same one.

The structural caution is general, not aimed at any one project: a framework that adopts the renderer-and-cache architecture without the matching platform machinery inherits the hard part without inheriting the economic advantage.

Some runtimes refuse this trade by construction. That is the line I have tried to hold in @lazarv/react-server — a cache primitive that lives with the function, a router that is opt-in rather than load-bearing, a deployment story handled at the build seam rather than at the source. Hono, Fastify, Express, the older Node frameworks never had this problem because they never tried to absorb infrastructure decisions in the first place. They stay frameworks because they stay small.

The point is not that every framework should look like the smaller ones. The point is that there is a spectrum, the spectrum has been visible for years, and the choice each framework makes about where to sit on it shapes the economics of every team that picks it.

What "framework" used to mean

A framework, historically, is a thing you pick up to write an application. The decision is local. The team's senior engineer reads two days of docs, the team's frontend lead does a spike, the team picks one, and the work moves forward. The decision does not require sign-off from security, platform, FinOps, procurement, or an architecture review board. It does not need to, because the framework's blast radius is the application source.

A platform is a thing you provision. The decision is organizational. It involves vendor risk review, multi-year contracts, integration with the org's authentication and observability, alignment with the org's existing infrastructure, and the long tail of "what happens if this provider gets acquired" thinking. Those reviews exist because the wrong platform decision is hard to walk back, and because the people who feel the consequences are not the same people who made the call.

When a framework's correctness and performance start to require a specific cache topology, a specific function runtime, a specific proxy behavior, the framework has crossed the category line. Picking it is no longer a local decision. It is a platform decision dressed as a framework decision, and the people who would normally weigh in on a platform decision are not in the room when it is made. The frontend lead picks Next.js because Next.js is what frontend leads pick; the cost of that choice shows up months later, in a Redis bill, in a Lambda invocation count, in a p99 graph that nobody can explain to the CFO without a paragraph of caveats.

This is the part of the trade that does not recover quickly. Money recovers. A team can switch frameworks; it is painful but bounded. What does not recover is the org's awareness that infrastructure was a thing the org was supposed to choose. The next framework that ships on the same model finds the ground already prepared. Each one normalizes the next.

The line we forgot

A framework is not a platform, and a platform should not pretend to be a framework.

The honest test for any tool wearing the framework label is the one this article has been circling. What infrastructure does it require us to operate? What is the degraded-mode cost if we don't? A tool whose answers are "your existing Node host, and roughly the same as before" is a framework. A tool whose answers are "vendor-shaped infrastructure, and meaningfully worse" is something else. It does not have to be a worse thing. It does have to be named for what it is, because the people responsible for the answers to those two questions used to be the ones making the decision.

The dev/ops handshake we used to have was not nostalgia. It was a real division of labor that let frameworks evolve without dragging infrastructure along, and let platforms evolve without rewriting applications. It let teams stay in motion. It let small projects stay small. It let large projects choose where they ran on the basis of their own constraints, not the framework's.

We are losing that division of labor one framework choice at a time, mostly without noticing, and the cost is showing up in places — bills, latency floors, operational complexity, vendor leverage — that nobody connected to the original decision back when it was just "what should we use to build the app."

A framework should be replaceable without replacing the infrastructure underneath it. Infrastructure should not become a consequence of the framework. When those two roles invert, the team has stopped owning the most important architectural surface in the system, and the framework's authors have started.

A framework is not a platform. The two have always known what they were. We are the ones who forgot.

Time to Yield

Viktor Lázár — Sun, 03 May 2026 12:10:32 +0000

An SSG benchmark across five React frameworks, from one thousand
pages to half a million.

You're building a marketplace. Or a documentation site. A wiki,
a generated archive, any of a dozen things that ship a static
catalogue at scale. Your CMS has a hundred thousand entries.
You've picked your SSG. You run the build.

Five minutes. Ten. Twenty. Maybe an hour. Maybe a stack trace.

You don't know in advance — and the public benchmarks won't tell
you. Most stop at a thousand pages, where most real catalogues
start. The gap between what gets measured and what gets shipped
is where the unpleasant surprises live, and the engineer who has
to ship into that gap usually finds out which side of it their
tool was designed for at deploy time.

So I built a benchmark for the gap.

The benchmark

Five frameworks in a pnpm workspace, each rendering one dynamic
route /posts/[id] from a shared deterministic data source. Same
content, same shape, idiomatic config per tool. The output has to
be pure deployable static HTML — no Node runtime is allowed at
request time, which is the whole point of SSG. The harness sweeps
PAGE_COUNT across 1k → 10k → 100k → 200k → 300k → 400k → 500k,
measures wall time, time-to-first-page (TTFP), peak RSS, output
size, and validates a sample of generated HTML actually contains
the right Post #N content. It's all in
bench/.

The contestants

Five different bets on what static-site generation should look
like in 2026.

Next.js (apps/next) — Vercel's framework, version 16, App
Router and Turbopack. The most-deployed React tool in the world
and the default reference point for any tooling comparison. Its
strengths are well documented elsewhere; what this benchmark
exercises is one of its many output modes — output: "export",
the fully static path with no Node runtime at request time.

TanStack Start (apps/tanstack) — the youngest entry, from
the team behind TanStack Router and Query. Vite plus a Nitro-
backed prerender plugin, file-system routing, currently in the
1.x line and rapidly evolving. Prerendering takes a materialized
pages array of paths declared inside the Vite config.

Gatsby (apps/gatsby) — the old guard. GraphQL-driven by
default, Redux-backed build cache, a sprawling plugin ecosystem,
now maintained by Netlify after acquisition. It pre-dates every
other entry here by years and has a distinct mental model:
imperative createPage calls inside a gatsby-node.mjs
lifecycle hook. People left it for Next.js partly because Gatsby
builds were slow at scale; it's interesting to find out whether
that's still the relevant fact.

Astro (apps/astro) — a static-first multi-framework site
builder. Strictly speaking it isn't running React in this
benchmark; pages are written in Astro's own .astro template
language with a fast static optimizer. It's included as the
ceiling — the answer to "how fast can a non-React SSG go?" —
against which the React-runtime entries can be measured fairly.

@lazarv/react-server (apps/react-server) —
an open React Server Components runtime built on Vite 8's
Environment API with Rolldown as the production bundler.
Disclosure: I wrote it. It's in this comparison because it's the
only React-runtime entry whose static-export pipeline accepts a
streaming path source — which, as the rest of this article will
show, turns out to be the decisive design choice.

The headline

At a thousand pages, every modern tool finishes in seconds and
the table is a wash. At ten thousand, the leaders pull a small
lead. The interesting story starts at a hundred thousand. The
decisive story starts above two hundred thousand.

I'll give you the whole thing chart by chart, but here's the
spoiler. At 100,000 pages:

Framework	wall	ttfp	output bytes
Astro	22.6s	2.18s	47 MiB
@lazarv/react-server	26.1s	1.63s	83 MiB
TanStack Start	36.9s	2.65s	172 MiB
Gatsby	62.1s	7.91s	189 MiB
Next.js	264.5s	124s	1.84 GiB

At 200,000 pages, Next.js's build crashes — exit 1, no HTML.

The chart that broke the pattern

Most benchmark charts are roughly parallel lines: the same
ranking from one page count to the next, gaps roughly constant,
nothing that asks you to stop and look. This one isn't.

react-server's TTFP is a flat line. From a thousand pages to half
a million, the time between "I started the build" and "the first
HTML file appeared on disk" stays between 1.4 and 3.2 seconds.
Astro and TanStack Start curve gently upward. Gatsby's curve
starts mid-air at 5 seconds and climbs to over a hundred. Next.js
sits between them within its working range, climbing from 2.9s at
1k pages to 124s at 100k.

What you're looking at is a single architectural decision, made
once, repeated through every layer of each pipeline. One framework
streams its work. The others batch it.

Yield, don't return

When you tell an SSG to render /posts/[id] for many IDs, it has
to ask you for the list. The shape of that question — the API your
config file uses — turns out to determine almost everything else.

Most frameworks ask you for an array.

// Next.js — apps/next/app/posts/[id]/page.jsx
export const dynamicParams = false;

export function generateStaticParams() {
  return allIds().map((id) => ({ id: String(id) }));
}

---
// Astro — apps/astro/src/pages/posts/[id].astro
export async function getStaticPaths() {
  return allIds().map((id) => ({ params: { id: String(id) } }));
}
---

// TanStack Start — apps/tanstack/vite.config.mjs
const pages = allIds().map((id) => ({
  path: `/posts/${id}`,
  prerender: { enabled: true, outputPath: `/posts/${id}/index.html` },
}));

The shape is identical: build an array, return an array. The
runtime then has to materialize that array — all hundred thousand
elements of it — before any rendering can start. The first page
of HTML cannot be written before the last entry of the path list
has been allocated.

react-server asks the same question differently:

// react-server — apps/react-server/src/pages/posts/[id].static.mjs
import { idStream } from "@ssg-test/shared";

export default async function* () {
  for (const id of idStream()) {
    yield { id: String(id) };
  }
}

It's an async generator. The router pulls one descriptor at a
time, when a render worker is free. The path list is never in
memory all at once; peak memory of the path source is O(1),
regardless of N. As soon as the first descriptor is yielded, the
first page can render. As soon as the first page renders, it lands
on disk. The rest of the build is just keeping the workers fed.

The runtime documents this contract explicitly at
react-server.dev/router/static#streaming-static-paths
— and the detection is by function kind: write async function* directly as the default export, or fall back to the
legacy array contract. There's no opt-in flag. The shape of your
function is the shape of the build.

You can chain the same idea at the config level, which is what the
benchmark does to skip RSC payload sidecars (the other frameworks
emit HTML only; we want the bytes column to compare like with like):

// react-server — apps/react-server/react-server.config.mjs
export default defineConfig({
  root: "src/pages",
  async *export(paths) {
    for await (const p of paths) {
      yield { ...p, rsc: false };
    }
  },
});

Two async function* shapes — one in the route, one in the
config. The whole streaming property of the build comes from
those two declarations. Look at the TTFP chart again with this in
mind: react-server is renderer-bound; everyone else is array-bound.

Things start to fall apart at a hundred thousand

If TTFP is the early-warning signal, total wall time is where the
architecture pays its real bill.

At a thousand pages, every framework here finishes in single-digit
seconds and you'd struggle to feel the difference in a CI log. The
slope of the curves is what matters, and the slope diverges hard
above ten thousand.

By a hundred thousand pages, react-server has finished in 26
seconds. Astro, the leader, in 22.6 seconds. TanStack Start
in 37. Gatsby in just over a minute.

Next.js takes four and a half minutes.

For the same work. Same content, same hundred thousand pages on
disk. Next.js's curve is steeper than linear above 50k pages, and
by 100k the wall time is into the "go for a coffee" territory
that distinguishes a benchmark from a real engineering decision.

The other notable result at this scale: at 100,000 pages, Gatsby
finishes faster than Next.js. 62 seconds versus 264. Gatsby
has a long-standing reputation for slow builds at scale, and
that reputation isn't unfair, but on this specific workload it
crosses the line first. The framework people moved off of for
build performance is now, on this measurement, the faster of
the two.

The same data reads sharper as throughput: pages produced per
second, the per-page work each framework does once it's warmed
up.

The four frameworks that complete the workload all reach a
plateau somewhere above ten thousand pages — a steady-state
pages-per-second ceiling that holds up the rest of the way.
@lazarv/react-server runs around 3,000–3,800 pages/s; Astro
3,000–4,400; TanStack Start 1,900–2,700; Gatsby 1,500–1,700.
The plateaus tell you how much overhead each framework has
amortized away once the build is steady.

Next.js never reaches a plateau. Its throughput peaks at 480
pages/s at 10k, drops to 378 pages/s at 100k, and crashes before
it can be measured at higher counts. The build is doing more
work per page as the page count grows — the opposite of what
amortization should produce. That trajectory is what makes the
next section's failure mode predictable in retrospect: a
pipeline whose per-page cost is increasing was always going to
hit a ceiling.

The wall

Then I cranked the count to two hundred thousand.

The build crashed.

RangeError: Maximum call stack size exceeded
    at ignore-listed frames

> Build error occurred
Error: Failed to collect page data for /posts/[id]
    at ignore-listed frames {
  type: 'Error'
}

Three seconds of CPU. No HTML. Exit code 1. Next.js's "collect
page data" phase — the step that runs after Turbopack compiles
your app and before the worker pool starts rendering — overflows
V8's call stack.

I bumped to 300k, 400k, 500k. Same crash, every time. The error
itself is forthright: stack overflow, here's the phase. What the
error can't tell you is that the input the pipeline cannot handle
is your own page list, and that there is no flag in next.config
to ask for a different consumer of it.

A RangeError: Maximum call stack size exceeded is a recursion
fingerprint. Something in Next's pipeline is walking the params
array via naive recursion — JSON-serializing it, normalizing it,
hashing it for the data cache, building a tree from it, take your
pick — with recursion depth proportional to the array length
itself, not to its log. (A balanced-tree traversal would push
log₂(200,000) ≈ 18 frames; nowhere near a stack limit. The
overflow only makes sense if each entry contributes a constant
share of frames.) At 100k entries the depth still fits inside
V8's default ~10k-frame stack. At 200k it doesn't.

This is not something --max-old-space-size=8192 can fix (we
tried). It's not a memory issue at all. It's an algorithmic
ceiling: Next.js's page-data collection is implemented as
recursive traversal over the materialized params array, and that
recursion has a depth limit baked into the JavaScript engine. You
cannot grow your way past it. There is no flag because there is
no scalar to turn.

The runtime requires the array contract — generateStaticParams
must return one — and the pipeline that consumes it cannot tolerate
arrays past a certain size. Both halves of that statement are
architecture, not bugs.

react-server, on the same hardware, with the same content, spent
155 seconds on five hundred thousand pages. First HTML on
disk: 2.87 seconds. The same TTFP it has at a thousand pages.
Nothing in its pipeline ever sees a 500,000-element array, because
nothing in its pipeline is allowed to construct one.

What's actually in the output directory

If the wall time is the loud problem, the output bytes are the
quiet one. At 100,000 pages:

Astro emits 47 MiB.
react-server emits 83 MiB.
TanStack Start emits 172 MiB.
Gatsby emits 189 MiB.
Next.js emits 1.84 GiB.

At 100k pages, the deployable Next.js output is roughly forty
times larger than Astro's and twenty times larger than react-
server's. The bulk of it is per-page files: a .txt RSC payload
sidecar for every route, used to power client-router prefetch on
navigation, plus a runtime bundle the page links to for hydration
even on routes without "use client".

Both files are part of the App Router's contract: the .txt
payload exists so the client router can prefetch, the runtime
exists so client components can hydrate. They're features of the
deployment topology Next.js is designed for. The trade-off, when
the deployment is fully static and no client component is ever
going to run, is that the contract still ships. There's no
documented flag to drop either for output: "export".

react-server makes the equivalent choice in the opposite
direction: emit HTML only by default for fully static export, and
let the user opt back into RSC payload sidecars per path if they
want them. The benchmark's config-level export() hook tags every
yielded path with rsc: false to keep the bytes column comparing
HTML to HTML.

Memory: where Gatsby still hurts and @lazarv/react-server stays quiet

The memory chart is shaped a lot like the wall chart, with one
outlier: Gatsby. Gatsby's build cache is a Redux store that
appends every createPage call into in-memory state, and it never
sheds that state until the build finishes. At 500k pages, Gatsby's
peak resident set hits 9.55 GiB. Long-time Gatsby users will
be unsurprised; this is what gatsby build has always done.

react-server holds between 1.2 GiB at a thousand pages and 2.6
GiB at half a million — essentially flat above 10k. TanStack
Start ranges from 600 MiB at 1k to 3.6 GiB at 400k before
nudging back down to 3.1 GiB at 500k. Astro is the leanest of all
at 0.6 to 1.8 GiB across the same range.

The streaming path source is one reason react-server's memory
curve flattens. The bigger reason is what it doesn't accumulate:
no per-route manifest, no fingerprinted asset graph for every
page, no client-router prefetch index. Whatever doesn't exist
doesn't take memory.

A note about Astro

Astro is the fastest tool in this benchmark. It deserves the
credit, with one important asterisk: Astro isn't running React.

In apps/astro/src/pages/posts/[id].astro, the page is written in
Astro's own template language. There's no React reconciler, no
hydration framework, no Server Components flight protocol — it's
closer to JSX-flavored server-side templating with a fast static
optimizer. Astro is the right ceiling for "what can a static-
site generator do at all," but it isn't an apples-to-apples
comparison with React-runtime tools.

Which makes the next sentence the actual story.

@lazarv/react-server matches Astro. Within ~15% on wall time
at 100k (26s vs 22.6s), and faster on TTFP (1.63s vs 2.18s). And it
does this while running the actual React Server Components
production server — the same one a deployment would serve at
request time, bundled by Vite 8 and Rolldown, driven by a
streaming path source. The HTML on disk after the export is the
HTML the production server would have produced for a real
request. A real React runtime moving at static-template-engine
speed.

That isn't a result you get by accident.

Why this works

A React Server Components runtime keeping pace with a static-
template engine doesn't happen because someone optimized a hot
loop. It happens because the architecture has fewer places for
work to pile up. Five things contribute, and none of them are
clever; they're all just the absence of unnecessary buffers.

The build phase produces a real production server. Vite 8 and
Rolldown bundle the runtime exactly as it would run at request
time; the static export then starts that bundled server and asks
it to render each yielded path. The thing that produces your HTML
during the export is the same thing that would serve your HTML if
you weren't exporting. There is no separate build-only renderer,
no compile-time-only sandbox, no special static-export pipeline
running its own copy of half the framework. Whatever the
production server can render at request time, the export can
produce. Two phases — bundle, then render — but the second phase
is the production server you'd deploy, not a parallel universe
of build-time machinery.

The static path source streams by contract. Both [id] .static.mjs and the config-level export() are async function*
shapes that the router pulls from. Memory of the path source is
O(1). Rendering can start on the first yielded path.

Render workers are driven by the stream. The
--export-concurrency flag forks N child processes; each runs its
own RSC main thread plus an SSR worker thread; the coordinator
dispatches one path per free worker. Output bytes never cross the
IPC boundary — every artifact (HTML, optional .gz / .br
sidecars, postponed-fragment cache) is written to disk inside the
child. There is no central "collect page data" buffer because
there is no central buffer.

There is no per-page runtime tax. Pages without "use client"
get pure HTML. The runtime doesn't inject bootstrap scripts,
doesn't write _buildManifest.js, doesn't emit per-page payload
sidecars unless you ask. The 22× output-size delta vs. Next.js
collapses to: emit only what the page needs.

And there is no extra compiler in the path. No Turbopack-
style parallel compiler stack, no SWC custom plugins, no static-
build renderer that's a different runtime from the production
server. Vite 8, Rolldown, Node, JavaScript — and the runtime
itself. Phase 2 is just the runtime. Fewer moving parts than its
peers, which is precisely why fewer of them break at scale.

What this means if you have to pick

If you have a thousand pages, all of these tools work. The
differences are noise. Pick on developer experience.

If you have ten thousand, Next.js is already five times slower
than the leaders. Worth knowing before your next pitch deck.

If you have a hundred thousand:

Astro is the fastest if you don't need React.
@lazarv/react-server is the fastest React runtime that completes the workload, on par with Astro while running RSC end-to-end, with the smallest HTML-only output of any React option.
TanStack Start completes but loses time to the materialized pages array.
Gatsby completes, slowly, with high memory.
Next.js completes but takes about ten times as long as the leaders and emits roughly twenty times the bytes; both numbers follow from defaults that aren't configurable away in the output: "export" path today.

If you have two hundred thousand pages or more of pre-rendered
routes — a CMS-backed catalogue, a docs archive, a programmatically
generated index — Next.js's static-export pipeline does not
complete. The build crashes with a RangeError: Maximum call stack size exceeded during page-data collection. The failure is
recursion depth in V8, not heap size, so it isn't fixable by
flags or environment variables. The right framing is that
output: "export" at this scale isn't a supported topology for
Next.js — its answer for catalogues this large is ISR, which is a
different topology, which is the next section.

But what about ISR?

Whenever the sentence "Next.js can't pre-render two hundred
thousand pages" appears in public, someone responds: just use ISR.

Incremental Static Regeneration is Next.js's answer to large
catalogues. Don't pre-render every page at build time. Build the
app shell, deploy it, and have the runtime generate each page on
first request and cache the result. A revalidate: N knob handles
freshness. On Vercel it works well; on a Next.js-aware host it
mostly works.

For a strictly static deployment, it doesn't work at all.

The unspoken word in "Incremental Static Regeneration" is
the regeneration, and regeneration requires a runtime. ISR turns
your "static site" into an HTTP server that lazily produces HTML
on the way to the browser. If your deployment target is a CDN
that only serves files — GitHub Pages, S3 + CloudFront, an nginx
in front of a directory, Cloudflare Pages without a Worker, the
static-files product on Netlify, an air-gapped intranet, the
classic shared-hosting plan your client insists on — there is no
runtime for ISR to run on. The feature isn't degraded, it's
missing.

This is the case the benchmark was designed for: pure static HTML
plus assets, no Node runtime at request time. All five tools in
the comparison advertise themselves as supporting that mode. The
point of measuring at 100k+ is to find out whether the advertised
mode survives at the scale a real catalogue produces. ISR doesn't
enter the comparison because it isn't the same product — it's a
different deployment topology that swaps a build-time problem for
a request-time one. Both are valid; they aren't interchangeable,
and the trade-offs should be visible to whoever signs off on
hosting cost, security posture, or operational surface area.

Three concrete consequences of that swap, worth knowing before
reaching for ISR as a workaround:

The first visitor to every page pays the bill. A hundred
thousand product pages and a hundred thousand unique long-tail
visits over a quarter mean each visitor is the unlucky one for
exactly one page. Cold start plus render time plus cache write —
typically a hundred milliseconds to a few seconds, depending on
the page. A static export amortizes that work into one build. ISR
amortizes it into one hundred thousand request-time renders, each
on the critical path of someone's pageview.

You are now paying for compute you weren't paying for. A
static site sits on CDN edge cache and costs essentially nothing
above bandwidth. ISR requires a serverless function (or a long-
running process) that's billable per invocation and per millisecond
of execution. The bigger the catalogue, the more pages enter the
"never visited" tail and the more compute you allocate for HTML
that nobody reads.

Cache invalidation enters your application's design. ISR's
freshness story is revalidate: N plus on-demand revalidation
hooks. Both are reasonable, both are concepts your team now has to
think about, and both are operational surface area that didn't
exist when the deployment was files in a directory. For sites
whose content really doesn't change often, this is purely added
complexity.

And there's a subtler point. ISR doesn't fix the underlying
build ceiling. If you mark some routes as fully pre-rendered
via the array contract — dynamicParams: false, generateStatic Params returning the full set — you're back in the recursion-
overflow territory from earlier in this article. ISR side-steps
the wall by routing around it. It doesn't move the wall.

None of this makes ISR a bad feature. It makes ISR an answer to a
different question. "How do I serve a hundred thousand pages
without paying for a build that materializes them all" is a real
problem. "How do I generate a hundred thousand pages of pure
static HTML to a CDN" is a different real problem. You don't
solve the second with the answer to the first.

react-server, Astro, TanStack Start, and Gatsby answer the second
one. Next.js, in its output: "export" mode, scales to about
150,000 pages and is designed around ISR for the rest.

The contract is the product

@lazarv/react-server didn't win this benchmark with new
technology. The runtime is Node. The bundler is Vite 8 with
Rolldown. The API is async function* — a primitive that's been
in JavaScript engines since 2018. There's nothing in the build
pipeline you couldn't have shipped seven years ago.

What's novel is choosing it.

Most of the React ecosystem has spent the last half-decade
optimizing the wrong layer. The renderer is fast everywhere. The
worker pool is fast everywhere. The compiler — Turbopack, SWC,
take your pick — is fast everywhere. The bottleneck at scale
turns out to be one decision made at the top of your route file:
does the path source return, or does it yield? And the only
way to fix the bottleneck is to change the contract. Nobody else
has.

generateStaticParams returns an array. getStaticPaths returns
an array. TanStack Start's pages is an array. Gatsby's
createPage is an array smuggled in through a loop. Every layer
downstream of those APIs is forced to assume the worst case lives
in memory at once. At a thousand pages the assumption costs
nothing. At a hundred thousand it costs minutes. At two hundred
thousand, in Next.js, it costs the build — RangeError: Maximum call stack size exceeded, exit one, zero pages produced.

react-server's [id].static.mjs doesn't return anything. It
yields. The renderer pulls. Memory of the path source is O(1).
N is unbounded. The build is the same shape at a thousand pages
as it is at half a million, because the architecture has nothing
that grows with it.

If you are picking an SSG in 2026 and your roadmap has more than
ten thousand pages in it, look at the path-list API before you
look at anything else. The framework that lets you yield will
scale with your content. The framework that asks for a return
will, eventually, give you back an empty out/ directory and a
stack trace.

This isn't really a Next.js problem. It's a generation-of-tooling
problem. Static-site generation at scale has been treated as a
build-pipeline optimization for years. It isn't. It's an API
design problem, and the API is the array.

Change the API. Yield, don't return.

It's time.

The full benchmark is open source. apps/ for each
framework's setup, bench/ for the harness, and
bench/REPORT.md for the complete table. To
reproduce: pnpm install && pnpm bench:sweep && pnpm report && pnpm chart.

Disagreements welcome

I wrote @lazarv/react-server. The disclosure is at the top of
the article, and I built the bench to keep the comparison honest
despite it — same content per route, fastest successful run wins
per cell, sample HTML validated per build, failed cells reported
as failed rather than dropped, every framework's idiomatic
configuration used as documented. I believe the comparison is
fair.

But I'm one person reading my own benchmark. If you spot a flag
I should have set, a version I should have tried, an inadvertent
advantage I've handed @lazarv/react-server — open an issue or
send a PR. The harness is in bench/, the apps are in apps/,
and any change that produces a fairer comparison wins.

If the data lands somewhere different in your read than in mine,
that's the conversation worth having. I'd rather the article get
the technical story right than win an argument.

A Low Floor Is Not a Low Ceiling

Viktor Lázár — Fri, 01 May 2026 18:58:19 +0000

There is a moment at the beginning of using a framework when the framework tells you what kind of developer it thinks you are.

It rarely says this directly. It says it by what it asks of you before your own idea is allowed to appear. It says it through the scaffold it generates, the folders it names, the configuration files it creates, the conventions it assumes you already understand, and the amount of system you must accept before the smallest useful program can run.

This first moment matters because it defines the emotional shape of the tool. Some systems begin with a primitive: a function, a component, a request handler, a file. They let the idea arrive first and allow structure to grow around it. Other systems begin with an institution. Before there is behavior, there is a project. Before there is a program, there is a topology.

We have become used to this, especially in frontend development. A new app is expected to be born as a tree. It has routing before it has routes, build configuration before it has a build problem, lint rules before it has a team, deployment assumptions before it has users, and a package graph before it has a reason to exist. Each piece may be defensible on its own. The problem is not that any one file is absurd. The problem is that the smallest idea is asked to carry the shape of a much larger future.

That is a strange bargain. It is especially strange now, because the two kinds of developers most exposed to the beginning of a system, beginners and AI agents, are exactly the two least able to separate essential shape from accumulated ceremony.

What experts stop seeing

Experienced developers have a skill we do not talk about enough: selective blindness.

We can open a repository and immediately reduce its apparent size. We know that some files are behavior, some files are policy, some files are boilerplate, some files are generated, and some files are present only because a tool once needed a place to write down its preferences. We know when a folder name is meaningful to the framework and when it is merely organizational. We know when a config file is actively shaping the program and when it is an artifact of the scaffold.

This is not the same as simplicity. It is familiarity doing compression.

A beginner does not have that compression. When they open a scaffolded project, the entire tree arrives with equal authority. Every file might matter. Every convention might be something they are already supposed to know. Every import, suffix, folder, generated type, and default export might be part of the lesson. To an expert, the surrounding machinery is background. To a beginner, it is the room.

That changes what the first lesson becomes. Instead of learning that a program is an idea made executable, the beginner learns that software begins inside a prepared environment whose rules are not yet visible. They learn that making even a small thing requires standing in the correct place, naming files correctly, accepting the correct project shape, and trusting that the framework will interpret the structure as intended.

Some of that knowledge will eventually be necessary. But "eventually" is the important word. The first encounter with a tool should not require the learner to distinguish core concepts from scaffolding residue. A good beginning should bring the irreducible thing close: data becomes UI, input becomes state, a request becomes a response. Architecture should arrive as a way to preserve clarity as the program grows, not as the admission price for writing the first line.

The agent has the same problem

AI agents make this problem visible in a different way. They are not beginners in the usual sense; they have absorbed patterns from more code than any human will read. But when an agent enters a particular repository, it does not bring the local memory of the team. It does not know which conventions are intentional, which are obsolete, which are inherited from the starter template, and which are workarounds nobody likes but everyone is afraid to remove.

The agent has to discover the system by reading it. That sounds obvious, but it changes the economics of ceremony. What used to be a one-time human annoyance at project creation becomes a recurring cost paid on every AI-assisted change. The model must spend attention on the filesystem, the dependency graph, the framework conventions, the version-specific behavior, and the shape of the surrounding setup before it can safely reason about the user's request.

It is tempting to reduce this to token count. More files mean more tokens; more tokens mean more cost. That is true, but it is the least interesting part. The deeper issue is that tokens do not all have the same semantic weight. In a real project, some text defines behavior, some configures behavior, some describes behavior that used to exist, some is framework glue, and some is simply the fossil record of how the project began. A human teammate can often point at a file and say, "ignore that." The model has to infer it.

This is where bloated systems become dangerous for AI. They do not merely give the model more to read. They give it more ways to be plausibly wrong. It can follow a pattern that exists in the repository but no longer represents the intended direction. It can apply a framework rule from the wrong version. It can miss that a file path changes rendering mode, or that a cache option interacts with a parent segment, or that a wrapper exists only because a previous tool could not express the smaller thing directly.

The beginner asks, "where do I put the code?" The agent asks the same question in another form: "which of these tokens are the program?"

Systems with too much ceremony answer both questions poorly.

Code size is a reasoning surface

We often talk about code size as if it were a maintenance problem that appears after the fact. The project gets larger, so it becomes harder to maintain. That is true, but it misses the more immediate effect: code size changes the way a system can be understood.

A small program can be held in the mind. You can read it and keep the whole shape present: inputs, outputs, state, effects, and failure modes. As the program grows, understanding has to move through supports: names, tests, types, boundaries, conventions, documentation, and trust. Those supports are necessary, but they are not free. Each one helps organize the system while also becoming another surface on which a wrong assumption can land.

The growth is not linear because the problem is not only the number of lines. It is the number of relationships between them. A route can interact with a layout, a cache rule, a bundling boundary, a server/client split, a deployment target, and a default inherited from somewhere the developer is not currently looking. A config file can change the meaning of a component that does not mention it. A directory name can affect runtime behavior even though it looks like organization.

At small sizes, adding code mostly adds capability. At larger sizes, adding code increasingly adds interaction. The surface the next change has to cross becomes wider, less local, and harder to see at once. That is the familiar moment when a small change stops being small because the system around it must be understood first. You want to add a button, but first you need to know whether it belongs on the client. You want to move data fetching, but first you need to know which cache owns freshness. You want to simplify a file, but first you need to know whether the filename itself is an API.

For humans, this becomes onboarding time, superstition, fatigue, and the slow accumulation of "don't touch that" knowledge. For AI agents, it becomes larger prompts, weaker locality, pattern matching where understanding should be, and edits that are syntactically reasonable but semantically misplaced.

This is why "use a bigger context window" is not a complete answer. A bigger context window lets the model carry more of the maze. It does not tell us whether the maze needed to be there.

The toy path is not kindness

Once the weight of modern tooling becomes visible, the obvious solution is to give beginners something smaller. A simpler framework. A reduced mode. A teaching tool. A toy environment with fewer concepts and fewer ways to get lost.

Sometimes this is useful. Teaching often requires choosing a smaller surface. But as an architectural answer, it fails if the small path is not part of the same world as the large path. If the beginner learns one model and then has to abandon it when the application becomes real, the simplicity was not a doorway. It was a waiting room.

The same is true for small projects. A tiny internal tool should not have to choose between a toy framework that will be outgrown and a production framework that arrives already bloated. A prototype should be allowed to be real. A first file should be allowed to become the first file of the final system. The path from "almost nothing" to "something serious" should be continuous.

This is the part that is easy to miss: beginners do not need worse tools. They need real tools with lower entry points.

If the only way to make a framework approachable is to remove its power, then the framework has not solved approachability. It has outsourced it to a different tool. A better framework shape lets the same primitive participate at multiple scales. The first component is not a demo artifact; it is a legitimate member of the system. The first route is not a special tutorial mode; it is the smallest case of the routing model. The first cache is not a global doctrine; it is a local decision next to the computation it affects.

A low floor is not a low ceiling. In the best systems, the low floor is evidence that the ceiling is supported by real structure rather than by ceremony.

Almost nothing should work

There is a design principle hiding here that sounds more radical than it is: almost nothing should work.

A single file should work. A single component should work. No configuration should work. No router should work until there is more than one place to go. No cache policy should exist until freshness has become a question. No deployment adapter should change the meaning of the application before deployment is actually being discussed.

Absence should be a valid state of the system.

This is not minimalism for its own sake. It is maintainability in its most practical form. A file that does not exist cannot go stale. A wrapper that was never extracted cannot become a place where names drift. A configuration key that was never introduced cannot be copied into the next project without understanding. A convention that was never required cannot become folklore. The strongest abstraction is often not the clever one, but the missing one.

Frameworks are usually better at adding capabilities than at preserving absence, because capabilities are easier to demonstrate. A router can be documented. A cache layer can be benchmarked. A deployment adapter can be announced. "You do not have to think about this yet" is harder to turn into a feature page, even though it may be the most important feature for the first hour, the first week, and every AI agent session after that.

The discipline is not to avoid power. The discipline is to delay power until the problem asks for it. Configuration is good when it changes something the developer has chosen to care about. Project structure is good when the project has enough internal gravity to need one. Defaults are good when they remain defaults. They become bloat when they appear before the program has earned them and then pretend their presence is neutral.

Scaling downward

We usually use "scalable" to mean that a system can grow upward. More users, more routes, more teams, more data, more features, more deployment targets. That kind of scale matters, and a framework that cannot grow upward will eventually trap serious applications.

But there is another kind of scale that is just as important: a system must scale downward.

It must scale down to one file, one component, one endpoint, one idea tested before lunch. It must scale down to the beginner trying to see the whole program at once. It must scale down to the AI agent trying to make a narrow change without reconstructing the entire framework context first. A system that scales upward but not downward is not truly scalable. It is only large-capable.

This distinction changes how we judge architecture. The question is not only whether a framework can host an enormous application. The question is whether it can host a tiny one without making it pretend. Can the smallest useful program be written directly? Can it grow by adding concepts one at a time? Can each new layer explain itself by answering a pressure already present in the code?

That is what a grown-up framework should feel like. At the beginning, most decisions should be not yet. Not yet a routing tree. Not yet a cache hierarchy. Not yet a deployment-specific semantic. Not yet a global configuration file. Just the program. Then, when the program needs a second page, routing appears. When it needs shared structure, layout appears. When it needs data freshness control, caching appears next to the data. When it needs background isolation, a worker boundary appears around the work. When it needs deployment specificity, an adapter appears at the edge rather than changing the meaning of the center.

Each new concept should feel like a door opening from the room you are already standing in.

The same world

The deepest mistake is believing that beginners, experts, and AI agents need different worlds. They do not. They need different distances from the same center.

The beginner needs to stand close to the irreducible idea, where the relationship between code and behavior is visible. The expert needs to move outward into power, performance, specificity, and control without being trapped by the framework author's fixed menu. The AI agent needs the same locality both of them need: code whose meaning is present in the text before it is hidden in conventions that must be inferred.

These are not competing requirements. They are the same architectural requirement seen from different heights.

Make the primitive honest. Make the first step real. Make absence valid. Make defaults optional. Make every layer replaceable when it finally appears. Let the small thing belong to the same world as the large thing. Then the beginner is not trapped in a toy path, the expert is not trapped in a convention path, and the agent is not trapped in a fog of scaffolding.

We should stop admiring systems merely because they can host enormous applications. That is only one kind of strength. The more interesting strength is the ability to be gentle with beginnings: to let an idea exist before it has proved that it deserves architecture, and to let it grow without exile.

A serious framework should be able to hold almost nothing.

And if the idea grows, it should not have to leave home.

A Function Should Know Where It Runs

Viktor Lázár — Thu, 30 Apr 2026 10:27:03 +0000

There is an obvious appeal to a server function you can call from anywhere. The old version of the same idea was not pleasant. You wrote an endpoint, then a client helper for that endpoint, then some shared schema to keep the two sides honest, then error handling in both places, and eventually a small pile of files whose main job was to move one value from the browser to the server and another value back again.

So when a framework lets you write the server part as a normal function and call it as a normal function, it feels like the right kind of progress.

export const getUser = createServerFn().handler(async () => {
  return db.user.findCurrent()
})

Somewhere else:

const user = await getUser()

This is much nicer than wiring an endpoint by hand. The function is typed. The caller is typed. Refactors have a path through the codebase instead of disappearing into a string URL. For a lot of application code, especially small reads and mutations, this is exactly the kind of boilerplate a framework should remove.

The question is not whether the API is useful. It is. The question is what gets hidden when the call becomes this smooth.

The same call is not always the same operation

await getUser() can mean slightly different things depending on where it appears. If the call happens while the application is already running on the server, it can be a direct path into server code. If it happens in the browser, it has to become a request. If it happens in a route loader, it belongs to the router's data lifecycle. If it happens after a click, it belongs to an interaction that the user is waiting on.

Those cases can all share the same TypeScript signature, but they are not the same situation. The value that comes back may have the same shape; the act of getting it does not.

That is the part of isomorphic server functions that makes me uneasy. The abstraction removes a lot of code nobody wanted to write, but it also makes the call site less descriptive. The line looks ordinary in places where the operation behind it may not be ordinary at all.

What TanStack makes pleasant

TanStack Start leans into this trade quite naturally. A server function is explicit when it is defined, and then the exported value is designed to be called from the places where application code tends to need it: loaders, components, hooks, event handlers, other server functions. That fits the rest of TanStack's style. The router is central, the data flow is typed, and the application is assembled out of explicit functions rather than a large menu of special filenames. If that is already the way you want to build, the server function API feels consistent.

There is nothing dishonest about the definition site. createServerFn() tells you that the handler is server code. It can touch a database. It can read secrets. It can do work the browser cannot do. The ambiguity appears later, when the call has been made deliberately ordinary.

That ordinariness is useful while you are writing the code. You know where you are. You know whether the call is inside a loader or inside a button handler. You know what the framework is going to do. The problem shows up later, when the code is read without all of that context already loaded into someone's head.

A small refactor changes the role

Imagine a settings page that starts like this:

export const Route = createFileRoute("/settings")({
  loader: () => getUser(),
  component: SettingsPage,
})

Later, someone adds a refresh button inside the page:

async function refresh() {
  const user = await getUser()
  setUser(user)
}

Both calls are reasonable. Both may be exactly what the application wants. But they are not playing the same role anymore. The first call belongs to navigation. The second call belongs to an interaction after the page is already on screen. It has a different timing, a different failure shape, probably a different loading state, and possibly a different relationship to invalidation.

Nothing about getUser() is wrong here. The issue is that the call is too polite to mention that its role changed. The code moved from one part of the application to another, and the most important difference is now carried by the surrounding framework context rather than by the expression itself.

Types do not carry place

Types do not really solve this. They solve an important part of it, but not this part. Promise<User> tells me what value I will eventually get. It does not tell me why I am waiting. It does not tell me whether the delay is a database query in the same process or a request from the browser to the server. It does not tell me whether cookies are involved, whether middleware runs, whether a rate limit can trip, or whether the user is now staring at a disabled button.

All of those things can live behind the same return type.

What RSC keeps visible

This is where React Server Components come from a different direction. RSC does not try to make server code and client code feel like the same kind of code. It lets them participate in the same React tree, but it keeps their environments distinct. Server Components run on the server. Client Components run in the browser. Server Functions are server code that can be referenced across the boundary.

The same settings page has a different shape in that model:

export default async function SettingsPage() {
  const user = await getUser()

  return <SettingsForm user={user} refreshUser={refreshUser} />
}

async function getUser() {
  return db.user.findCurrent()
}

async function refreshUser() {
  "use server"
  return db.user.findCurrent()
}

"use client"

export function SettingsForm({ user, refreshUser }) {
  const [currentUser, setCurrentUser] = useState(user)

  async function refresh() {
    setCurrentUser(await refreshUser())
  }

  // ...
}

There is more ceremony here. The client piece has to be named. The server function has to be passed across the boundary. Depending on the framework, this may also mean another file. But the roles are visible in the shape of the code: the initial read belongs to the Server Component, and the later refresh is a client interaction calling a Server Function.

The split does not necessarily have to be a file split. With function-level boundaries, the same idea could live much closer to the place where it is used:
export default async function SettingsPage() {
  const user = await getUser()

  function SettingsForm() {
    "use client"

    const [currentUser, setCurrentUser] = useState(user)

    async function refreshUser() {
      "use server"
      return db.user.findCurrent()
    }

    async function refresh() {
      setCurrentUser(await refreshUser())
    }

    // ...
  }

  return <SettingsForm />
}
That is the argument in The "use client" Tax: the boundary should stay visible, but it should be allowed to live closer to the code it describes.

The current ergonomics of that model are not perfect. Next's file-level "use client" boundary creates real friction, and small interactive pieces often end up in files that exist mostly because the bundler needs a module boundary. That is not a minor annoyance; it changes how code is organized. But the underlying idea is still important: a piece of code should communicate where it belongs.

When something is server code, the reader should be able to expect server capabilities. When something is client code, the reader should be able to expect browser capabilities. When a value or reference crosses from one side to the other, the model should have a visible place for that crossing. Not because visible boundaries are beautiful in themselves, but because hidden boundaries tend to come back later as surprises about latency, failure, serialization, or state.

This is the difference I care about between the two approaches. With an isomorphic server function, the definition says "server", but the call site tries to feel universal. With RSC, the model keeps insisting that server and client are different places, even when they are composed together.

The boundary should be cheap, not invisible

I do not think the answer is to give up the convenience of server functions. Hand-written endpoints are not some lost paradise. A framework should make it cheap to invoke server code from the client, and TanStack's version of that idea is useful. The part I would be careful with is the framing. There is a difference between "this is server code with a convenient client invocation mechanism" and "this is just a function you can call from anywhere."

The first framing keeps the boundary in the reader's mind. The second makes the boundary feel incidental until some operational detail forces it back into view.

That is not just a matter of taste. It becomes a real maintenance problem.

It shows up in code review, when a harmless-looking call has moved from a loader into an event handler and the diff does not make the change feel as large as it is. It shows up in debugging, when a line that reads like a function call fails like a network interaction. It shows up in refactors, when moving code across an invisible boundary changes timing, failure, and user-visible behavior without changing the expression that caused it.

That is why I find the RSC direction healthier, even with its current rough edges. The goal should not be to make every server call dramatic. It should not be to reintroduce ceremony for its own sake. It should be to make the boundary cheap enough that we can keep it visible without resenting it.

A function does not need to shout where it runs. But if understanding the function requires knowing whether it is local code, server code, or a request in disguise, then that fact should not live only in the reader's memory of the framework. Once the boundary is invisible at the call site, every reader has to rediscover it later.