DEV Community: Viktor Lázár

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.

The Cache Belongs to the Function

Viktor Lázár — Wed, 29 Apr 2026 09:38:00 +0000

A few years ago, the question about caching in modern web frameworks was whether it should be on by default. That question is largely settled. Frameworks that defaulted to caching every fetch and rendering every page statically have walked the defaults back; frameworks that didn't, didn't have to. The argument that caching should be opt-in, and that the developer should be the one who decides where it pays, has won. Anyone arguing it today is arguing against a position the industry has already conceded.

What is not settled is where the caching primitive lives. The directive that marks a function as cacheable can be implemented in two structurally different ways, and the difference is not yet obvious to most of the people writing code that uses it.

The first design treats "use cache" as a marker on a function. The function carries its own caching contract. Wherever the function runs — on a server, on the edge, in a worker, in a browser — the directive means the same thing. The cache is a property of the function.

The second design treats "use cache" as a marker on a region of a rendering tree. The function exists, the directive is on it, but the cache machinery underneath is part of the framework's rendering pipeline. The cached output is a streaming shell that the framework stitches into a partially prerendered response, with dynamic holes carved out of it by <Suspense> boundaries. The cache is a property of how the page is built.

Both designs are coherent. Both are reasonable answers to a real engineering problem. They are not the same answer. This article is for the first one.

What was settled, and what wasn't

A short reset on the territory is worth the paragraph.

The case against default caching used to be obvious to anyone who had shipped a production application: you spend more time disabling the cache than enabling it. Routes get marked dynamic. Fetches get cache: 'no-store'. Layout segments get tagged force-dynamic. The defaults were calibrated for a population of pages where staleness is cheap and slowness is expensive, and most production applications are not that population. Every site that mattered ended up annotating its way out of the default.

The frameworks that shipped this model heard the criticism and inverted the defaults. In Next.js 15, fetch is no longer cached, segments are no longer static. The dynamicIO mode introduced "use cache" as the primitive a developer reaches for when caching actually pays. Inside that mode, uncached is the baseline; cache only what you mark. This is the design the critics asked for. They got it.

So when this article talks about what a caching primitive should look like, it is not arguing against caching by default. The default is gone. The argument that survives is about what the primitive in its place is made of.

Two places the cache can live

A caching primitive has to live somewhere. The two structural choices are with the function and with the renderer.

A cache that lives with the function is portable. It travels wherever the function travels. The directive is a contract between a function and a runtime; any runtime that understands the directive can honor it; any runtime that does not, ignores it and runs the function. The cache key is the function's inputs. The cache value is the function's output. Nothing about the surrounding system needs to be present for the cache to work, because the cache is the function's contract with its host.

A cache that lives with the renderer is part of a rendering pipeline. This is the design Next.js's Cache Components ships under dynamicIO. It works because the pipeline is in the loop — the cached value is a stream of bytes representing a region of the rendered tree, the dynamic holes are <Suspense> boundaries, the streaming response stitches the cached shell back together with the live data. The directive is a marker on a region of the tree the renderer cares about, and the cache is the part of the renderer that remembers what that region produced. Take the function out of the renderer and the cache disappears, because there is nothing to cache.

The first design is small. The second is integrated. Each one has a thing it is good at and a thing it cannot do.

The first cannot stitch shells around dynamic holes. It does not know about Suspense. It does not produce streaming responses with prerendered prefixes. If you want partial prerendering, the second design is the one you want.

The second cannot run outside the renderer. It cannot ship as a primitive in a library. It cannot run on the edge before the framework boots. It cannot run in the browser. It cannot dedupe a database lookup that happens during a worker job that has nothing to do with rendering. If you want a caching primitive you can reach for in any program, the first design is the one you want.

The two designs are not interchangeable. A cache that requires the framework to be present is a feature of the framework. A cache that requires only a function is a feature of the program. This article is for the second one, and the rest of it is the structural case for that choice — four properties the cache acquires when it belongs to the function and gives up when it belongs to the renderer.

Atomic, not ambient

A function-level cache is atomic. One function, one cache, one set of inputs, one output. The developer can assert — locally, by inspection — that the output is a function of the inputs and that nothing else in the world matters. The function's inputs are the developer's parameters; there is nowhere else for hidden state to come from.

Render-coupled caches give some of this up. A region of a rendering tree closes over the request, the user, the route parameters, the surrounding component state — and the cache machinery has to chase those captures and decide what is safe to serialize. The result is a more powerful cache, but the unit of reasoning has moved. The function is no longer what the developer reasons about. The region is.

The hard part of caching is not the syntax. It is the honesty — marking a function only when its output really is a function of its inputs, and not closing over state the key cannot see. A smaller unit makes that honesty checkable. A larger unit makes it a research project.

Caches that compose

A function-level cache composes. Two cached functions written by two different people, in two different libraries, called from a third function that caches nothing of its own, all behave the way the source reads. The outer call is uncached. The inner calls each consult their own caches. Each layer's decision belongs to that layer.

async function getOrder(id: string) {
  "use cache"
  const order = await db.orders.find(id)
  const customer = await getCustomer(order.customerId)   // also "use cache"
  const products = await Promise.all(
    order.lineItems.map(item => getProduct(item.productId)) // also "use cache"
  )
  return { order, customer, products }
}

Three caches stacked, no coordination. The outer cache stores the assembled order. The inner caches store the customer and each product. They have different TTLs, different tags, different lifetimes. None of them know about the others. A request that asks for an order seen recently hits one cache. A request for a fresh order whose customer is well-known hits two. A request for an entirely new order misses everything and fills in three caches at once. Every path through the system is correct, because every cache was a local decision.

Render-coupled caches compose under the renderer's rules. The shell's lifetime, the hole boundary, the streaming order — these are properties of the pipeline that two cached pieces inherit when they share a tree. The function-level cache carries no surrounding model. The diff is a one-line claim about the function. The blast radius is the function.

A function is a function

A directive that marks a single function does not care what runtime is reading it. The contract is between a function and its caller. The caller might be a server rendering RSC, an SSR pipeline streaming HTML, a worker, an edge runtime, a browser tab running the same code on the client side of an isomorphic boundary. The directive's meaning does not change. The function says: my output is my inputs. The runtime, whichever runtime that is, says: I will hold it.

This is the property the render-coupled cache cannot have, by construction. It works because the renderer is in the loop. Take the same code out of that loop — run it before the framework boots, in a worker job, in a browser tab that does not go through the request lifecycle — and the cache disappears, because the cache is the renderer remembering, and the renderer is not there.

A function-level cache survives the move. A library can ship cacheable utilities and rely on whatever runtime hosts them to honor the directive. There is no if (server) branch, no if (browser) branch, no separate cache wiring per environment. The same function, in any host that understands the directive, has the same contract. A host that does not understand it leaves the function alone.

This is what it means for a caching primitive to be portable. Not that the framework runs in many places — that is a deployment concern, and a different one. The render-coupled cache is a property of the host. The function-level cache is a property of the source. The function carries its own contract.

Locality buys you removability

A function-level cache is removable in a one-line diff. Delete the directive. Ship. The function reverts to first principles — it runs every time it is called — and you can investigate the staleness offline, where it is cheap to be wrong.

Render-coupled caches are removable too, when the unit being uncached is the unit the renderer marks. The harder cases are the surrounding ones: a cached region whose contents vary in ways the renderer's closure analysis did not capture, a tag-based revalidation that turned out to invalidate too much, a cacheLife profile that turned out to be wrong for one specific function in one specific context. The diff is still small; the diagnosis is not, because the failure isn't in the function — it's in the relationship between the function and the renderer.

The same property holds for code review. A "use cache" directive shows up in a diff. A reviewer asks: is this function actually a function of its inputs? Is the TTL right? When the unit being marked is a function, those questions have function-shaped answers. When the unit being marked is a region, the questions also have to ask about Suspense boundaries, about what the renderer captures, about how the streaming response composes. More variables, more places to be subtly wrong.

Scope is also a per-function decision

The strongest underdeveloped property of the function-level cache is scope. The clearest way to see it is to look at a page that needs three caches.

A product page calls getProduct(id) from three different components in the same render. They should see the same value; the database lookup should run once. This is request-scoped dedup.

The same page calls getProductCatalog(), the company's full catalog — refreshed nightly, shared across every request, identical for every user. This is a long-lived in-memory cache.

The same page calls getInventoryStatus(sku), which has to be synchronized across every server in the fleet, because two requests landing on different machines cannot disagree about whether an item is in stock. This is a shared store.

In current Next.js, those are three primitives. React.cache for the first. "use cache" for the second. A custom cache provider, or an external store reached through a server function, for the third. Each has its own API, its own keying, its own invalidation model. A developer who picks the wrong one rewrites the function when they discover the choice was wrong.

In a function-level design, all three are options on the same directive. "use cache: request" for the first. "use cache" for the second. "use cache: shared" for the third. The function shape does not change. The directive carries the answer to which scope it belongs to. Picking the wrong one is a one-line fix.

This is a real, structural advantage, and one of the places where the function-level design has not yet fully shipped in the largest framework that uses the syntax.

The shape of the contract

The directive is a contract between the developer and the runtime, and the mandatory part of the contract has only three lines.

The developer says: this function's output is determined by its inputs.

The runtime says: I will hold the output and serve it again the next time the inputs match.

Both parties say: when this is no longer true, the directive comes off.

That is the surface that has to be there. Everything else — a TTL, a tag, a named profile, a choice of storage, a choice of scope — is an option the developer attaches to the directive when the function calls for it. Tags are useful when there is something to invalidate by group. TTLs are useful when freshness has a known half-life. Named profiles are useful when several functions share the same caching shape and the shape is worth naming once.

None of these options are wrong. They are all part of the directive's optional surface, all developer-attached, all visible at the call site. The asymmetry that matters is between options the developer wrote down and options the runtime applied silently. A developer adding ttl=60 or tags=todos to a directive is making a decision visible in the source. A framework deciding the same thing on the developer's behalf is making the same decision invisible. Only the first kind is in the diff.

The same argument applies, structurally, to every directive in this family. "use client" is a marker that asserts a piece of code crosses a runtime boundary; the value of the marker is that you can read the program and see where the boundaries are. I have argued elsewhere that the directive should be allowed at finer granularity than a file — see The "use client" Tax — but the underlying point is the same. A directive is the developer telling the runtime something the runtime could not have inferred. That contract scales because it is small.

Two kinds of software

Underneath the function-vs-renderer choice is a more general one about what kind of software you are writing.

A framework is a packaged product. It optimizes for the page — for the user-visible artifact at the end of the rendering pipeline. Coupling caching to rendering is the breakthrough that makes partial prerendering work: a static shell streamed first, dynamic holes filled in afterward, no full server roundtrip on a navigation. That is a real win, and it is the win the render-coupled cache exists to deliver. A framework architect choosing the render-coupled design is making a coherent product decision.

A runtime is a primitive. It optimizes for the cache — for the contract a developer can hold in their head and reach for in any program. The function-level cache is not better than the render-coupled cache for the page. It is better for the cache. It composes outside a render tree. It runs in any environment. It survives library packaging. It does not require a mode flag to be turned on. A runtime architect choosing the function-level design is making a coherent primitive decision.

Both choices are defensible. They produce different software. A developer who wants the page wants the render-coupled cache; a developer who wants a caching primitive they can reach for unconditionally wants the function-level one. The directive looks the same in both. The systems underneath it do not.

What the ecosystem pays

The decision about where a caching primitive lives looks, inside one application, like a trade-off between two designs. From above the application — at the level of the JavaScript ecosystem the application depends on — it is something else.

A library author shipping a function cannot assume the consumer is in dynamicIO mode. They cannot assume the consumer is using a framework at all. So a library that wants to ship a cacheable utility — a database client that should dedupe identical queries, a markdown renderer that should not re-parse the same input twice, an API client that should pool requests — has one option under the render-coupled design: do not provide the cache. The library exposes raw functions; the consumer wires them into their framework's caching themselves; everyone reinvents the same wrappers in slightly different shapes, and the bugs all live in the wiring.

Under a function-level design, the library author writes "use cache" at the top of the function and ships. Any consumer whose runtime understands the directive gets the cache. Any consumer whose runtime does not, gets the raw function. The library does not have to know. The consumer does not have to wrap.

This is a pattern. Every time a framework absorbs a capability that could have been a primitive — caching, server functions, partial hydration, request-scoped state, routing — the ecosystem pays. The capability becomes available only inside that framework. Libraries that want it pick the framework as a hard dependency, ship their own version, or expose it as a configuration surface for the consumer to wire up. None of these are good for the developers a level removed from the framework. Each one moves complexity out of the framework and into a thousand small repositories that did not need to invent it.

The render-coupled cache is not the only place this happens. It is one place where the trade is unusually clear. The capability — memoizing a function on its inputs — has a canonical shape. The shape is small. It does not need a renderer to be useful. Putting the renderer in the loop trades that universality for an integration the framework can use to power partial prerendering. That trade is fine for the framework. It is paid by everyone else.

I have made a parallel version of this argument about a different misplaced primitive: a framework exposing a capability as a library API where a directive would have been smaller (RSC as a serializer, not a model). Misplaced primitives look different in the small. From far enough away they look the same.

The smaller point

Where a primitive lives determines what the developer can do with it. A cache that lives in the renderer can do things a function cache cannot — partial prerendering, streamed shells, suspense-aware regions. A cache that lives with the function can do things a render-coupled cache cannot — travel between environments, compose without coordination, ship in a library that does not know what framework will host it.

"use cache" is the same five letters in either design. The choice the developer is making by writing the directive is not really a choice about caching. It is a choice about which of those two things the caching primitive should be.

A cache that lives in the framework belongs to the framework. A cache that lives in the function belongs to the developer. Only one of those travels.

The "use client" Tax

Viktor Lázár — Tue, 28 Apr 2026 17:16:59 +0000

Why React Server Components force small interactive ideas into file-sized boundaries — and why that boundary should be lexical instead.

There is a moment that every developer who tries React Server Components hits, usually within their first hour. They write a server component. It fetches some data. It renders a list. Beautiful. Then they want a button that toggles a filter, and the compiler stops them: "you can't use useState here." So they cut the interactive piece out, paste it into a new file, sprinkle "use client" at the top, import it back into the parent, and move on.

A week later their components/ directory looks like this:

components/
├── product-list.tsx
├── product-list-filter.tsx
├── product-list-filter-input.tsx
├── product-list-sort.tsx
├── product-list-sort-dropdown.tsx
├── product-card.tsx
├── product-card-actions.tsx
├── product-card-favorite-button.tsx
└── product-card-quantity-stepper.tsx

Nine files for one product list. Each one a thin wrapper. Each one with two or three lines of real logic. Each one named with an increasingly desperate suffix because the original Filter already exists three directories up.

This is the "use client" tax, and it is real.

Where the tax comes from

The directive is not arbitrary. "use client" marks a module boundary that the bundler uses to split graphs: everything reachable from a "use client" entry becomes part of the client bundle; everything else stays on the server. The directive has to live at the top of a file because that is the granularity the bundler operates on. Modules in, modules out.

That works fine in theory. In practice it forces a one-to-one correspondence between interactive concerns and files on disk, and interactive concerns are not file-sized. They are paragraph-sized. A "favorite" button that toggles state is not a module — it is two lines inside the card that displays the product. But the runtime can't see those two lines unless you lift them into their own module, give them a name, export them, import them back, and pass props across the boundary.

The result is a particular kind of friction that compounds:

File sprawl. Trivial widgets become trivial files. Most of the file is the import header.

Naming fatigue. Every extracted leaf needs a name. Names that were unique in their lexical scope are no longer unique once they live in a flat directory. You end up with ProductCardFavoriteButtonInner.

Lost colocation. A server function that writes to the database and the form that calls it now live in two files. The relationship between them survives only as an import statement. To understand the feature you alt-tab.

Indirection without abstraction. Each extracted client component is a wrapper that accepts everything the parent had in scope, as props. You are manually performing closure conversion — by hand, every time, with no help from the compiler.

Compositions you can't write. The pattern that hurts most is the one you cannot express at all: a server function that computes some data and returns a small interactive component bound to that data. You cannot do this in standard RSC, because the client component has to be a separate module, which means it cannot close over server-side values. You always end up exporting the client component, exporting the data fetch, and re-assembling them at the call site. The expression you wanted to write — a factory — is not available to you.

The shape of the pain

Here is what a real fragment looks like under the current rules:

// product-card.tsx
import { FavoriteButton } from "./product-card-favorite-button";

export async function ProductCard({ id }) {
  const product = await db.product.find(id);
  return (
    <article>
      <h3>{product.name}</h3>
      <FavoriteButton productId={product.id} initial={product.isFavorite} />
    </article>
  );
}

// product-card-favorite-button.tsx
"use client";

import { useState } from "react";
import { toggleFavorite } from "./product-actions";

export function FavoriteButton({ productId, initial }) {
  const [favorite, setFavorite] = useState(initial);
  return (
    <button
      onClick={async () => {
        setFavorite(!favorite);
        await toggleFavorite(productId);
      }}
    >
      {favorite ? "★" : "☆"}
    </button>
  );
}

// product-actions.ts
"use server";

export async function toggleFavorite(productId: number) {
  // ...
}

Three files for a star button. Two of them exist purely as plumbing for the directive system. The actual interesting code — eight lines of state and a database write — is buried under thirty lines of imports, exports, and prop-passing.

This is what people mean when they say RSC is heavy. It is not the data fetching. It is not the streaming. It is this: the directive system asks you to manually re-architect every interactive idea into a multi-file module graph, and it does so for the smallest possible units of behavior.

Zoom out one level and the same pressure exists at the project boundary: modern frontend frameworks force entire micro-apps to be scaffolded across directory trees, config files, and node_modules for the same kind of mechanical reason — tooling that operates at a coarser unit than the developer's idea. I covered that version of the problem in The Forgotten Joy of node app.js. The fix is structurally the same as the one proposed below: stop letting the file system be the unit of expression.

The constraint is in the tool, not in the model

Here is the part that is worth saying out loud: the file-level restriction is a property of how bundlers were built, not a property of what the directive means. "use client" is asserting that a piece of code runs on the client and must be serialized across a runtime boundary. That assertion is perfectly meaningful at any function scope. It only has to live at the top of a file because that is what the bundler can see.

A compiler that knows about RSC directives can do better. Given a server module that contains a nested function marked "use client", it can:

Identify the nested function and the variables it captures from its lexical scope.
Lift the function into a synthetic module that the bundler treats exactly like a regular "use client" module.
Replace the original definition with a reference to the lifted module.
Inject the captured variables as props at the call site.

The developer wrote one file. The bundler sees the module graph it needs. Nothing about the underlying RSC contract changes — the same serialization rules apply, the same boundary is enforced — but the file system stops being the unit of expression. The function does.

What this should look like

Imagine writing the favorite button like this instead:

export async function ProductCard({ id }) {
  const product = await db.product.find(id);

  function FavoriteButton() {
    "use client";
    const [favorite, setFavorite] = useState(product.isFavorite);

    async function toggle() {
      "use server";
      await db.product.toggleFavorite(product.id);
    }

    return (
      <button onClick={async () => { setFavorite(!favorite); await toggle(); }}>
        {favorite ? "★" : "☆"}
      </button>
    );
  }

  return (
    <article>
      <h3>{product.name}</h3>
      <FavoriteButton />
    </article>
  );
}

One file. Server fetch, client interaction, server function — colocated, in the order you would read them, sharing a closure. The compiler does the lifting; the captured product becomes a prop on the synthesized client module; the inner "use server" function becomes a bound server function with the right scope. Server → client → server nesting works recursively because the same extraction pass runs until no nested directives remain.

This is what a real RSC ergonomic story looks like. Not a new mental model — the same one — just expressed at the granularity humans actually think in.

Why this should be a standard feature

The technique is not exotic. It is closure conversion, a transform compilers have been doing since the seventies. The hard part is wiring it into the RSC plugin chain so that virtual modules generated for inline directives flow through the same client/server graph the rest of the system already uses. That is engineering, not research.

There is no fundamental reason an RSC-capable runtime cannot support this. The directive system is already a contract between the developer and the compiler; expanding it to cover function scopes in addition to module scopes does not change serialization, bundling, streaming, or the security boundary. It only changes where the developer is allowed to write the directive.

If you are building an RSC runtime: pick this up. If you are using one that does not have it: ask for it. A "use client" file is not a feature. It is a workaround for a constraint we no longer need to accept.

The point of RSC was to let us put server logic and client logic next to each other. The directive system, taken at face value, does the opposite: it forces them apart, file by file, until your repository is ninety percent wrappers. We can fix this. It is time to make the fix standard.

The Forgotten Joy of `node app.js`

Viktor Lázár — Tue, 28 Apr 2026 17:16:40 +0000

There used to be a moment, ten years or so ago, when you could go from "I have an idea" to "I have a running web server" in about thirty seconds:

// app.js
const express = require('express')
const app = express()

app.get('/', (req, res) => res.send('hello'))

app.listen(3000)

node app.js

That was the whole thing. One file. One command. You could paste it into a Slack message. You could drop it in a Gist and someone could run it. A tiny webhook receiver, a debug dashboard, an internal tool, a stub API — the entire project lived in a single buffer in your editor.

Then frontend frameworks happened, and somewhere along the way we collectively decided that "starting a new project" meant something else entirely.

The scaffold tax

Today, the canonical first step in starting a new app is no longer writing code. It is running a command that writes code for you:

npx create-next-app@latest my-app
npx create-react-app my-app
npm create vite@latest
npx create-remix

What comes back is not a file. It is a tree. Configuration files for tooling you have not yet decided to use. A pages/ or app/ directory with conventions you must learn before you can write a single line. A tsconfig.json you did not write. ESLint rules. Prettier rules. A .gitignore. A README.md describing the scaffold itself. A package.json with twelve dependencies and four scripts you did not pick.

And, critically, there is no path back to a single file. The scaffold is the unit of starting. There is no framework dev ./App.jsx. There is only framework new my-project, which produces forty files, of which you will edit two.

This is fine when you are starting a real product. It is absurd when you are not.

What we lost

The single-file app is not a relic of a less mature ecosystem. It is a fundamentally different mode of working — one the modern frontend toolchain has quietly priced out of existence.

Specifically, we lost:

The throwaway. The five-minute hack to verify that an idea works. The "let me just see what this looks like rendered" experiment. With a scaffold, the cost of starting is high enough that you don't bother. You either pollute an existing big project, or you open the browser DevTools console.

The teaching artifact. A blog post used to be able to say here, run this file. Now it says clone this repo. The reader is no longer reading code; they are operating a project.

The micro-app. The three-route admin tool. The internal status page. The webhook that posts a Slack message. Things that should be one file are now twenty, because the framework demands it.

The shareable Gist. I cannot send you a single .jsx file and have you run it. I have to send you a repository — or a CodeSandbox URL, which is its own confession that the local toolchain has gotten too heavy.

The curl-and-run. Plain Node lets you stream a program straight from a URL into the runtime, no file on disk: curl https://gist.githubusercontent.com/.../app.js | node. No clone, no install, no project to set up. The source travels over the wire, lands in the interpreter, runs. The same pattern should work for a single-file frontend app — curl https://.../App.jsx | npx some-framework dev - — and the fact that this is unimaginable today is the most concrete possible measurement of how heavy "starting a frontend app" has become. We have a JavaScript-shaped hole in our shells that the language used to fit through.

There is a fractal version of this same pain one level down. Even inside a project, modern React's "use client" directive forces single features to be sharded across multiple files for purely mechanical reasons — the same disease, at smaller scale. I wrote about that version separately in The "use client" Tax. What follows here is the project-level shape of the same problem: even when the whole app should be one file, you are not allowed to write it that way.

The shape of the fix

Imagine, for a second, that this just worked:

npx next dev ./App.jsx

One file. One command. The framework picks it up, runs it, hot-reloads it, serves it. No next.config.js, no pages/, no app/, no package.json. If you decide later that you want a real project, you make the directory, add the config, split the file. The framework grows with you instead of demanding everything upfront.

The technology to do this is not hard. Frameworks already build on dev servers — Vite, esbuild, Turbopack — that can resolve and bundle a single entry point. The framework conventions (file-based routing, layouts, server components) are conventions over the bundler, not replacements for it. There is no fundamental reason a framework's CLI cannot accept a path to a .jsx file and Just Work, with the conventions kicking in only once you opt into a directory layout.

The reason it doesn't work is not technical. It's cultural. We have decided, somewhere along the way, that the project is the unit of frontend code, and the file is merely an implementation detail. Backend frameworks never made that mistake. You can still write a fifteen-line server.js and run it. You can still write a Flask app in one file. You can still put a Go HTTP handler in main.go and ship it. Scaffolds are offered as a convenience, not enforced as a precondition.

Frontend should be no different.

One file in, one file out

The single-file dev story is only half of the picture. The other half is what comes out when you build.

Today, building a frontend project produces another tree. A .next/ directory. A dist/ directory. A .output/ directory. Hundreds of chunked JavaScript files, manifests, server bundles, client bundles, route maps — and a node_modules you must ship alongside it, or carefully fold into the deployment artifact. Running the result usually means another framework-specific command (next start, node .output/server/index.mjs) that depends on the surrounding directory structure being intact.

It should be possible to do this:

some-framework build ./App.jsx -o app.js
node app.js

One file in. One file out. No node_modules, no config, no manifest, no dist/ to preserve. A single .js that boots an HTTP server, serves the assets it needs (inlined or referenced), and runs on any Node install with nothing else next to it.

Backend developers have had this for years, just under different names. Go produces a static binary. Deno compiles to a single executable. esbuild can bundle a Node program into one file. The pattern is universal: take everything the program needs, fold it into one artifact, ship that. Nothing about a React app — even a server-rendered, server-component-heavy React app — fundamentally prevents the same thing.

What this unlocks is bigger than convenience:

Trivial deployment. scp app.js server:/srv/ && node app.js. No CI artifact pipelines, no Docker images for a webhook receiver, no Kubernetes for a status page.
Reproducibility. The artifact is a file. You can hash it, version it, archive it, email it. Not a directory whose contents quietly differ depending on which npm install produced it.
Sandboxes. A single file is something a sandbox runtime — a serverless platform, a worker, a container — can swallow whole, with no need to mount a node_modules.
Distribution. Internal tools become as easy to share as a CLI binary. "Drop this on the server and run it" is a workflow we lost the moment frontends grew a build directory.

The deploy story for a small app should be as small as the app. Right now, even a thirty-line frontend deploys like a monorepo.

And then AI showed up

The scaffold tax used to be paid mostly by humans — a one-time annoyance you absorbed at project start, then forgot about. AI coding tools have quietly turned it into a recurring tax, paid on every interaction.

When you ask an AI to modify a single-file app, it can read the entire program in one shot, hold the whole behavior in its working memory, and reason about a change with confidence. The file is the project. There is nothing else to discover.

When you ask an AI to modify a scaffolded project, it has to do archaeology first. Where does routing live? Which tsconfig paths are aliased? Is that import resolved by a framework convention or by the bundler? Is app/ the routing root, or a coincidentally-named folder? What does the project's ESLint config forbid? Half the request gets spent loading context that wasn't actually relevant to the change.

This shows up as:

Worse answers, because the model is reasoning under a noisier prompt.
Slower answers, because more files have to be read before it can act.
More expensive answers, because tokens are not free, and a fresh agent re-discovers the same project structure on every session.
More fragile answers, because the model has more surface area on which to misread a convention.

A one-file app is, by accident, the ideal substrate for AI-assisted coding: the entire program fits in a single attention window, every symbol resolves locally, and the change you ask for can be made without crawling a directory tree first. The convention overhead we built up to make starting a project "easier" turns out to be overhead we now pay every time we ask a tool to help us edit one.

The same things that made the single-file app pleasant to write by hand — small surface, no hidden conventions, nothing to discover — make it the format AI tools handle best. We just stopped producing apps in that shape.

Why this matters

There is a subtle compounding effect to all of this. When the cost of starting is high, people start fewer things. When people start fewer things, the ecosystem gets less weird, less experimental, less playful. The thirty-line idea that would have become a beloved internal tool never gets written, because the scaffolding tax was higher than the energy budget for the experiment.

The modern frontend stack is extraordinarily capable. It can render server components, stream HTML, hydrate selectively, generate static pages, run on the edge, do incremental builds. None of that is at odds with also being able to do this:

some-framework dev ./App.jsx

It's a small surface area. It's enormously valuable. And it is, conspicuously, missing from almost every option you'd reach for today.

The good news is that almost. If you look around carefully, this capability is starting to reappear in the corners of the ecosystem — runtimes that treat the single file as a first-class entry point, not as a degenerate case of a project. It's worth keeping an eye on.

The thirty-second app deserves to come back.

The Two Joys of Coding Before AI

Viktor Lázár — Mon, 27 Apr 2026 19:51:28 +0000

There is a particular kind of grief floating around right now. You see it in blog posts, in conference talks, in late-night threads: a mourning for the joy of coding before AI. People describe it as if a forest has been paved over. Something they loved is gone, and something colder has taken its place.

I think most of these conversations talk past each other because they skip the only question that matters: what was the joy actually made of?

"Coding" is not one activity. It is at least two, braided together so tightly that for decades nobody had to separate them. AI pulls on one of those strands and not the other, and whether that feels like loss or liberation depends entirely on which strand you were holding.

Two kinds of joy

Strip a programming session down to its emotional core and you find two distinct rewards.

The first is the joy of materializing a vision. You see something in your head — a tool, an interface, a system, a small clever thing that does not exist yet — and you bring it into the world. The pleasure here is in the gap closing. The thing in your imagination and the thing on the screen converge until they are the same thing. The keyboard, the language, the build system: these are friction. Necessary friction, often beautiful friction, but friction. The joy lives at the moment of arrival.

The second is the joy of figuring something out. A problem resists you. You sit with it. You pull on threads, build mental models, get them wrong, refine them, and somewhere — sometimes in the shower, sometimes at 2 a.m., sometimes mid-sentence in a meeting — the shape of the answer clicks into place. The pleasure here is not in arrival but in the act of comprehension itself. You understand something now that you did not understand an hour ago, and your brain rewards you for it the way it rewards eating when you are hungry.

These are not the same feeling. They use different muscles. They satisfy different hungers. And — this is the important part — they leave behind different kinds of memory. A vision-materializer remembers what they built. A problem-solver remembers how the world bent into a new shape inside their head.

Most working programmers feel both, in different proportions, sometimes in the same hour. But if you ask honestly which one is the core — the thing that made you a programmer rather than something else — almost everyone has an answer.

What AI actually changes

AI coding assistants are extraordinary materializers. That is what they are built to be. You describe the thing, they produce the thing. The friction between vision and artifact collapses dramatically. What used to be an afternoon of plumbing is now a paragraph and a review pass.

If your joy was in the materialization — in seeing the thing exist — AI is not stealing anything from you. It is giving you more of what you loved. The gap closes faster, which means you can close more gaps, which means more visions per unit of life. The friction you tolerated was never the source of the joy; the arrival was. You can build the second thing now, and the third, and the weird side project you never had time for. The hands-on craft loss is real but it is a craft loss, not a joy loss. You can still write the loop by hand on a Saturday if you want to. Nothing stops you.

One thing has to be said clearly here, because it is the most common bad-faith reading of the materializer position: materialization is not "whatever shipped, shipped." A vision is not just a silhouette of a feature; it has internal coherence, a way it behaves under pressure, a quality it carries. A materializer who accepts slop because it superficially resembles the artifact in their head has not closed the gap — they have moved the goalposts to meet the output. That is not the joy of materializing a vision. That is the relief of being done. They are different feelings, and conflating them is how teams end up shipping confident-sounding garbage at unprecedented speed. The AI gives you a draft. The work — the actual materializer's work — is to keep pushing the draft until it matches the thing in your head, including the parts of the thing in your head that have to do with correctness, taste, performance, and how it will read to the next person. Acceleration is acceleration toward the right artifact, not toward any artifact. A materializer who forgets this is no longer practicing their craft; they are just hitting accept.

If your joy was in the figuring out, the picture is genuinely different — and the grief is genuinely earned. The AI is not just removing friction; it is removing the problem itself. The puzzle you would have sat with for three days, turning it over in your head on the train and in the shower, building the mental model that becomes part of how you think forever — the AI hands you an answer in twelve seconds. The answer is often correct. And the comprehension that would have grown in you while you struggled does not grow, because you did not struggle.

This is not a complaint about laziness or skill atrophy, though those are real concerns. It is something more specific: a category of human pleasure, the pleasure of understanding something hard, requires the hardness. Remove the hardness and you remove the pleasure, even if you keep the answer. You cannot have the satisfaction of a crossword without the crossword.

Why the debate is so confused

Once you see this split, the public conversation about AI and coding starts to make more sense. The two camps are not actually disagreeing about AI. They are reporting honestly on two different inner experiences.

The "AI is wonderful, I ship five times faster" camp is overwhelmingly populated by materializers. They are telling the truth. Their joy is intact and amplified.

The "AI is hollowing out my craft" camp is overwhelmingly populated by problem-solvers. They are also telling the truth. Their joy is, in fact, being eroded — not by malice or hype, but by the specific mechanism of having the puzzles solved before they get to play with them.

When these two groups argue, they sound like they are arguing about a tool. They are actually arguing about which of two pleasures is the real one. There is no answer to that question, because there are two answers, and they are both correct for the person giving them.

Notice how each camp uses the same phrase to dismiss the other's grief. To the materializer, the problem-solving was always an implementation detail — a means, a tax you paid on the way to the artifact, something a sufficiently advanced tool was supposed to absorb eventually. To the problem-solver, the shipped artifact was the implementation detail — the residue, the visible echo of an internal event that had already happened in their head. Each side, in good faith, treats the other side's joy as the boring scaffolding around their own. That is why the conversation goes nowhere: both sides are correctly identifying what is, for them, incidental.

What to do about it

If you are mourning, the first useful move is to ask yourself the honest version of the question. Not "do I miss coding," but: which kind of coding? When you replay the moments you would call joyful, are you watching yourself ship the thing, or are you watching yourself understand the thing? The answer tells you whether you are facing an opportunity or a loss.

For materializers, the path is mostly forward. Use the tools. Build more. The thing you loved is more available now, not less.

For problem-solvers, the answer is harder and more deliberate. The puzzles still exist; they have just stopped arriving on their own. Production code paths now route around them. To keep the joy, you have to choose the friction back in — pick problems the AI cannot solve cleanly, work in domains where the model is weak, build from scratch on weekends, read papers, do the leetcode-equivalent that is actually interesting to you, contribute to runtimes and compilers and other places where the problem space is still deep enough that no autocomplete can shortcut it. The protected hour where you do not ask the assistant is not a Luddite stance; it is a deliberate preservation of the conditions your joy requires.

Both responses are healthy. Both are grown-up. What is not healthy is conflating them — using a materializer's optimism to dismiss a problem-solver's grief, or using a problem-solver's grief to deny a materializer's genuine, earned acceleration.

The thing under the thing

The deeper claim hiding inside all of this is that coding was never one thing. It was a workbench where two very different human pleasures happened to use the same tools. The industry treated them as one because the workflow forced them to be one — you could not materialize a vision without solving a hundred small problems along the way, and you could not solve interesting problems without something to materialize them into.

AI is the first force strong enough to pull those two pleasures apart. It is doing so cleanly and without asking permission. What we are watching is not the death of the joy of coding. It is the unbundling of two joys that were always separate, finally being forced to admit it.

Which one was yours?

RSC as a serializer, not a model

Viktor Lázár — Mon, 27 Apr 2026 17:32:02 +0000

The most interesting thing about how TanStack Start integrates React Server Components is not what it does with them. It is the shape of the API.

You do not write a Server Component. You do not opt into a model. You opt into a function — a programmatic primitive that takes a component, runs it through the RSC renderer, and hands you back a payload you can store, transport, and rehydrate later. RSC is not the substrate of the application. It is a tool you reach for at specific call sites, when you want a specific thing.

That framing is worth pausing on, because it tells you something about the design intent that the marketing copy does not.

What the API is really for

The use case being served is narrow and clear: caching values that the rest of the JavaScript ecosystem cannot cache. A normal cache stores JSON. JSON cannot represent a React element. JSON cannot pass through a value that resolves later. JSON cannot carry the richer plain types — Map, Set, Date, typed arrays — that show up in a real component tree. RSC's wire format can. It was designed to. That is what the protocol is.

So if you take the RSC renderer, strip it of everything that makes it a composition model, and expose just the serializer, you get a primitive that turns "a tree containing UI and non-JSON props" into "a string you can put in Redis." That is a real capability. It is also, on reflection, a very small one.

This is the capability TanStack Start has surfaced. Not Server Components. A serializer for component-shaped values, exposed as a programmatic API.

If the goal is caching, name it caching

"use cache" is the design that already exists for this exact problem. It is a directive. It tells the runtime: this output is cacheable, key it on these inputs, store it for this long. The runtime handles serialization, deserialization, key derivation, invalidation, and storage. The developer writes a function and adds one line.

Concretely. Imagine a post card — a tree containing a server-rendered article and a client-rendered set of actions — produced once and reused across navigations. Under a directive:

async function PostCard({ postId }: { postId: string }) {
  "use cache"
  const post = await db.posts.findById(postId)
  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.body}</p>
      <PostActions postId={post.id} authorId={post.authorId} />
    </article>
  )
}

The runtime knows what the cache key is (the inputs the function closes over), where the value lives, when it expires, and how to serialize it (the same wire format the rest of the system already speaks). One line of metadata and a function body. The developer writes a component.

Under TanStack Start's API, the same tree is produced by driving the protocol explicitly:

import { createServerFn } from "@tanstack/react-start"
import { createCompositeComponent } from "@tanstack/react-start/rsc"

const getPostCard = createServerFn()
  .validator(z.object({ postId: z.string() }))
  .handler(async ({ data }) => {
    const post = await db.posts.findById(data.postId)
    const src = await createCompositeComponent(
      (props: {
        renderActions?: (d: { postId: string; authorId: string }) => React.ReactNode
      }) => (
        <article>
          <h1>{post.title}</h1>
          <p>{post.body}</p>
          <footer>{props.renderActions?.({ postId: post.id, authorId: post.authorId })}</footer>
        </article>
      ),
    )
    return { src }
  })

export const Route = createFileRoute("/posts/$postId")({
  loader: ({ params }) => getPostCard({ data: { postId: params.postId } }),
  component: PostPage,
})

function PostPage() {
  const { src } = Route.useLoaderData()
  return (
    <CompositeComponent
      src={src}
      renderActions={({ postId, authorId }) => (
        <PostActions postId={postId} authorId={authorId} />
      )}
    />
  )
}

Six things have to agree across this code: the server function that produces the payload, the validator that gates its inputs, the createCompositeComponent call that names the seam, the loader entry on the route, the useLoaderData site that retrieves the payload, and the <CompositeComponent> site that rehydrates it — including the render-prop signature that has to match on both sides. Caching is implicit in the router's staleTime and loaderDeps. Invalidation is the router's responsibility and shaped by the route boundary, not the value boundary.

None of these decisions have a defensible non-canonical answer for the simple case. Every team using this will write the same wrapper around it, in slightly different shapes, and the bugs will all live in the relationships between the serialization site, the render-prop signature, and the rehydration site.

The case where this matters most is the one the framework does not address at all: caching a component-shaped value at request scope. The docs recommend React.cache for the request-scoped case, but React.cache deduplicates plain function results — it does not memoize trees that contain client component references and closures over server-only data. There is no primitive shaped for that. The same computation can run three times in one request because three parts of the tree need it, and the framework's answer is the route-level cache, which is route-scoped, or React.cache, which does not apply.

A directive-shaped API hides those decisions because most of them only have one correct answer. A library-shaped API exposes them because the framework refuses to commit to one.

Boundary wrappers, protocol wrappers

There is a more general problem under this. RSC, as a protocol, is a serialization format. RSC, as a model, is a composition story between two environments. When a framework lifts the protocol out of the model and exposes it as a programmable primitive, what it is really saying is: "the protocol is interesting to us, the model is not."

It would be easy to read this as a complaint about wrappers in general. It is not. A wrapper-shaped API is often the right answer, and in TanStack Start specifically it is the dominant idiom. Routes are wrappers. Loaders are wrappers. Server functions are wrappers. The whole framework is built around the pattern of pass your thing through this constructor, get back a richer thing the runtime now understands. A wrapper for RSC caching slots into that idiom cleanly.

The argument is about what a wrapper carries across the boundary it creates, because there are two kinds and they look almost identical until you start using them.

A boundary wrapper says: this is where the model changes shape. It takes a value, marks a seam the runtime will operate on, and hands the developer a richer reference back. The developer never touches the protocol underneath; they only see the seam, named and located. The wrapper carries the model with it — calling it is participating in the model.

A protocol wrapper says: here is the renderer, here is the payload, here is the deserializer. It hands the developer the wire format and asks them to drive it. The seam is gone. What is left is a set of operations on bytes that the developer has to compose themselves.

TanStack Start's other wrappers — the route, the loader, the server function — are boundary wrappers. The framework knows what the wrapped thing is, the runtime knows what to do with it, and the developer writes their code in the vocabulary of the model rather than the vocabulary of the protocol underneath. That is what makes those APIs feel coherent next to each other.

The RSC integration is the exception. The outer shape is the same — a function you call, a value you hand it, a value you get back — but there is no model on the other side. The developer is handed the renderer instead of being handed a richer reference.

The defensible version of the choice

The strongest case for what TanStack has shipped goes something like this. The framework's audience is router-driven and SPA-adjacent. Committing to the full RSC composition model would constrain the rest of the architecture in ways that conflict with how the framework already works. A library-shaped API leaves room for teams whose caching needs really do diverge. A directive forces a single shape on every caller, and that shape — "use cache" as it ships today — is itself not a settled design. Its key inference, its invalidation story, and its "what is safe to close over" semantics have known warts. Why commit to it?

The first half of that case is real. The second half is the one to push back on.

A directive does not have to mean "use cache" exactly as it ships today. The directive is a shape, not a specification. The shape is: a marker at the boundary, a runtime that infers the keying and storage, a developer who writes a function. The runtime gets to choose how aggressive the inference is, what scope the directive defaults to, and what the escape hatches look like. A request-scoped variant is easier than the application-cache variant "use cache" currently targets, not harder, because almost every decision has one canonical answer at the request scope.

The "we left it open because needs diverge" defense applies to primitives where they really do diverge. Application caches diverge — TTLs, tags, storage. Request-scoped caches do not. The needs are: dedupe within a render, survive into hydration, evaporate at request end. That is the specification. There is no second team whose answer to those questions is meaningfully different.

The honest version of the architectural choice is: "we don't want to commit to the model yet, and we don't want to ship a caching directive without committing to the model, so we shipped the renderer as a library and let users assemble what they need." That is a coherent position. It is just not the position the docs reflect.

What is actually being shipped

To make this caching primitive work, the framework has to bundle the RSC renderer, the RSC serializer, the matching deserializer, the streaming format reader, and enough of the React internals to drive all of it. That is the entire RSC machinery, intact — including the parts the framework will not let the developer use.

The framework does not have a "use client" boundary at all. Interactivity is injected through slots on <CompositeComponent> — children, render props, component props — not through client component references resolved at hydration. The reference-resolution machinery RSC was designed around, the matched identifiers across server and client builds, the client manifest, the hydration-time dispatch, all of it is bundled but inert. The framework has actively engineered an alternative path (the slot pattern) that routes around the very mechanism RSC exists to provide. The user experience of writing a TanStack Start application is the user experience of writing a router-driven app that occasionally summons the RSC serializer for caching.

So the framework pays the full cost of the protocol — every byte of the serializer, every transitive dependency, every line of React internals it has to remain compatible with — and uses it to power a feature that, on its own, could be expressed as a directive over a much smaller mechanism. The bundle includes the engine of a model the framework has chosen not to adopt.

There is a third option the design did not take: a fit-for-purpose serializer. The capability TanStack Start actually needs — turning a rendered component tree, slot placeholders and non-JSON values included, into bytes and back — is a small one. It is not the RSC protocol. RSC is that capability plus a streaming format with suspense boundaries, plus server reference dispatch, plus the entire client-resolution layer the framework has already chosen not to use. A protocol designed for the narrower job would be smaller, evolvable on the framework's own cadence, and decoupled from React's internals. That a project willing to ship its own router, its own loader system, its own server-function wrapper, and its own composite-component primitive nevertheless reached for the entire RSC implementation tells you the choice was not driven by what the feature needs.

The agent reading the code

There is one more lens worth applying, because in 2026 it is the lens that shapes a growing share of code: the AI coding agent.

The relevant claim is narrower than "agents will get directives right and wrappers wrong." It is structural: a directive compresses the model into the syntax; a protocol wrapper requires the model to be reconstructed at every call site, and that reconstruction is where coordination bugs compound.

An agent producing a directive-based caching feature emits a marker, a function body, and the inputs the developer already named. The keying, scope, invalidation, and lifetime are the runtime's contract — the agent does not produce them, so it cannot produce them wrong.

An agent producing a protocol-wrapper caching feature has to emit a serialization call, a storage decision, a key derivation, an invalidation hook, a deserialization call, a rehydration site, and the glue holding all of them in agreement. The shape of each piece is locally reasonable. The bug lives in the relationships — a stale key, a missed invalidation hook, a request-scoped value silently captured in the payload, a payload rehydrated at the wrong boundary. An agent reviewing its own output will not flag these, because each part on its own makes sense.

Less code is not only easier for humans. It is easier for agents — fewer tokens to generate, fewer relationships to track, fewer places to be subtly wrong. Boundary primitives compress an enormous amount of model into a tiny amount of syntax. Protocol APIs decompress the model back into surface area and ask the agent to operate it. Increasingly, an API surface that is hostile to agents is an API surface that is hostile to its own users.

What gets lost

A framework gets to choose the level of abstraction it commits to. If it commits to RSC as a model, the developer writes components and the runtime handles the seams. If it commits to caching as a model, the developer writes directives and the runtime handles serialization. If it commits to neither and exposes the protocol as a library, the developer writes glue.

Glue is the most expensive code in any application. It is the code that does not solve the problem; it only connects the things that do. It also ages worst, because every change to the surrounding ecosystem requires the glue to be rewritten while the parts on either side of it stay the same. The moment a request-scoped value becomes something the developer has to manually serialize, key, store, and revive, the framework has already lost the lifecycle it was supposed to protect.

A framework whose RSC story is a library call is asking every team that uses it to write and maintain that glue forever. The convenience is moved out of the runtime and into a thousand small repositories that all rediscover the same patterns and the same failure modes. The framework gets to ship a thinner runtime; the ecosystem absorbs the cost.

That trade is sometimes worth it — for a primitive that genuinely has no canonical shape. Caching component output is not that primitive. It has a canonical shape. The shape is a directive. The reason it is not the API is not that the shape is wrong. It is that adopting the shape would require committing to the surrounding model, and that commitment was the thing the framework was avoiding from the start.

The smaller point

Strip the protocol away and the design becomes legible. The team wanted a way to cache values that JSON could not represent. They had access to a serializer that could. They exposed the serializer. They called it RSC support.

It is RSC support in the sense that the renderer is in the bundle. It is not RSC support in the sense that the developer is asked to think in the RSC model, write in its idioms, or benefit from its composition story. The renderer is a load-bearing dependency for a feature that is not, itself, the model the renderer was designed to power.

When a framework treats a model as a primitive instead of as the model, it is telling you that it wanted something the model happened to make possible, not the model itself. There is nothing wrong with that as a product decision — but it should be named accurately. The honest version of this feature is a caching directive. The honest version of the framing is "we ship a serializer-backed cache." Everything else is a story told in the vocabulary of a model the framework chose not to adopt.

Project, Don't Embed: Introducing Virtual Frame

Viktor Lázár — Tue, 21 Apr 2026 08:48:43 +0000

A first-time introduction to Virtual Frame — what it is, why it exists, and how it composes independently deployed web apps into a single page without a shared build.

There's a problem every large frontend eventually runs into, and it goes something like this: you have five teams, five stacks, five deployment pipelines — and one page. The design system lives in team A's repo. The checkout widget belongs to team B. The dashboard you're trying to embed was last touched by a team that no longer exists. None of these things ship together. All of them need to render on the same page, at the same time, and feel like one product.

The industry has been trying to solve this for a decade. The solutions all have a tax.

Module federation is great when host and remote share a build pipeline, and useless the moment they don't. The first time you need a coordinated upgrade across three repos, the "independent teams" story evaporates. Iframes give you perfect isolation and zero composability — you get a rigid rectangle that doesn't flow with your layout, can't inherit your theme, and picks fights about scroll, focus, and accessibility. Edge-side includes and server fragments work beautifully for static markup and fall apart the moment the remote needs its own runtime. Ad-hoc SPA shells work until they don't; then you're debugging a shared React instance that sees two different versions of the same context.

Each of these is the right answer to a different question. None of them is the right answer to the question most teams are actually asking: how do I compose fully independent web applications — different repos, different frameworks, different deploys — into one page, with real layout flow and real interactivity, without coupling any of them at build time?

Virtual Frame is a bet that you can do that if you stop thinking about embedding remote applications and start thinking about projecting them.

The one-paragraph version

Picture a hidden iframe loading another team's page. The page runs normally in there — same as if you'd opened it in a new tab. Virtual Frame takes what that hidden page is drawing and paints it into a slot on your own page, live. When the remote updates, your slot updates. When your users click, scroll, or type inside the slot, Virtual Frame forwards those interactions back to the hidden page so its app keeps working like it's running in a real browser tab.

The result: the remote app's output is part of your page. It flows with your layout, picks up your theme, and behaves like any other piece of your UI — because, as far as the browser is concerned, it is any other piece of your UI. The remote keeps running in its own world; its output lives in yours.

That's the entire pitch.

Why this mental shift matters

The most important word in the previous section is projecting, and it's worth slowing down on.

When you embed something — an iframe, a web component, a third-party widget — you're accepting its frame. The embedded thing has a boundary, and things stop at that boundary. Layout stops there. Events stop there. Themes stop there. You're not composing, you're docking.

When you project, the boundary collapses. The remote application still runs in its own browsing context — that part is non-negotiable, it's how you keep the remote's runtime from tripping over yours — but its rendered output flows into your page the way a child component's output would. The execution is isolated; the presentation is composed.

This is a surprisingly slippery idea the first time you encounter it, because we've been trained by twenty years of iframe behavior to think of "other-origin content" and "rigid rectangle" as the same thing. They're not. The rigidity is an implementation detail of how browsers expose iframe contents, not a law of nature.

How it actually works

Three primitives, no magic.

A source iframe, hidden off-screen. The remote runs as a complete, standalone application inside it — its framework boots, its router runs, its effects fire, its fonts load. Virtual Frame doesn't re-execute your app; it observes it. That's the key constraint: nothing about your remote has to change to be projectable.

A host element, which is any element you put on the page — a <div>, a <section>, a component root. Virtual Frame optionally attaches a Shadow DOM to it (open or closed) and mirrors the remote's <body> subtree into that shadow root. Shadow DOM gives you CSS isolation without giving up custom-property inheritance, which is the sweet spot: the remote's styles can't bleed into your page, but your theme still crosses the boundary.

A sync layer. Same-origin, this is a MutationObserver on the source plus CSS rewriting and event re-dispatch. Cross-origin, a bridge script loaded once in the remote serializes the DOM and events over postMessage, and the host reconstructs them. The cross-origin story is worth dwelling on, because this is where iframes usually give up: there is no host-side configuration. Drop the bridge into the remote, and every host on every origin can project it.

Everything else — selector-based projection, canvas streaming, SSR with resumption, the shared reactive store — is built on top of these three primitives. But the primitives are simple, and that's on purpose. Simple primitives compose.

A taste of code

The shortest path is the custom element. This is a complete working projection:

<script type="module">
  import "virtual-frame/element";
</script>

<virtual-frame
  src="https://dashboard.example.com"
  isolate="open"
  style="width: 100%; height: 600px"
></virtual-frame>

That's it. No build plugin. No config file. No framework buy-in. When the element connects to the DOM, it creates a hidden iframe at src, attaches a shadow root to the custom element, and starts projecting. When the element is removed, everything tears down.

If you want to project only a piece of the remote — a chart, a panel, a sidebar — add a selector:

<virtual-frame
  src="https://dashboard.example.com"
  selector="#metrics-chart"
  isolate="open"
></virtual-frame>

The full remote still runs in the background, so the selected subtree behaves exactly as it would in its native page. Its event handlers work. Its data fetches work. Its animations work. You just pulled a widget out of another team's app without negotiating an API contract.

If you're in React, it's a component:

import { VirtualFrame, useVirtualFrame, useStore } from "@virtual-frame/react";
import { createStore } from "@virtual-frame/store";

const store = createStore();

function Dashboard() {
  const count = useStore(store, ["count"]);
  const frame = useVirtualFrame("https://remote.example.com", { store });

  return (
    <>
      <p>Count: {count ?? 0}</p>
      <VirtualFrame frame={frame} selector="#counter" />
    </>
  );
}

The store there is worth a second look. It's an event-sourced, proxy-based reactive object that synchronizes between host and remote automatically. Read and write it like a plain object on either side; mutations propagate over the same message channel the projection uses. It's the piece you reach for when "host and remote need to share state" comes up, and it means you don't have to invent a coordination protocol.

There are first-class bindings for Vue, Svelte, Solid, Angular, Next.js, Nuxt, SvelteKit, TanStack Start, SolidStart, Analog, React Router, and a few more. They all sit on the same core engine. Pick whichever is closest to how your page is built.

What you actually get

A few consequences of the projection model that are worth naming explicitly, because they're the things that tend to surprise people:

Layout flow just works. Projected content fills its host element's box and participates in flex and grid like any other child. No width="100%"-then-cry dance. No resize observer hacks. No scroll-inside-scroll confusion.

Theming crosses the boundary. CSS custom properties inherit into the shadow root, so your design tokens — colors, spacing, fonts, dark mode — reach the projection without any coordination with the remote team. They don't even need to know your tokens exist; they just need to use var() for things they want themeable.

Accessibility is inherited. The projected DOM is real DOM in your tree, so focus traversal, screen readers, and keyboard navigation see it as part of the page. You're not fighting the iframe a11y model.

SSR with resumption. The meta-framework integrations can server-fetch the remote, inline the projection inside declarative Shadow DOM, and resume on the client without a second round-trip. First paint is styled and interactive content arrives without the iframe flash.

Cross-origin without proxy gymnastics. No CORS negotiations. No server-side proxy. Ship the bridge once in the remote, and every host everywhere can project it.

What it isn't

Worth being honest about the non-goals, because they come up in design reviews and getting them wrong wastes everyone's time.

Virtual Frame is not an iframe replacement — it still uses one under the hood, because that's how you give the remote its own browsing context. What's different is that you don't see the iframe; its DOM is projected into your host.

It is not a trust boundary from the host's side. The iframe sandboxes the remote's script execution (same-origin policy still applies; the remote's JS can't touch host DOM or globals), but once you project the remote's DOM into your page, your code can read and manipulate that projected tree. If the remote is untrusted, keep the iframe visible and don't project.

It is not module federation. Nothing is shared at build time. No shared React instance, no shared bundle graph. If you need runtime coordination, use the shared store — a typed message channel, not a hidden dependency on a shared import.

It is not a hydration framework. The remote hydrates normally inside its own iframe. You don't rewrite your remote app to make it projectable; any web page will do.

When to reach for it

Virtual Frame fits well when you need to compose multiple independently deployed apps into one page without coordinating a build. When you want to embed UI from another team, tenant, or origin while keeping layout flow and interactivity native. When you want to retire a user-visible iframe that looks and feels like one. When you want to project only a slice of a remote app and let the rest keep running in the background.

Skip it when host and remote already share a build — module federation or a plain component export is lighter. Skip it when you need a hard security boundary against an untrusted remote — keep the iframe visible. Skip it when the remote doesn't need interactivity and doesn't change — a server-rendered fragment is simpler.

Where to go from here

The shortest possible next step: npm install virtual-frame, drop in the custom-element snippet above with a URL you own, and watch it work. Most of the mental model survives contact with five minutes of playing with it.

When you're ready for more:

What is Virtual Frame? — the conceptual overview in depth, including the parts of the mental model this article skipped.
Getting Started — installation, the three integration paths, and the first-projection checklist.
Framework guides — React, Vue, Svelte, Solid, Angular, Next.js, Nuxt, and the rest. Pick yours.
Cross-Origin — the bridge protocol, CSP requirements, and the proxy option for keeping first-party cookies.
Store — the reactive message channel for bidirectional state between host and remote.
API reference — every option, property, and method.

The thesis, one more time: stop embedding remote applications. Project them. The boundary you've been working around doesn't have to be there.

The Illusion of Language: What Directives Really Are

Viktor Lázár — Sun, 09 Nov 2025 11:35:27 +0000

Preface & Introduction — Why This Post Exists

This post is not a rebuttal.

It’s a reflection inspired by the great “Directives and the Platform Boundary” article by Tanner Linsley. I genuinely enjoyed the piece and agree with many of its points — especially around ownership, provenance, and the value of explicit APIs.
What I wanted to add is a slightly different lens: one that comes from building directive-driven tooling and from having lived through a very similar chapter in programming history, long before JavaScript had 'use client' or 'use server'.

Over the past year, I’ve watched countless developers treat directives in JavaScript as if they were actual language features — something built into the JavaScript spec or the runtime environment. And to be fair, at a glance, it does look that way. A string at the top of a file that magically changes how the code behaves feels authoritative.

If you haven’t been following the evolution of React Server Components and frameworks like Next.js: modern React apps now use file-level directives such as 'use client' and 'use server' to control where code runs. They look like simple string literals at the top of a file, but they decide whether a component executes on the server or the client — shaping bundling, rendering and data-flow. That’s where the confusion begins.

But here’s the tension:

Directives look like language features.
Directives feel like language features.
Yet directives are not language features.

They are tooling-level signals — consumed by bundlers, compilers, and build pipelines.

This misunderstanding is not a new phenomenon.
We’ve been here before.

A Personal Flashback

The first time I saw a #pragma once in a C++ codebase as a young developer, I thought:
“Wow, the language has a keyword for this! Why doesn’t JavaScript?”

Except… it wasn’t a language keyword.
It was a compiler instruction. A directive. A hint to the preprocessor, not to the language itself.

Just like 'use strict' wasn’t “JavaScript syntax” at first — and just like 'use client' isn’t “JavaScript syntax” today.

This post explores that parallel. Because understanding the C/C++ preprocessor era is a surprisingly powerful way to understand modern JS directives — why they confuse people, and what we could learn from the past to teach them better.

Why Do Directives Feel Like Language Features?

If you show a newcomer the following code:

'use client';

export function Button() {
  return <button>Click</button>;
}

and ask them what 'use client' is, most will confidently answer:

“It’s part of JavaScript.”

This isn’t ignorance. It’s pattern recognition.

Throughout their entire programming life, file-level “magic statements” have almost always been language semantics, not tooling semantics:

"use strict"
"use asm"

They look like syntax.
They live at the top of the file.
They change behavior.

So the brain does the obvious thing: it classifies them as language.

The TanStack article captures part of this well when it says:

“A directive at the top of a file looks authoritative. It gives the impression of being a language-level truth, not a framework hint.”

This is the crux of the confusion.

The Hidden Mechanism Makes It Worse

Directives blur boundaries because the code that reacts to them is:

invisible
non-local
not traceable through imports

If I write:

import { client } from 'somewhere';

→ I can follow the import. I see who owns it. I can version it. I know what documentation to search for.

But with directives:

there is no import
no namespace
no ownership reference
no callsite to inspect

The behavior “comes from nowhere”.

Which is exactly why they feel like language.

Add Build Tools… and the Illusion Solidifies

Unlike JavaScript keywords, directives do nothing by themselves.

A runtime engine won’t throw if you mistype 'use clinet'.
A bundler or transform plugin decides what to do with it. Some ignore it, some error, some treat it as a string literal.

This leads to the second major confusion:

“If it requires a bundler to work, isn’t it part of the ecosystem platform, not the language?”

From the developer’s perspective, if code changes behavior without explicit imports, the mind defaults to:

✅ language feature
❌ library feature

And that is the trap.

Because what we call “platform” today is actually a stack of tools — not a coherent language surface. Exactly like in the C/C++ era.

A Look Back: C/C++ Macros and the Preprocessor

Long before modern JavaScript build pipelines, the C and C++ world lived through a very similar confusion. And it all started with a layer that sat before compilation: the preprocessor.

To understand today’s directives, we need to briefly revisit three pillars of that era — because they map surprisingly well to what we see today.

The C Preprocessor Was Not the Language — But It Felt Like It

Consider this:

#define PI 3.14

Many beginners encountering this for the first time assume:
“Oh, C has a special language keyword for defining constants.”

Except… #define is not part of the C language grammar.
It’s an instruction to a separate tool that runs before the compiler.

It performs text substitution — not type checking, not syntax analysis, not semantic validation.

Yet, because it lived inside .c/.h files and looked like “code”, generations of developers perceived it as the language.

Sound familiar?

A directive in JS behaves the same way:

'use server';

The JavaScript engine doesn’t know what that means.
The bundler decides what to rewrite before execution.

Both are pre-language phases that masquerade as language.

Pragmas: The Original “Framework Directives”

If macros were like today’s codegen utilities, then #pragma was the closest ancestor to modern directives:

#pragma once

This line is not part of the C++ language spec.
It’s a compiler-specific “hint” — an instruction that affects how the build system treats this file.

No import
No namespace or provenance
No indication of ownership

Different compilers supported different pragmas. Some ignored them. Some produced warnings. Some behaved differently.

Replace “compiler” with “bundler” and you get 2025.

For example:

Next.js reacts to 'use client'
Vite might ignore it
A custom RSC bundler might interpret it differently

It’s the same fragmentation pattern seen 30 years ago.

Include Guards: The First “Invisible Build-Time Behavior”

Before #pragma once became common, C/C++ used include guards to prevent double inclusion:

#ifndef MY_HEADER_H
#define MY_HEADER_H

// header contents

#endif

This pattern:

altered program behavior
existed only for tooling
had no runtime meaning
required knowledge of the build model, not just the language

This is important:

C/C++ forced developers to learn that “code you write in a file” and “the language itself” are not the same thing.

This was a painful but transformative lesson.

We are now at the same educational moment in JavaScript.

Multi-Stage Compilation: A Familiar Pipeline

C/C++ had distinct layers:

Preprocessor → Compiler → Linker → Executable

Modern JS tooling has the same separation, just with cooler names:

Directive Scanner / Loader → AST Transforms → Bundler → Output Chunks

And just like beginners blamed “C++ the language” for preprocessor quirks, today developers blame:

“JavaScript”
“React”
“the platform”

…for behaviors that actually originate from build tooling.

History is repeating itself — almost line for line.

Modern Directives Through the Lens of the Preprocessor Era

Once you see the C/C++ parallels, modern JavaScript directives suddenly make a lot more sense. They are not an evolution of JavaScript syntax — they are an evolution of compiler hints.

Let’s make the mapping explicit:

Preprocessor Era Concept	Modern JS Equivalent
`#pragma`	`'use client'`, `'use server'`
`#define` macros	code transforms / auto-generated wrappers
`#include` guards	module boundary / hydration boundaries
compiler-specific behavior	bundler-specific behavior
multi-stage builds	loader → transform → bundle pipeline

Just like in the 90s, the surface looks deceptively simple — but the real action happens underneath.

Directives Don’t Execute — They Instruct a Tool

A key property of directives is this:

They don’t do anything themselves — they only change how something else behaves.

Here’s a breakdown of what typically happens in a directive-driven pipeline (simplified, but accurate enough):

Read file → Check for directives → Decide environment / boundary →
Run transforms → Generate client/server bundles → Output

Let’s compare that to the C pipeline:

Read file → Preprocessor expands macros + handles pragmas →
Compile → Link → Output

They are structurally identical concepts, just applied to different languages and eras.

Why the Illusion of a Language Feature Persists

Three psychological factors contribute to the confusion:

They look like syntax
Both #pragma once and 'use client' feel like reserved keywords.
They live at the top of the file
Anything that shapes the entire file is often assumed to be language.
They act globally and implicitly
They don’t require instantiation or import.

In other words, directives successfully exploit a linguistic illusion.
They act like a programming language — while not being one.

But Modern Directives Go Further Than C Pragmas

Here’s where things get more interesting:

C pragmas only affected compilation behavior.
Modern directives often affect execution model, code placement, bundling, and runtime boundaries.

For example, 'use server' might:

move code into a server-only chunk
replace calls with RPC stubs
add serialization wrappers
enforce data-flow constraints

This is already beyond what the C preprocessor did.

It’s closer to a macro system + compiler pass.

Which is exactly why understanding the distinction matters:

If something affects runtime execution and code placement, we should not treat it as “just a string at the top of the file”.

And yet, ironically, most misconceptions arise because that is exactly how it appears.

Build Tools Are the Real Interpreter of Directives

Just like different C compilers treated pragmas differently, modern JS tooling varies, too:

Next.js interprets 'use client' one way
Vite + RSC implementations another
Third-party bundlers a third way

If tomorrow another framework introduced:

'use streaming-server';

JavaScript engines wouldn’t care.
Tools would decide what it means.

And that is the mental shift we need developers to make:

Directive ≠ language
Directive = build instruction

They live in userland — not in the spec.

Before we move on, it’s worth pausing for a moment. The parallels with C and C++ are useful for understanding the shape of directives, but they can still feel abstract until you’ve seen them in practice. To bring the idea into clearer focus, let’s look at a concrete example from today’s ecosystem — one that makes the theory a bit more tangible, and shows how these compiler hints manifest in real, modern code.

📦 When Inline Server Functions Reveal the Need for Directives

I once ran into a case that perfectly exposed why some server behaviors cannot be left to runtime.

Consider an inline server function defined inside a Server Component, capturing variables from its local scope:
export default function Dashboard() {
  const rate = 0.27;

  async function save(value) {
    'use server';
    return value * rate; // ← captures "rate" from the component scope
  }

  return <button onClick={() => save(10)}>Save</button>;
}
At first glance, this feels like a normal function call. But for this to work, the bundler must do something subtle and non-negotiable:

detect that save is a server function,

hoist it into a server-only module,

perform AST-level closure analysis to capture rate,

and generate a stable, directly callable reference for the client — not a runtime-constructed wrapper.

A runtime helper cannot solve this.
By the time the code runs, the closure is gone and the intent is already lost.
The function must be transformed before the program exists, so that the client can call it as a direct function, not a proxy we stitched together too late.

This is why directives fit this space so well: they tell the build tools at the moment of definition what this function truly is, giving them time to shape it accordingly.

Some decisions must happen while the code is still being woven — not after it is already alive.

The Educational Gap — and What We Can Learn From History

If you step back and look at the confusion around directives today, you’ll notice something striking:

The problem is no longer technical — it’s educational.

We’ve repeated a historical pattern:

A tool-level construct looks like language
Developers assume it is language
The mental model becomes wrong
Confusion spreads faster than documentation can correct it

This happened with the C preprocessor.
It’s happening again with JavaScript directives.

We Need to Teach the Layering — Not Just the Feature

If we teach 'use server' as:

“This makes your function run on the server.”

…we’ve already lost.

Because that sentence hides 4 separate layers:

Layer	Responsible For
Syntax	writing a string literal
Loader	detecting the directive
Build tools	transforming / splitting code
Runtime	enforcing the boundary

If developers don’t understand which layer is responsible for what, they will blame “JavaScript” for a bundler problem — just like C developers once blamed “the language” for preprocessor bugs.

What the C/C++ Community Eventually Learned

Over time, C/C++ education evolved:

Early teaching:
“Here’s how to use #define and #pragma.”

Mature teaching:
“Here’s what the preprocessor is, and why it’s separate from the language.”

After that shift, confusion dropped dramatically. No serious C++ course today teaches macros without first teaching the mental model of the compilation stages.

We need the same shift for JS directives.

Directives Aren’t Bad — They’re Powerful, If Understood

This post is not an argument against directives. They serve a purpose:

Conveying intent declaratively
Reducing boilerplate
Helping tools optimize and separate code
Giving the developer a simple switch for complex behaviors

In fact, some of the most ergonomic server/serverless features would be far more cumbersome without them.

But the price of ergonomics is clarity debt.

If we don’t teach where the magic comes from, developers misattribute the source of truth — and debugging collapses.

A Simple Mental Model to Teach (Starting Tomorrow)

I like to explain directives with a single sentence:

“A directive is a note you leave for your build tools — not for JavaScript.”

That line alone fixes 70% of misunderstandings.

Add one analogy:

“If #pragma once was not C++ syntax, then 'use client' is not JavaScript syntax either.”

And suddenly, people get it.

This doesn’t require more docs — it requires better framing.

A Practical Step Toward Clarity: A TypeScript Plugin for Directives

Before wrapping up, I want to share one more concrete step I took to reduce this confusion in real-world codebases. If part of the problem comes from directives looking like language yet lacking any formal structure, then giving them type-level meaning is one way to bridge the gap.

I built a small TypeScript plugin called typescript-plugin-directives that brings type safety and IntelliSense awareness to directives. It allows teams to:

define their own directive vocabulary,
validate them at compile time,
get editor hints and autocomplete,
and avoid silent typos like 'use clinet'.

The goal isn’t to “standardize” directives, but to make their intent explicit and visible to both developers and tooling — without needing a bundler to interpret them first.

You can try it here:

npm: https://www.npmjs.com/package/typescript-plugin-directives
GitHub: https://github.com/lazarv/typescript-plugin-directives

It’s intentionally lightweight — just a small layer to help the mental model click earlier, and to give directives a more formal shape inside TypeScript projects.

There’s a common assumption that a TypeScript plugin could “enforce” directives — that if the plugin knows about them, the system becomes safe by default.
But a TS plugin lives in the Language Service. It can provide awareness, warnings, and guidance — yet it still doesn’t run where code is actually transformed. It doesn’t participate in compilation or bundling.

A plugin can help identify directive usage, but it cannot enforce their semantics.
For that, the compiler needs a signal of intent — something the type system can understand.

To enable this, I expose a global Directive type in my plugin. Authors can use satisfies not to inform the editor, but to inform the TypeScript compiler that a given string is intended to be a directive:
'use server' satisfies Directive;
This doesn’t change behavior or trigger any transformation.
What it does is far simpler and more fundamental:

It tells the type system:
“Treat this as a directive — and validate it as such.”

It aligns intent with the compiler, not with runtime, and not only with the IDE.

The actual separation of worlds — hoisting inline server functions out of a component, analyzing captured scope, generating a directly callable boundary — still belongs entirely to the build. The type system can acknowledge intent, but the bundler is the one who must act on it.

One practical caveat: today, some tooling — including Next.js — expects directives to appear as bare string literals. When written as 'use server' satisfies Directive, the directive may no longer be detected, since the literal is no longer in the exact form the framework scans for. Until this changes, this pattern won’t be picked up by Next.js.

There is one more subtlety worth mentioning. This type-level intent only matters if a type-checker is actually running. Many modern toolchains — esbuild, SWC, Oxc, Bun, even most Deno and Vite setups — do not type-check at all. They simply strip types and move on. In those environments, the Directive + satisfies expression becomes a silent note to the compiler that never had a chance to listen.

Closing Reflection

The article from Tanner raises a valuable conversation — one worth having early, before bad habits ossify. I don’t believe the goal should be to eliminate directives; they clearly solve real problems. But we can learn from history, and avoid the confusion that entire generations of C/C++ developers had to unlearn.

We’ve been here before.
We know how this story goes.
This time, we can skip the decade of confusion in the middle.

Teach the layers.
Teach the provenance.
Teach the mental model.

And directives will stop feeling like “secret language features” — and start feeling like the powerful, intentional compiler hints they actually are.