I mean the metaframework stopped being the most interesting boundary in the system.

For a long time, the deal was great: web apps had too many decisions, and a metaframework showed up with one coherent answer. Routing, rendering, data loading, server code, bundling, deployment, caching, images, CSS, and environment config all got pulled into one mental model.

That helped.

But the more the framework owns, the more the actual shape of the product disappears into runtime behavior, compiler transforms, generated manifests, and deployment adapter rules. At some point the app is not simpler. It is just harder to see.

The thing that changes the tradeoff now is AI agents.

Codex, Claude Code, and similar tools are good at producing explicit scaffolding. They can create the route, register it, wire the test, update the manifest, and follow the repo's local patterns. That makes the next useful move less about hiding structure behind another runtime abstraction, and more about generating clear code that teams can own.

The Old Deal

The old deal was runtime consolidation.

flowchart TD
  app["Application"] --> framework["Metaframework runtime"]
  framework --> router["Router"]
  framework --> data["Data loading"]
  framework --> server["Server functions"]
  framework --> bundler["Bundler integration"]
  framework --> deploy["Deploy adapter"]
  framework --> cache["Cache behavior"]

That shape is seductive. Need a route? Put a file in the right directory. Need a mutation? Export a server function. Need caching? Use the blessed helper. Need deployment? Pick the adapter.

You get a lot done quickly because the framework makes big choices feel small.

The cost shows up later. The route is not just a file. The server function is not just a function. The cache is not just a cache. They are all pieces of a larger runtime contract, and that contract may be partly generated, partly inferred, and partly specific to one hosting path.

When everything important is hidden in framework convention, understanding the app means understanding the framework's private model of the app.

The Runtime Got Too Important

Modern metaframeworks do not just render pages. They decide where code runs, split bundles, serialize server references, infer static and dynamic behavior, wrap request caches, generate manifests, and map one source tree onto several runtime targets.

flowchart LR
  source["Source tree"] --> compiler["Framework compiler"]
  compiler --> manifest["Generated manifests"]
  compiler --> client["Client bundles"]
  compiler --> server["Server bundles"]
  manifest --> runtime["Framework runtime"]
  client --> runtime
  server --> runtime
  runtime --> platform["Host platform"]

Some of that belongs at runtime. Requests have to be served. Navigation has to work. Streaming has to run somewhere.

But a lot of the important shape can be decided before the app runs: route tables, API contracts, server reference maps, feature boundaries, entrypoints, asset graphs, environment policy, and deploy metadata.

Those are better as build outputs than vibes.

If the build can generate them, the build can also check them, diff them, document them, and fail early when they drift.

Build Time Is The Better Boundary

The healthier version looks more like this:

flowchart TD
  source["Application source"] --> buildGraph["Build graph"]
  buildGraph --> generated["Generated app structure"]
  buildGraph --> checks["Static checks"]
  buildGraph --> bundles["Runtime bundles"]
  buildGraph --> docs["Generated maps"]

  generated --> app["Owned application code"]
  checks --> app
  bundles --> deploy["Deployable artifacts"]

This changes the relationship with the framework.

The framework can still be powerful, but it is no longer the box the product lives inside. It becomes a generator, compiler, checker, and dev server for an app whose structure is visible.

That visibility matters. Reviewers can read a diff. Tests can point at concrete files. Boundary rules can run before deploy. A future teammate can inspect the route map or API contract without learning a pile of runtime inference rules first.

Agents Change The Cost Model

This is the part that feels different from five years ago.

The old reason to prefer deep framework abstraction was that explicit structure was expensive. Nobody wanted to write the boring glue. So the framework hid it.

AI agents make that bargain less compelling. Codex or Claude Code can handle the glue. They can look at the repo, copy the local convention, add the obvious files, and adjust the nearby tests.

That does not mean the agent should create more magic. It means the agent can afford to create more ordinary code.

Verbose Scaffolding Is Back

We spent years treating boilerplate as the enemy.

Some boilerplate is bad. Nobody wants to hand-wire the same fifteen files every time they add a page. Nobody wants copied data loaders that quietly drift.

But explicit scaffolding is different from busywork.

I would rather have:

• a real route module than a hidden route record
• a named server endpoint than an opaque server reference
• a visible cache policy than cache behavior inferred from callsite magic
• an import boundary enforced by the build than a package name pretending to be architecture

The old objection was fair: explicit code costs time.

That objection is weaker now. Agents and generators are good at boring code. They can leave behind ordinary files instead of another layer of framework indirection.

flowchart LR
  intent["Developer intent"] --> agent["AI agent or generator"]
  repo["Repo conventions"] --> agent
  buildGraph["Build graph"] --> agent
  agent --> files["Concrete files"]
  files --> review["Human review"]
  review --> app["Owned app structure"]

The important part is the output. It should not be magic. It should be code the team can read, change, delete, and blame.

That is the part agents make newly cheap: not less structure, but more explicit structure with less typing.

Default To Eject Mode

The best default is not "never use a framework." That is silly.

The best default is: use the framework as if you already ejected.

flowchart TD
  framework["Framework"] --> generate["Generate"]
  framework --> check["Check"]
  framework --> compile["Compile"]
  framework --> serve["Serve"]

  app["Application"] --> routes["Routes"]
  app --> api["API contracts"]
  app --> data["Data clients"]
  app --> cache["Cache policy"]
  app --> deploy["Deployment shape"]

  generate --> app
  check --> app
  compile --> app
  serve --> deploy

Eject mode does not mean giving up good tools. It means the framework helps create and maintain the application shape instead of hiding it.

The route tree can be conventional, but the route table should be visible. Server functions can be ergonomic, but the API boundary should be named. Caching can have defaults, but the policy should be inspectable. Deployment can be integrated, but the artifact should be understandable.

That is where "more boilerplate" starts to mean "less magic."

The New Deal

The metaframework is dead as the central abstraction.

Not because routing, rendering, dev servers, or deployment adapters stopped mattering. They still matter a lot.

But the next jump is not another layer of runtime cleverness. It is build-time generation plus explicit ownership, with AI agents handling the scaffolding work that used to make explicit architecture feel too expensive.

Use the framework to compile, optimize, and serve. Use the build graph to make the product shape concrete. Use agents like Codex and Claude Code to create the boring structure. Keep the important boundaries visible.

Start with the code you would want after the abstraction leaks, and let the tools help you keep it boring.

New folder, new package.json, new package name.

It is tidy. It makes imports look official. It gives a team something that feels like a boundary.

The trouble is that it quietly mixes up two different things:

• a folder of code with an owner
• an npm package with a public name

Those are not the same thing, and treating them as the same thing makes the repository harder for both people and tools to understand.

The common pattern is to put a package.json in every meaningful folder, give it a name like @acme/payments, add it to a workspace, and import it from other code:

import {calculateTax} from "@acme/payments";

That import looks clean. It also hides a lot of machinery for code that never leaves the repository.

If the package is not published, installed by another repository, or consumed through a stable external contract, the package name is not really a product boundary. It is an alias with ceremony. The repository now has two naming systems: the filesystem and the package graph.

The Package Name Trap

The filesystem already has a name for the code:

packages/payments/calculate-tax.ts

The package manifest invents another one:

{
  "name": "@acme/payments"
}

Once both names exist, every tool has to answer questions the code did not really need to ask:

• Which folder owns @acme/payments?
• Is that name a workspace package, an installed dependency, or both?
• Does the import resolve to source, compiled output, or a package entrypoint?
• Which exports, types, main, module, and sideEffects fields matter for this tool?
• Does the bundler see the same graph as TypeScript, tests, lint, and the build system?

That indirection is worth paying for public packages because public packages need a distribution contract. It is much less convincing for private internal code.

It gets worse when internal packages use root entrypoints as the normal way to import anything:

import {Button, Modal, TextField} from "@acme/ui";

That entrypoint is usually a barrel file. It is pleasant to read, but the tools still have to resolve the re-export graph behind it. Marvin Hagemeister's "The barrel file debacle" is the canonical writeup here. The Next.js local development guide now explicitly warns that barrel files can slow builds because the compiler has to parse them to check for side effects. Atlassian also published a large migration story, "How We Achieved 75% Faster Builds by Removing Barrel Files", where removing barrel files improved TypeScript, test selection, and CI performance.

The pattern is familiar:

flowchart LR
  import["import from a short name"] --> alias["package name or barrel"]
  alias --> resolver["resolver work"]
  resolver --> source["actual source file"]
  resolver --> extra["extra files in the graph"]

A short import is not free if every tool has to chase a larger graph to understand it.

Public package entrypoints are still useful. A published library should have a small, documented API. But that is the edge of the repository. It does not need to become the default way internal files talk to each other.

Relative Imports Are Not Great Either

The obvious alternative is relative imports:

import {calculateTax} from "../../payments/calculate-tax.js";
import {formatMoney} from "../../../core/money/format.js";

Relative imports are honest. They do not need package manager magic, and they can be resolved from the importing file alone.

They are also pretty annoying in a large codebase.

Move a file and the import path changes. Move a folder and all of its consumers may need edits. A dependency from checkout to payments is encoded as ../../.., which is technically precise and semantically useless.

Relative paths make local file movement expensive and make architecture harder to read. They answer "how do I walk the directory tree from here?" when the reviewer wants to know "which module does this depend on?"

So I do not think the choice is really package names versus relative paths. The nicer target is absolute imports over the repository's source tree.

Use One Root Import Space

For Node and TypeScript projects, the cleanest version I have found is a single private root package.json with a package.json#imports map. TypeScript supports these package imports in node16, nodenext, and bundler module resolution modes:

{
  "private": true,
  "type": "module",
  "imports": {
    "#apps/*": "./apps/*",
    "#packages/*": "./packages/*",
    "#tools/*": "./tools/*"
  }
}

Then source imports by repository path:

import {calculateTax} from "#packages/payments/calculate-tax.js";
import {formatMoney} from "#packages/core/money/format.js";

This buys a few things at once.

The import path stays stable when the importing file moves. The path says what the dependency is, not how many .. hops it takes to reach it. The resolver has one root map instead of one package manifest per internal folder. TypeScript, Node, tests, lint, and bundlers can share the same naming convention instead of each growing a slightly different alias system.

It also matches how many other language ecosystems feel in practice. Go imports by module path plus directory. Rust code commonly uses crate-rooted paths like crate::feature::module. Python packages usually import from a package root instead of walking the tree from every file. Java and Kotlin package names are absolute namespaces.

The point is not that JavaScript should pretend to be Go or Rust. The point is simpler: internal code should have a stable absolute address that maps back to the source tree.

Boundaries Are Not Resolution

The usual objection is:

If everyone can import any source file, how do we keep boundaries?

That is the right question. Package names are just a clumsy answer.

Resolution and visibility are different jobs. Absolute imports should tell tools where a file is. Boundary rules should tell developers whether that dependency is allowed.

Go has a useful convention here. A directory named internal can only be imported by code in the parent tree. In a TypeScript monorepo, the same convention is easy to read:

packages/
  checkout/
    checkout-page.tsx
    internal/
      price-breakdown.ts
      shipping-rules.ts
  payments/
    charge-card.ts

This import should be allowed:

import {renderPriceBreakdown} from "#packages/checkout/internal/price-breakdown.js";

from code under packages/checkout.

The same import should be rejected from packages/payments, packages/search, or an app that happens to know the file exists.

That enforcement can live in lint rules, build-system visibility, dependency-cruiser, Nx module boundaries, a custom ESLint rule, Bazel visibility, or a small repository-specific checker. The rule needs to compare the importer path with the imported path. A package alias cannot express that by itself.

This split keeps the system honest:

• Import maps make files addressable.
• Boundary checks decide which addresses are allowed.
• Package manifests describe artifacts that leave the repository.

When those jobs are separate, each one becomes easier to reason about.

package.json Is for Public Artifacts

I am not arguing that package.json is bad. It is good at describing an npm package. That is its job.

Use one when the code is consumed outside the monorepo:

• a public npm package
• a private package published to an internal registry
• an SDK installed by another repository
• a plugin package loaded by a package manager
• a package with semver, changelog, peer dependencies, and an external API

In that world, package.json fields are real product surface:

{
  "name": "@acme/payments-sdk",
  "version": "3.2.0",
  "type": "module",
  "exports": {
    ".": "./index.js",
    "./testing": "./testing.js"
  },
  "types": "index.d.ts",
  "peerDependencies": {
    "react": "^19.0.0"
  }
}

That is a real distribution contract. Consumers outside the repository should not know your source tree. They should know the public package name and the public subpaths you support.

Internal code is different. If the only consumer is the same repository, a package manifest often turns into ritual:

• fake versions
• fake package names
• fake publish boundaries
• dependency lists that duplicate build metadata
• generated exports fields for code that is never exported
• package manager linking for code that could be resolved directly

Internal package manifests can work. They are just often solving the wrong problem.

FormatJS Is a Useful Example

The FormatJS repository is a nice example because it is both a real public library monorepo and a modern TypeScript codebase.

The repository publishes real packages such as @formatjs/intl, @formatjs/cli, @formatjs/icu-messageformat-parser, intl-messageformat, and react-intl. Those packages deserve package manifests because people install them from outside the repo. They have names, versions, entrypoints, peer dependencies, and compatibility expectations.

The interesting bit is that the root package is private and defines an internal import map:

{
  "name": "formatjs-repo",
  "private": true,
  "imports": {
    "#packages/*": "./packages/*"
  }
}

That lets source files import by repository path instead of inventing package names for every internal source boundary:

import {type MessageDescriptor} from "#packages/intl/types.js";
export * from "#packages/intl/types.js";

react-intl does the same thing for its own internals:

import {
  createFormattedComponent,
  createFormattedDateTimePartsComponent,
} from "#packages/react-intl/components/createFormattedComponent.js";

At the same time, react-intl also imports and re-exports the public @formatjs/intl package:

export {
  createIntlCache,
  type FormatDateOptions,
  type MessageDescriptor,
} from "@formatjs/intl";

That distinction is the whole point.

FormatJS still has package manifests for publishable artifacts. @formatjs/intl has name, version, exports, types, and workspace:* dependencies. react-intl has its own manifest, peer dependencies, and public subpath exports. Those are real package boundaries because external users install them.

But internal source references do not have to pretend every folder is an npm package. The root #packages/* map gives the repository a stable internal address space.

FormatJS is not an argument against package manifests. It is an argument for putting them at the distribution boundary, not every source boundary.

There is one nuance: public package entrypoints still look like barrels. packages/intl/index.ts re-exports the API for @formatjs/intl, and packages/react-intl/index.ts does the same for React users. That is reasonable because a public package needs a public API.

The mistake would be forcing all internal code to go through those public entrypoints when it really depends on a specific source module.

Pick Tooling That Does Not Require Fake Packages

The build system should let you create a code boundary without creating an npm package.

You should be able to say:

• these files form a unit
• these are its runtime dependencies
• these are its test dependencies
• this is how to typecheck it
• this is how to test it
• these imports are allowed
• these imports are forbidden

None of that inherently requires a package.json.

Some tools make package manifests the only project discovery mechanism. That nudges teams into creating fake npm packages just to get typechecking, tests, cache keys, ownership, or dependency boundaries. At small scale, this feels fine. At large scale, the repository accumulates a second filesystem made out of package names.

Better tooling lets packages be arbitrary source units. Bazel targets can do this. Custom TypeScript project generators can do this. Nx can do parts of this with project configuration and module boundary rules. A repo-specific lint or dependency checker can do this. The exact tool matters less than the capability.

The workflow should feel more like this:

create folder -> add source -> add test target -> import by absolute path -> enforce boundaries

and less like this:

create folder -> invent package name -> add package.json -> update workspace -> teach every tool how to resolve the fake package -> import through entrypoint -> fight barrels later

The Rule

Use package names for code that leaves the monorepo.

Use absolute root imports for code that lives inside the monorepo.

Use internal folders and lint/build visibility for private implementation details.

Use public package entrypoints only at real public package boundaries.

That gives the repository one source address space, real distribution contracts where they matter, and fewer layers of indirection for every tool that has to understand the graph.

That works for a while. Then the same product needs to run in more than one browser, inside an embedded third-party surface, in a desktop shell, in mobile webviews, or across a few generations of browser support.

At that point, "the browser" is not one platform anymore. It is a family of runtimes with different APIs, storage behavior, networking rules, telemetry paths, and localization support.

The mistake is letting every feature handle those differences on its own.

Application Anatomy

Most web apps end up with layers, even if nobody names them at first.

flowchart TB
  app["Application"]

  subgraph featureLayer["Product features"]
    search["Feature A"]
    settings["Feature B"]
    checkout["Feature C"]
  end

  subgraph coreLayer["Core components"]
    design["Design system"]
    router["Router"]
    sharedUi["Shared UI"]
    domain["Domain helpers"]
  end

  subgraph runtimeLayer["Web platform runtime"]
    direction LR
    io["IO"]
    storage["Storage"]
    telemetry["Telemetry"]
    analytics["Analytics"]
    l10n["Localization"]
    config["Config"]
    polyfills["Polyfills"]
  end

  subgraph nativeLayer["Native capabilities"]
    browser["Browser APIs"]
    webview["Webview APIs"]
    desktop["Desktop shell APIs"]
  end

  app --> featureLayer
  featureLayer --> coreLayer
  coreLayer --> runtimeLayer
  runtimeLayer --> nativeLayer

The application owns product composition. Product features own user workflows. Core components own reusable product building blocks.

The web platform runtime owns the messy part: making the same capability behave consistently across the environments where the product runs.

That layer is easy to underinvest in because it rarely ships a feature by itself. When it is missing, though, the cost shows up everywhere else.

Code Sharing Needs Rules

Sharing everything sounds efficient. In practice, it often produces abandoned utilities, ambiguous ownership, and packages nobody wants to delete.

Sharing nothing is not better. It creates duplicated tracking code, duplicated storage helpers, duplicated fetch wrappers, duplicated polyfill decisions, and a different failure mode in every feature.

The useful middle is to decide which layers are meant to be shared.

flowchart TD
  app["Application code\nusually app-specific"]
  feature["Product feature\nshareable at feature boundary"]
  core["Core components\nshared intentionally"]
  runtime["Web platform runtime\nshared by default"]
  internals["Feature internals\nnot shared"]
  tiny["Random tiny helpers\nnot shared by default"]

  runtime --> core
  core --> feature
  feature --> app
  feature --> internals
  app --> tiny

  classDef shared fill:#e8f5e9,stroke:#2e7d32,color:#111;
  classDef private fill:#fff3e0,stroke:#ef6c00,color:#111;
  class runtime,core,feature shared;
  class internals,tiny private;

The rule I like is: share platform, core components, and deliberate product features. Do not share random internal components just because two places happen to want them today.

That rule needs enforcement. Import boundaries, package visibility, lint rules, ownership, and dependency checks matter because "please be thoughtful" does not scale.

What The Runtime Owns

A web platform runtime is not a utils package. It owns the stuff every serious feature eventually needs.

flowchart LR
  runtime["Web platform runtime"]

  runtime --> ecma["Language and browser features\npolyfills, CSS support, browser targeting"]
  runtime --> io["IO\nfetch wrapper, auth headers, retries, tracing"]
  runtime --> storage["Persistence\nquota, local cache, storage adapters"]
  runtime --> telemetry["Telemetry\nRUM, errors, client logs"]
  runtime --> analytics["Analytics\ninteraction metadata, funnels, attribution"]
  runtime --> l10n["Localization\nlocale data, translations, formatting"]
  runtime --> config["Config\nruntime config, feature flags, environment dimensions"]

Each box looks boring until it is implemented five different ways.

Polyfills Are A Delivery System

Polyfills are not just a list of imports at the top of the app.

Different browsers need different polyfills. Different locales need different data. Mobile Safari has different gaps from Chromium. Embedded runtimes and desktop shells may support some native APIs but not others. Localization data can be especially large because it often pulls from Unicode CLDR data.

A platform layer should decide:

• which browser and runtime versions are supported
• which APIs can be polyfilled
• which APIs must be banned or guarded
• which locale data is loaded for which user
• how polyfill bundles are tested

flowchart TD
  request["Page request"] --> detect["Detect runtime\nbrowser, version, locale, shell"]
  detect --> policy["Capability policy"]
  policy --> js["JS polyfills"]
  policy --> css["CSS support checks"]
  policy --> locale["Locale data"]
  js --> boot["App bootstrap"]
  css --> boot
  locale --> boot

The important bit is that each feature should not make this up on the fly. Features should write against a known platform contract.

There is useful prior art here. Dropbox has historically shipped targeted bootstrap bundles for different browser/locale combinations. Yahoo-style dynamic polyfill services are another version of the same idea: do not make every client pay for every compatibility layer. Resolve the runtime shape, then send the smallest safe set of patches.

IO Should Be A Platform API

Network code is one of the first places where cross-platform assumptions break.

The browser has fetch. An embedded third-party surface may need an iframe bridge. A desktop shell may have a native transport. A mobile webview may need special headers or tracing. Some environments have stricter CORS behavior. Some need request correlation with native logs.

If every feature wraps fetch directly, there is no single place to handle this.

flowchart LR
  feature["Product feature"] --> client["Platform IO client"]
  client --> browser["Browser fetch"]
  client --> embed["Iframe bridge"]
  client --> desktop["Desktop native bridge"]
  client --> mobile["Webview bridge"]

  client --> trace["Tracing"]
  client --> auth["Auth context"]
  client --> retry["Retry / timeout policy"]

The platform IO client does not need to hide every detail. It does need to centralize the defaults people otherwise forget: tracing, auth propagation, request metadata, retries, timeouts, and runtime-specific transports.

Persistence Is Shared Whether You Like It Or Not

Browser storage is not infinite, not uniform, and not truly feature-local.

localStorage, IndexedDB, Cache Storage, cookies, and memory caches all have runtime-specific behavior. Private browsing modes can restrict storage. Webviews can behave differently from browsers. Multiple product features can starve each other if each one assumes storage is free.

That makes persistence something the platform has to own.

flowchart TD
  featureA["Feature A"] --> store["Platform storage API"]
  featureB["Feature B"] --> store
  featureC["Feature C"] --> store

  store --> quota["Quota policy"]
  store --> eviction["Eviction policy"]
  store --> adapters["Storage adapters"]
  adapters --> local["localStorage"]
  adapters --> idb["IndexedDB"]
  adapters --> native["Native storage bridge"]
  adapters --> memory["Memory fallback"]

The platform should provide a storage API, decide what is cacheable, monitor usage, and make fallback behavior explicit.

Telemetry And Analytics Are Different

Telemetry answers: is the application healthy?

Analytics answers: what did the user do?

They often share transport and metadata, but they are not the same system.

Telemetry needs page load metrics, interaction latency, client errors, logs, app version, browser version, route, device class, and deploy correlation.

Analytics needs product events, interaction hierarchy, attribution, experiment dimensions, and funnel metadata.

flowchart TD
  ui["UI interaction"] --> metadata["Interaction metadata\nsurface, role, route, feature"]
  metadata --> analytics["Analytics event"]
  metadata --> telemetry["Telemetry context"]
  telemetry --> rum["RUM metrics"]
  telemetry --> logs["Client logs"]
  telemetry --> errors["Error reports"]

A good platform layer makes the common case automatic. A button from the design system can carry semantic metadata. A route can provide page context. A logging client can attach app version and browser dimensions without every callsite remembering to do it.

This is also where older web platform work is still relevant. Dropbox invested heavily in real-user metrics because frontend performance work needs cohorts: browser, device class, route, deploy version, and network shape. Yahoo's instrumentation systems had a similar lesson from a different angle: user behavior is only useful when events carry enough context to explain where they came from.

In other words, telemetry and analytics should not be a thousand hand-written event calls. The platform should make the boring metadata automatic.

Localization Is Runtime Work Too

Localization is not only a translation pipeline.

The runtime also needs locale data, number/date formatting, pluralization rules, message loading, fallback behavior, and the ability to avoid shipping every locale to every user.

flowchart LR
  source["Colocated messages"] --> extract["Extract catalogs"]
  extract --> package["Package translations"]
  package --> cdn["Serve by locale"]
  runtime["Runtime locale resolver"] --> cdn
  runtime --> polyfill["Locale polyfills"]
  cdn --> app["Localized UI"]
  polyfill --> app

The feature should own the words. The platform should own extraction, packaging, loading, and runtime guarantees.

Again, the interesting prior art is not the specific company implementation. It is the pattern. Large web properties do not ship one giant locale payload to everyone. They extract messages, package locale data, and load the right pieces for the user and runtime.

Config Needs A Real Shape

Every platform grows configuration.

The problem is not config existing. The problem is each feature inventing its own way to resolve it.

A platform config layer should define:

• the dimensions config can vary by
• where config is loaded from
• what is available at build time vs runtime
• how defaults work
• how missing or malformed config fails
• how config usage is tested

flowchart TD
  dimensions["Dimensions\nregion, locale, device, runtime, app version"] --> resolver["Config resolver"]
  files["Feature config declarations"] --> resolver
  remote["Remote config service"] --> resolver
  defaults["Defaults"] --> resolver
  resolver --> feature["Feature receives typed config"]

Typed config matters because config bugs are otherwise discovered as runtime weirdness.

Platform Adapters

Once the runtime has a contract, each environment can implement it differently.

flowchart TD
  contract["Web platform runtime contract"]

  contract --> browser["Browser adapter"]
  contract --> embed["Third-party embed adapter"]
  contract --> desktop["Desktop shell adapter"]

  browser --> bFetch["fetch"]
  browser --> bStore["IndexedDB / localStorage"]
  browser --> bLog["browser logging"]

  embed --> eFetch["iframe bridge / CORS-safe transport"]
  embed --> eStore["restricted storage"]
  embed --> eLog["host-aware logging"]

  desktop --> dFetch["native network bridge"]
  desktop --> dStore["native storage bridge"]
  desktop --> dLog["native logging bridge"]

This is where the extra structure starts paying rent. Product features keep using one platform contract while the runtime chooses the right implementation for the environment.

It also keeps framework assumptions in check. A framework may assume the platform is a browser plus a Node server. Your product may need browser, embed, desktop, mobile webview, and worker surfaces. The platform layer is where those assumptions become explicit.

Core Components Sit Above The Runtime

Core components can assume the runtime exists.

That lets a design system provide components that are already:

• instrumented
• localized
• accessible
• theme-aware
• compatible with platform navigation
• connected to platform config where needed

flowchart TD
  runtime["Web platform runtime"] --> design["Design system"]
  runtime --> router["Router"]
  runtime --> ui["Shared UI components"]
  design --> feature["Product feature"]
  router --> feature
  ui --> feature

This is better than asking every feature to remember how to tag every button, load every translation, or log every error.

A Practical Starting Point

Do not start by building a grand platform.

Start with the things every feature already reimplements:

1. logger
2. analytics client
3. IO client
4. localization runtime
5. polyfill policy
6. feature flag or config client
7. storage API
8. design system integration

Each one should have a small contract, a browser implementation, and a story for at least one non-browser environment if that is on the roadmap.

flowchart LR
  start["Repeated feature code"] --> choose["Pick one platform capability"]
  choose --> contract["Define a small contract"]
  contract --> browser["Implement browser adapter"]
  browser --> migrate["Migrate one feature"]
  migrate --> enforce["Add lint/import guardrails"]
  enforce --> next["Move to the next capability"]

The goal is not to centralize everything. Centralize the parts where inconsistency is expensive.

The Rule

If a product feature has to know which runtime it is running in, that is a smell.

Sometimes it is unavoidable. But most of the time, the feature should know what capability it needs, not which bridge, polyfill, storage backend, telemetry client, or config source provides it.

That is what a cross-platform web runtime buys you: not a bigger abstraction for its own sake, but a place to put the decisions that should not be rediscovered by every feature team.

Once the server is part of the component model, frameworks can make server work feel like ordinary application code. You render on the server. You stream UI. You pass server references through the tree. Some frameworks also let client interactions call server functions without writing a route by hand.

That is a good ergonomic move. It removes a lot of boilerplate around mutations that are tightly coupled to one screen.

The catch is that the wiring is still an API. It is just an API generated by the framework.

That starts to matter when an app is deployed continuously, cached by browsers and CDNs, or served by more than one backend version at the same time.

Next.js Server Actions are the concrete example I know best, so I will use them here. But the deeper point is not specific to one framework. If a client can invoke server code through a generated server reference, that reference has API-like failure modes.

The Normal Shape

Without a generated server function transport, a client mutation usually has an explicit endpoint:

flowchart LR
  ui["Client UI"] --> route["POST /api/update-item"]
  route --> auth["Auth / authz"]
  auth --> schema["Input validation"]
  schema --> service["Service call"]
  service --> result["JSON response"]

That endpoint is visible. You can give it a stable path, a schema, rate limits, logs, dashboards, deploy compatibility rules, and migration plans.

With an RSC-style server function, most of that ceremony can disappear. In Next.js, that looks like a Server Action:

// app/actions.ts
'use server'

export async function updateItem(id: string, value: string) {
  // auth, validation, mutation
}

// app/item-form.tsx
'use client'

import { updateItem } from './actions'

export function ItemForm() {
  return <button onClick={() => updateItem('item_123', 'new value')}>Save</button>
}

That is nice. It also makes it easy to forget that the browser still has to call the server somehow.

The Next docs are explicit: Server Functions are reachable through direct POST requests, so authentication and authorization must happen inside every Server Function. The "use server" directive does not make a function private to your component tree.

What Gets Generated

The exact implementation is a framework detail, but the rough shape of a generated server function transport looks like this:

flowchart TD
  source["Source file\nserver function export"] --> transform["Framework compiler transform"]
  transform --> id["Generated server reference ID"]
  id --> manifest["Server reference manifest"]
  id --> clientStub["Client reference\ncallServer(referenceId)"]
  clientStub --> request["POST request\nreference ID + serialized args"]
  request --> handler["Server function handler"]
  manifest --> handler
  handler --> fn["Original server function"]
  fn --> response["RSC payload / redirect / revalidation / result"]

A few details are worth calling out:

• the client does not ship the original server function
• the client ships a reference to a generated server ID
• the browser invokes that ID with a request
• the server uses a manifest to route the ID back to the original function
• the function arguments and return value must fit the serialization rules

This is why server functions can feel like magic. The framework created a small RPC layer for you.

It is also why they need to be treated with the same care as any other RPC layer.

The Generated ID Is Not A Contract

The generated server reference ID is not a stable API name like /api/update-item.

At build time, the framework needs to decide which server function an ID points to. The inputs to that ID may include implementation details such as a build salt, file path, export name, bundler metadata, and function-shape information.

That means a small code or framework change can produce a different ID for the same conceptual mutation.

Next.js is a useful concrete example. In one version of its Server Action scheme, the action ID was effectively tied to a small set of build-time facts:

flowchart LR
  salt["Build salt"] --> hash["SHA-1"]
  file["File path"] --> hash
  export["Export name"] --> hash
  hash --> id["Action ID"]

In that world, this kind of refactor could keep the same action ID:

'use server'

export async function updateItem(id: string, value: string) {
  // ...
}

'use server'

export async function updateItem(
  id: string,
  value: string,
  options?: { optimistic?: boolean },
) {
  // ...
}

The file stayed the same. The export stayed the same. If the build salt stayed the same, the action ID stayed the same.

Newer implementations include more function-shape information. In the current Next source, the generated server reference ID still starts from a SHA-1 over the hash salt, file name, and export name, but it also appends a byte that encodes whether the reference is a cache reference plus an argument mask and rest-argument bit.

flowchart LR
  salt["Build salt"] --> hash["SHA-1 base"]
  file["File path"] --> hash
  export["Export name"] --> hash
  hash --> byte["Append metadata byte"]
  isCache["Server action vs cache reference"] --> byte
  args["Argument mask"] --> byte
  rest["Rest argument bit"] --> byte
  byte --> rotate["Rotate bytes"]
  rotate --> id["Action ID"]

That is a reasonable implementation change. The framework is trying to encode more about the server reference into the ID. But operationally, it changes the compatibility story. A parameter-shape change can now mean "new generated API endpoint," even if the source file and export name did not move.

The difference looks roughly like this:

flowchart TD
  subgraph old["Older action ID shape"]
    oldSalt["hash salt"] --> oldHash["hash"]
    oldFile["file path"] --> oldHash
    oldExport["export name"] --> oldHash
    oldHash --> oldId["same ID if those stay stable"]
  end

  subgraph new["Newer action ID shape"]
    newSalt["hash salt"] --> newHash["hash + metadata"]
    newFile["file path"] --> newHash
    newExport["export name"] --> newHash
    newCache["cache/action bit"] --> newHash
    newArgs["argument mask"] --> newHash
    newRest["rest-argument bit"] --> newHash
    newHash --> newId["new ID when shape changes"]
  end

This is the kind of detail that disappears inside an upgrade. The source diff looks like a compiler implementation detail. In production, it can change the public token old clients use to call the server.

Another way to say it: the public "API name" is synthesized from code shape.

flowchart LR
  salt["Build hash salt"] --> makeId["Generate server reference ID"]
  file["File name\napp/actions.ts"] --> makeId
  fn["Export / function name\nupdateItem"] --> makeId
  params["Parameter shape\nid, value, options?"] --> makeId
  makeId --> actionId["Action ID\naction_def456"]
  actionId --> client["Client bundle\nserver reference action_def456"]
  actionId --> server["Server manifest\naction_def456 -> updateItem"]
  client --> post["POST request\naction_def456"]
  post --> server

That is the surprising part. The thing behaving like an API route is not named by a URL you wrote. It is named by a compiler-generated ID derived from implementation details.

flowchart LR
  subgraph oldBuild["Build A"]
    oldFn["updateItem(id, value)"] --> oldId["action_abc123"]
  end

  subgraph newBuild["Build B"]
    newFn["updateItem(id, value, options?)"] --> newId["action_def456"]
  end

  oldId -. "not guaranteed to exist" .-> newId

Most of the time this is fine. A fresh page load gets the fresh JavaScript bundle, which contains fresh server reference IDs, and it talks to a matching server.

The trouble starts during deploys.

The Rolling Deploy Problem

Imagine a user has an old page open. The page was rendered by Build A, and the JavaScript bundle contains action_abc123.

While the tab is open, Build B rolls out. Build B only knows about action_def456.

Then the user clicks Save.

sequenceDiagram
  participant Browser as Browser with Build A JS
  participant CDN as CDN / asset cache
  participant Server as Server running Build B

  Browser->>Browser: User clicks Save
  Browser->>Server: POST request with action_abc123
  Server->>Server: Look up action_abc123 in Build B manifest
  Server-->>Browser: Action not found / request fails

From the user's point of view, nothing unusual happened. They opened a page and clicked a button.

From the server's point of view, a client called a server reference ID that no longer exists.

That kind of failure is easy to miss locally. Local development usually has one browser, one server, one version, and no real deploy overlap. Production has cached assets, long-lived tabs, rolling deploys, multiple instances, retries, and users who click buttons at inconvenient times.

When this fails during a deploy, the graph does not look like a slow burn. It looks like a cliff:

xychart-beta
  title "Generated server function failures during a version-skew deploy"
  x-axis ["18:00", "18:10", "18:20", "18:30", "18:40", "18:50", "19:00", "19:10"]
  y-axis "failed calls" 0 --> 120
  bar [5, 4, 6, 5, 7, 18, 105, 64]

The shape is the clue. A normal app bug usually follows traffic. Server reference skew shows up when the deploy crosses the old-client/new-server boundary.

Why This Is Different From A Route Handler

An explicit route can be versioned:

flowchart LR
  oldClient["Old client"] --> v1["POST /api/v1/update-item"]
  newClient["New client"] --> v2["POST /api/v2/update-item"]
  v1 --> shared["Shared service logic"]
  v2 --> shared

You can keep v1 alive during migration. You can log usage. You can reject bad input with a typed error. You can publish a compatibility window. You can put the path in a runbook.

With generated server functions, the API surface is intentionally hidden. That is the point. You get less boilerplate because you gave the framework control over the transport.

That tradeoff is fine for many UI-local mutations. It is much less comfortable for anything that needs a durable API boundary.

Use Them, But Draw The Line

I would use RSC server functions or framework actions for:

• forms that are tightly coupled to one page
• low-risk UI mutations
• mutations where a full page refresh fallback is acceptable
• actions that only need to work within one deployed version
• code where colocating mutation logic with the route is worth the coupling

I would be careful using them for:

• mutations called from many routes or packages
• workflows that need schema versioning
• endpoints used by mobile apps, extensions, workers, or other services
• high-volume mutations that need independent rate limits and observability
• flows that must survive rolling deploys without old-client failures
• anything that already looks like a product API

The line is not "server functions are bad." The line is "server functions are not a replacement for every API."

Deployment Safety

If you use generated server functions heavily, treat deploy compatibility as part of the design.

flowchart TD
  action["Does this mutation need to survive old clients?"] -->|No| serverFunction["Generated server function is probably fine"]
  action -->|Yes| boundary["Use an explicit route or compatibility layer"]
  boundary --> version["Version the request shape"]
  version --> observe["Log and monitor old usage"]
  observe --> remove["Remove after the compatibility window"]

Practical mitigations include:

• keep old servers around long enough for old pages to age out
• avoid serving old HTML with new-only server manifests
• use immutable asset URLs so a page and its JavaScript agree
• make generated server function errors visible in monitoring
• design important mutations so retrying through an explicit endpoint is possible
• avoid changing function signatures casually during framework upgrades

Next also has a separate concern around encrypted closed-over variables. In self-hosted multi-server deployments, the official data security guide calls out NEXT_SERVER_ACTIONS_ENCRYPTION_KEY for making encryption behavior consistent across instances. That is not the same thing as stable action IDs, but it comes from the same general place: Server Actions have build-time and deployment-time state. Treat that state deliberately.

The Mental Model

The easiest mistake is to think "use server" means "this is just a function call."

It is not. It is a framework-managed network call.

flowchart LR
  function["Looks like a function call"] --> rpc["Actually a generated RPC"]
  rpc --> api["Has API-like failure modes"]
  api --> deploy["Needs deploy compatibility"]
  api --> security["Needs auth and validation"]
  api --> observability["Needs logs and monitoring"]

That does not make server functions useless. It makes them a sharp tool.

Use them where the ergonomics are worth the coupling. Reach for explicit Route Handlers, API routes, or a BFF-style API when the boundary needs to be stable, observable, versioned, or shared outside one page.

The practical rule I use is:

If breaking the generated server reference would look like an API outage, give it a real API.

References

• React Server Components
• React Server Functions
• Next.js use server directive
• Next.js mutating data with Server Functions
• Next.js data security guide
• Next.js server action transform source
• Next.js action client wrapper source

pnpm dev
pnpm test
pnpm build

That is enough when there is one app, a few shared packages, and a small team. It stops being enough when the frontend becomes a graph: apps, SDK bundles, generated clients, translations, icons, tests, Storybook, browser extensions, edge workers, server bundles, static assets, and deployable images.

At that point, the question changes. It is no longer only:

How do we build the app?

It becomes something more annoying:

Which artifacts are affected by this change?

That is the point where Bazel starts to make sense.

flowchart LR
  change["Change"] --> pkg["Shared package"]
  pkg --> app["App bundle"]
  pkg --> test["Affected tests"]
  pkg --> meta["Translations / icons"]
  gen["Generated clients"] --> pkg
  config["Typed config"] --> app
  meta --> app
  app --> verify["Output checks"]
  verify --> deploy["Deployable artifact"]

Package Scripts Hide The Graph

A package script is easy to read:

{
  "scripts": {
    "build": "vite build",
    "test": "vitest run",
    "typecheck": "tsc --noEmit"
  }
}

The script is readable, but it hides almost everything the build actually cares about. It does not say which files are inputs, which packages are dependencies, which generated clients are required, which assets must be copied, or which downstream artifacts should be invalidated.

Task runners can improve this a lot. Turborepo and Nx both add structure, caching, and affected workflows. For many repositories, that is the right level of abstraction.

Bazel becomes interesting when the frontend graph needs more than package-level tasks. For example:

• generated REST, protobuf, or GraphQL TypeScript packages
• transitive translation extraction from colocated UI messages
• per-app icon sprite generation from reachable components
• route metadata aggregation across packages to detect collisions
• typed config files as build inputs
• test-only dependencies separated from runtime dependencies
• strict boundaries between app code, shared packages, examples, tests, and tools
• post-build verification over emitted bundles, including size budgets, environment replacement, sourcemap paths, and forbidden strings
• deployment targets that consume built artifacts instead of rediscovering files from the working directory
• selective side effects, such as uploading assets only when the artifact that feeds the upload changed

Those are not just commands. They are files, manifests, packages, checks, and uploads with dependencies.

Once you look at them that way, the system feels different. A translation catalog is not a random file that appears before build. It is an app-specific artifact derived from the dependency graph. A generated client is not just a prebuild step. It is a package with consumers. A CDN upload is not a shell command at the end of CI. It is a side effect attached to a verified bundle.

Selective Builds Need Honest Boundaries

Selective builds are only useful if you can trust them.

If a package can import undeclared dependencies, read undeclared files, or rely on global workspace state, the build graph becomes a guess. It may be fast, but it is not trustworthy.

Bazel pushes teams toward explicit boundaries:

• source files are declared
• assets are declared
• dependencies are declared
• generated artifacts have labels
• config files are inputs
• tests have their own dependency surface
• deployment artifacts consume known outputs

There is a cost. BUILD files, macros, generators, and rules become real work. But the payoff is simple: a change to one package does not have to become a global frontend event.

Where The Pain Shows Up

The pain usually does not appear on day one. It appears after the repository has a few generations of frontend architecture in it.

One team adds a shared component package. Another adds a browser extension. Another adds generated API clients. A platform team adds translation extraction. A design-system team adds icon sprites. A product team adds a second app. CI grows a pile of scripts that run "just to be safe."

Eventually, simple questions get expensive:

• Did this change affect the app shell?
• Do we need to rebuild every SDK?
• Which tests cover this shared package?
• Why did this bundle include that dependency?
• Which generated client version is being typechecked?
• Why did CI fail when local development worked?

Those questions get expensive because the graph already exists, but it lives in scripts, conventions, and memory. Bazel's value is making enough of that graph explicit that tools and humans can reason about it.

The Real Goal

I do not think the goal is to make every frontend engineer a Bazel expert.

The common path should be boring:

• create a package
• split a package
• add a dependency
• add a test
• add a generated client
• build one app
• run affected tests
• understand CI failures

Good Bazel rules hide most of the machinery while preserving the graph. The rest of this series is about that balance: package anatomy, generated BUILD files, typechecking contracts, aspects, generated clients, Vite bundles, tests, output verification, deployment targets, dependency hygiene, and how Bazel compares with Turborepo and Nx.

Bazel is not the easiest frontend build tool to adopt. It asks the repository to be precise.

In a large monorepo, that precision is the feature.

In a large monorepo, the same directory may contain runtime source, tests, stories, config files, fixtures, JSON, CSS, generated files, and static assets. Treating all of that as one project makes dependency boundaries fuzzy.

Bazel works better when a package is modeled as a small set of artifacts.

flowchart TD
  src["Runtime source"] --> lib["Library target"]
  assets["Runtime assets"] --> lib
  tests["Tests"] --> test["Test target"]
  lib --> test
  stories["Stories"] --> storybook["Storybook target"]
  lib --> storybook
  config["Typed config"] --> app["Leaf app / SDK"]
  lib --> app
  lib --> meta["Extracted metadata"]

Internal Packages Vs Leaf Packages

Internal packages are the pieces other code builds on. They expose components, hooks, clients, utilities, styles, or framework helpers.

Leaf packages produce something runnable or deployable: an app, SDK bundle, browser extension entry, worker script, example, or server artifact.

Those two shapes should not be modeled the same way. A shared library should not carry app deployment concerns. An app bundle should not pretend it is just another library.

Why Not A New package.json Every Time?

In JavaScript workspaces, the natural instinct is to make every boundary a new package with its own package.json.

That can work, but it gets clunky at monorepo scale. Package names are global within the workspace, so every small boundary needs a unique, stable, bikeshed-prone name. Renaming a package becomes more expensive than moving a directory. Publishing-oriented metadata starts leaking into internal architecture. A tiny refactor can turn into package naming, exports, dependency metadata, and toolchain ceremony.

Bazel gives another option: a package boundary can be a BUILD package, not necessarily an npm package. The directory and target label can carry the internal boundary while the root package manager still owns installed third-party versions.

This is especially useful for package splitting. Moving code from features/search/results to features/search/result-card should not require inventing a public package name if the boundary is only internal to the repository.

Split The Surfaces

A frontend package usually has several surfaces:

• runtime source: code that ships or is imported by other packages
• tests: test files, fixtures, test-only libraries
• stories/examples: documentation and demo surfaces
• config: Vite, Vitest, Storybook, Tailwind, codegen, or build tooling
• assets: JSON, CSS, SVG, images, translations, static files
• generated outputs: clients, manifests, locale metadata, sprites

The important rule: dependencies should attach to the surface that uses them.

A test runner belongs to the test target. A Vite plugin belongs to the config target. A browser-only library belongs to browser runtime source. A generated client belongs to the package that imports it.

This keeps production dependencies cleaner and makes selective builds less hand-wavy.

Companion Targets

One package may expand into several predictable targets:

• library
• typecheck
• runtime source sidecar
• unit tests
• Storybook build
• visual tests
• extracted translations
• extracted icon usage
• internal dependency metadata

Developers should not handwrite all of this every time. A macro or generator can create the standard targets from conventions. The useful part is the predictable shape: downstream rules can rely on stable names and known behavior.

Why This Shape Helps

This structure pays off when code moves, which is the part people tend to underestimate.

If a test file changes, the test target should be invalidated. The production bundle usually should not be. If a Storybook story changes, the Storybook target should rebuild. Runtime consumers should not inherit Storybook dependencies. If a generated locale file changes, app bundles that consume it should rebuild, but unrelated packages should stay out of the blast radius.

That is the practical reason to split package surfaces. It is not just tidier modeling. It gives the build system enough information to skip work without guessing.

It also gives better errors. "The config target is missing a dependency" is much more useful than "the package failed." "This test imports an undeclared fixture" is better than a mysterious CI-only file-not-found error.

Assets Are Inputs

Frontend packages are rarely pure TypeScript.

If source imports JSON, the JSON is an input. If a component imports CSS, the CSS is an input. If tests need fixtures, fixtures are inputs. If an app embeds translations or sprites, those generated files are inputs.

Sandboxed builds are blunt here, in a useful way. If an action reads a file that was not declared, the build should fail. That failure means the graph is missing an edge.

Visibility Is Architecture

Package visibility can feel bureaucratic until it catches the first bad dependency. Then it starts to look like architecture encoded in the build graph.

A design-system package may expose supported components and hide internals. An app feature may be visible only within that app. A generated client may be broadly visible. A test helper may be visible only to tests.

Without visibility, every package can depend on every other package. That is how internal implementation details become public APIs by accident.

There is also a useful convention from Go: directories named internal can only be imported by code within the parent tree. Frontend monorepos can copy that idea even if the language does not enforce it natively.

For example, features/search/internal/ranking can be treated as visible only to features/search/.... A lint rule or import-boundary check can enforce the convention. Bazel visibility can enforce it at the build graph layer. Together, they let packages have private implementation subtrees without turning every helper into a globally importable module.

The Package Checklist

A good package answers these questions clearly:

• What code ships?
• What code tests it?
• What config builds it?
• What assets does it need?
• What generated artifacts does it consume?
• What metadata does it expose?
• Who may depend on it?

Bazel does not answer those questions automatically. The build rules have to encode them. Once they do, a package boundary becomes more than a folder convention. It becomes a useful interface to the frontend graph.

Where Codegen Fits

The best BUILD file is often the one most engineers do not have to edit.

Large frontend repositories change constantly: files move, packages split, tests appear, generated clients change, and imports drift. If every one of those changes requires careful BUILD-file surgery, the build system becomes a tax on refactoring.

Generation is how you keep Bazel precise without making it tedious.

flowchart LR
  files["Source files"] --> scan["Import / file scanner"]
  imports["Imports"] --> scan
  scan --> build["Generated BUILD metadata"]
  build --> lib["Library target"]
  build --> config["Config target"]
  build --> test["Test target"]
  human["Human decisions"] --> build

Codegen is good at mechanical facts: source files, test files, story files, config files, static assets, import paths, npm packages, internal deps, and generated-package deps.

Humans should still own architectural choices: visibility, package boundaries, deployability, unusual runtime assets, intentional ambient deps, and special bundling behavior.

The generator emits the common shape. The rules own the behavior.

One promising tool in this space is hermeticbuild/gazelle_ts, a Gazelle TypeScript language extension that generates abstract TypeScript rule kinds and lets consumers map those kinds to project-specific macros. The important idea is the abstraction boundary: the generator can own source/test/config/import discovery while the repository still owns the concrete rule behavior.

Stable Target Names Are APIs

Generated targets should be predictable. For a package named ui, a repository might consistently create :ui, :ui_typecheck, :ui_srcs, :vitest_test, :extracted_translations, and :extracted_sprite_icons.

The names are less important than the stability. Other rules can compose those targets without knowing the package internals.

Stable target names are build-system APIs. Treat them that way.

Package Splitting Should Be Boring

Package splitting is a great test of build ergonomics.

The desired workflow is: move files, update imports, run the generator, and run affected tests.

If splitting requires hand-editing several build targets, copy-pasting config, and guessing dependency lists, engineers will avoid it. The repository will accumulate oversized packages because the better shape is too expensive.

Bazel provides the precise graph. Codegen makes that graph affordable to maintain.

Absolute Imports Help Refactors

Generated dependency metadata works especially well with stable absolute imports.

Relative imports are fine inside a tiny package, but they become noisy when files move:

import { formatDate } from "../../../common/date";

Move the file one directory deeper and the import changes even though the dependency did not.

Absolute subpath imports avoid that churn:

import { formatDate } from "#features/common/date";

The import describes the logical dependency rather than the file's current relative position. That is more ergonomic for refactors, and it gives tools like Gazelle a stable string to resolve into a Bazel label.

tsc --noEmit

Large frontend monorepos usually need more than one TypeScript contract. Runtime source, tests, config files, generated clients, browser code, server code, examples, and tools all have different assumptions.

One giant typecheck usually becomes too loose, too slow, or both.

flowchart TD
  src["Runtime source"] --> runtime["Runtime typecheck"]
  tests["Test files"] --> testcheck["Test typecheck"]
  src --> testcheck
  config["Tooling config"] --> configcheck["Config typecheck"]
  generated["Generated clients"] --> runtime
  deps["Declared deps"] --> runtime
  visibility["Visibility rules"] -.enforce.-> runtime

Typecheck Is Not Transpile

Typechecking asks: is this code valid?

Transpilation asks: what JavaScript and declarations should be emitted?

Bundling asks: what runtime artifact should be loaded?

Those are different jobs. A shared library may emit declarations. A Vite app root may typecheck but not emit JavaScript because the bundler owns output. A config file may typecheck but never become runtime code.

Bazel lets those jobs be separate targets.

This matters for performance too. Typechecking can be significantly slower than transpilation because it needs semantic analysis across files and declarations. Modern tooling reflects that split: Oxc focuses on a high-performance JavaScript/TypeScript toolchain, including fast parsing and transformation, while TypeScript's native Go effort, exposed through the tsgo entry point in the TypeScript 7 beta, exists specifically because TypeScript performance is important enough to justify a native implementation path.

The build graph should take advantage of that distinction. Fast transpilation or bundling can happen where JavaScript output is needed. Typechecking can run as its own target, cached independently, and scoped to the surface that actually needs that contract.

Split The Contracts

Runtime source should include runtime dependencies and exclude tests, stories, examples, and tools. If runtime code imports a test helper or Node-only package, the runtime target should fail.

Tests need their own contract. They often import assertion libraries, DOM simulators, mock servers, fixtures, and snapshot utilities. Those dependencies should not leak into runtime libraries.

Config files are code too. vite.config.ts, vitest.config.ts, Storybook config, Tailwind config, and codegen config can all import packages and change output artifacts. A bundler plugin belongs to the config target, not every runtime package the app imports.

Generated clients should be declared typecheck inputs, not ambient files that happen to exist locally. Browser code should typecheck against browser APIs. Server code should typecheck against server APIs. Worker code may need a third contract.

The Dependency Side

A root package.json says what is installed. A Bazel target's deps say what that target uses.

Those are different. A workspace may install hundreds of packages. A component should depend on a small, explicit subset.

Runtime deps belong to runtime source. Test deps belong to tests. Config deps belong to config targets. Generated deps belong to packages that import generated artifacts.

Dependency placement is architecture.

Ambient deps should be rare and reviewed. Visibility rules should catch accidental architecture. Shared packages should not import app packages. Browser-only packages should not import server-only modules. Generated packages should not depend on handwritten app code.

Circular dependencies should be treated as build graph bugs, not harmless TypeScript trivia. They make initialization order fragile, make tests harder to isolate, and make package splitting much harder. Bazel's explicit dependency graph gives teams a natural place to detect and reject cycles between packages.

This is another place where the frontend can borrow from stricter ecosystems. If a package graph has a cycle, the boundary is usually wrong: either a shared lower-level package needs to be extracted, or one package is reaching through another package's public API in the wrong direction.

A Concrete Failure Mode

Imagine one global typecheck that includes runtime source, tests, config files, and Node scripts.

To make that pass, the tsconfig often grows broad: DOM types, Node types, test globals, bundler globals, generated paths, and tool-specific settings all live together. That can hide real bugs. Browser code may accidentally use a Node API. Server code may accidentally assume the DOM. Runtime source may import a test helper. Config-only dependencies may appear available everywhere.

Separate typecheck targets and dependency surfaces make those mistakes visible. The stricter model is often less painful because failures are more specific.

Make Failures Fixable

Dependency checks should not feel like riddles.

A good failure says which import caused the problem, which target owns the importing file, and whether the missing dependency belongs to runtime, test, config, or generated deps. A visibility failure should explain which boundary was crossed.

Strictness works when the correct fix is obvious. If people have to guess, they will add broad dependencies or look for workarounds.

Lint Rules Need Typecheck Too

Lint rules are code, and serious frontend lint rules often depend on type information.

An import-boundary rule may need to understand generated import aliases. An internal-directory rule may need to resolve absolute subpath imports. A rule banning browser APIs in server code may need to know which files belong to which surface. A rule that detects unsafe framework usage may need TypeScript's semantic model rather than just syntax.

That means lint tooling has its own contract. The lint rule implementation should typecheck. Its test fixtures should typecheck where relevant. Its target should declare the same generated package mappings and type roots it needs to reason about source accurately.

Otherwise, lint becomes a parallel, weaker build system that guesses at the graph.

Translations, icon sprites, route metadata, internal dependency reports, REST clients, protobuf declarations, and GraphQL operation packages all sit in the middle. They are source-like enough for apps to consume, but generated or aggregated enough that package scripts handle them poorly.

This is where Bazel's graph model is useful in a very practical way.

flowchart LR
  app["App target"] --> pkg["Package graph"]
  pkg --> aspect["Aspect collection"]
  aspect --> meta["Translations / icons / routes / deps"]
  schema["Schemas / operations"] --> gen["Generated TS packages"]
  gen --> pkg
  meta --> app

Aspects For Transitive Metadata

A package can typecheck itself. A test can run its own files. But questions like these are different:

Which translations, icons, routes, and internal packages are reachable from this app?

Those are graph questions. Bazel aspects are one way to answer them without scanning the entire repository or maintaining brittle manifests by hand.

A normal rule says: given these inputs, produce these outputs. An aspect says: while walking this dependency graph, collect something from every target you visit.

Translations And Icons

Translations are a natural fit. Messages often live in shared components, feature packages, and app code. An app catalog should include strings reachable from the app, not every string in the monorepo.

FormatJS is a good concrete example of this workflow. Its application workflow guide describes extraction as the step that aggregates defaultMessages and descriptions into JSON for translation, followed by editing or uploading/downloading translations through a translation service.

That model is much easier to live with when messages are colocated with the components that own them. A button owns its label. An empty state owns its copy. A feature owns its messages. Engineers do not have to update a distant central translation file every time they move UI code.

Bazel then gives the missing monorepo piece: extraction can follow the dependency graph. Shared packages can colocate messages locally, while an app target aggregates only the messages reachable from that app. rules_formatjs is a useful reference point for modeling FormatJS extraction in Bazel. The result is the best of both worlds: colocated source ergonomics and app-level translation artifacts.

Icon sprites work the same way. A design system may ship thousands of icons. Most apps use a small subset. A production build can statically extract icon names from source, aggregate usage through dependencies, and generate a filtered sprite.

The app does not need to know which shared component used which icon. The graph already has that information.

Route Collision Checks

Routes are another useful example because collisions are often not local.

One package may contribute account routes. Another may contribute settings routes. A third may contribute an embedded app or route group mounted under a shared prefix. Each package can look correct in isolation, while the final app accidentally registers two handlers for the same path.

An aspect can collect route metadata across the app graph and feed a collision check:

flowchart LR
  account["account package\n/settings"] --> app["app target"]
  billing["billing package\n/settings/billing"] --> app
  embed["embedded app\n/settings"] --> app
  app --> aspect["route metadata aspect"]
  aspect --> manifest["aggregated route manifest"]
  manifest --> check["collision check"]

The check can validate more than exact duplicates. It can catch conflicting dynamic patterns like /teams/:id and /teams/new, overlapping catch-all routes, incompatible layouts mounted at the same prefix, or two apps trying to own the same browser extension route.

The important part is ownership. Individual packages own local route declarations. The app owns the aggregate route table. Bazel provides the graph walk that connects the two without a manually maintained central manifest.

Generated Packages

Generated TypeScript should be produced by labeled targets, and consumers should depend on those targets.

REST clients may come from OpenAPI, TypeSpec, framework route schemas, or service contracts. Protobuf-generated frontend types may include cross-package references. GraphQL operation packages may emit typed documents, result types, persisted-query hashes, and upload manifests.

These are not ghost dependencies. Schemas are inputs. Generated TypeScript is output. Consumers depend on generated package targets.

Import Conventions

Generated imports should be visually distinct and stable:

import { client } from "#generated/rest/users/client.js";
import type { Message } from "#generated/protobuf/messages/Message.js";
import { SearchQuery } from "#generated/graphql/search.graphql.js";

The exact namespace does not matter. What matters is that generated imports map cleanly to generated build targets.

Direct Deps Still Matter

A generated import namespace does not remove the need for dependency declarations.

If a package imports a generated REST client, it should depend on that REST client target. If it imports generated protobuf declarations, it should depend on the protobuf target. If it imports generated GraphQL operations, it should depend on the operation package.

This matters for build correctness, but it also matters for review. A new generated client dependency often means the package now talks to a new service or relies on a new contract. That is architectural information.

The broader pattern is the same for aspects and generated packages: stop relying on side effects that happen to run first, and give the artifacts names in the graph.

Vite is good at bundling frontend code. Bazel is good at modeling repository-scale inputs and outputs. Large frontend monorepos need both.

The split I like is:

Bazel decides what the app needs. Vite turns it into a bundle.

flowchart LR
  src["App source target"] --> vite["Vite bundle"]
  config["Typed Vite config"] --> vite
  gen["Generated clients"] --> src
  meta["Translations / sprite"] --> vite
  assets["Runtime assets"] --> vite
  vite --> tests["Tests / Storybook"]
  vite --> verify["Output checks"]

Apps Are Leaf Nodes

Internal packages are composable. Apps and SDKs are leaf nodes.

A leaf target produces something runnable or deployable: a web app bundle, static SDK directory, browser-extension entry, iframe embed, worker script, or server asset directory.

The app target should gather exactly what it needs: source, config, generated clients, assets, translations, sprites, and environment inputs.

Source And Config Are Separate

Runtime source depends on React, shared packages, state libraries, generated clients, and assets. Config depends on Vite, plugins, CSS tooling, and build helpers.

Those dependency sets should not be mixed.

A Vite plugin is not a runtime dependency just because it builds runtime code.

App Roots May Typecheck Without Emitting

Shared TypeScript libraries often emit declarations and JavaScript.

Vite app roots are different. The bundler owns the final JavaScript. The app source target may only need to typecheck, expose runtime files, and provide metadata for translations or sprites.

This avoids output collisions and keeps responsibilities clear.

Tests Are Consumers

Tests are not runtime source. They are consumers of runtime source.

A test target should depend on the package under test, plus test files and test-only dependencies. That gives a clean split: runtime typecheck can pass or fail independently, test typecheck can include test-only libraries, and production bundles do not inherit test dependencies.

Storybook and visual tests are also consumers. They may need browsers, fonts, screenshots, fixtures, themes, and Storybook packages. Those dependencies are heavy. They should be explicit, and they should not leak into runtime package deps.

Assets, Fixtures, And Environment Inputs

Vite actions and test actions need more than .ts files: CSS, JSON, SVG, static files, translation files, generated sprites, fixtures, snapshots, and environment-shaped values.

If an action reads a file, that file should be in the graph. If a client bundle needs a public environment value, that value should be modeled as a build input. If a server runtime needs an env file, that should be separate from client-side replacement.

A reliable app or test is not just code. It is code plus declared data.

Output Shape Is Part Of The API

Different Vite targets need different output shapes.

An app may emit an entire dist directory. A browser-extension background script may need a specific background.js file. An embedded SDK may need stable filenames. A server app may need static assets copied into another package.

Those output shapes are not incidental. Downstream verification, uploads, images, workers, and tests depend on them.

That is how "run Vite" becomes a reliable artifact-producing target instead of a script that happens to work on one machine.

The bundler answered one question:

Can these inputs become output files?

The build still needs another question:

Are those output files acceptable?

flowchart LR
  checks["Output checks"] --> build["Verified bundle"]
  build --> server["Server binary"]
  server --> image["OCI image"]
  build --> cdn["CDN upload"]
  build --> ext["Extension package"]
  build --> worker["Edge worker deploy"]

Built Artifacts Are APIs

Bundles have consumers: browsers, servers, CDNs, deployment scripts, monitoring tools, extension packages, and image builders.

If output shape changes accidentally, those consumers can break even when the build succeeded.

Useful checks include file size, environment replacement, asset references, sourcemap paths, CDN paths, chunk policy, and forbidden patterns.

These checks should consume the built artifact, not the source tree.

Concrete Built Asset Checks

A large SPA usually has a bunch of assumptions that nobody wants to check by hand. Put the cheap ones against the emitted dist directory.

Useful checks include:

• forbidden strings in HTML: restricted feature names, internal-only route names, or experiment scaffolding should not appear in public HTML.
• sensitive constants in JS: server-only identifiers, private enum values, or backend-only flags should not leak into public bundles.
• expected chunk placement: code intentionally split behind restricted or dynamic boundaries should emit under a known directory or filename pattern.
• CSS loading behavior: critical CSS should be present as a blocking stylesheet link if the app depends on it to avoid flash-of-unstyled-content.
• runtime CSS invariants: generated CSS can be scanned for required or forbidden properties when browser behavior depends on them.
• bundle budgets by pattern: vendor chunks, app-shell chunks, i18n chunks, route chunks, and CSS can each have separate size limits.

That often looks like a few focused tests wired to the bundle target:

output_scan_test(
    name = "env_var_no_leftover_test",
    rules = [":no_leftover_env_vars"],
    targets = [":app_bundle"],
)

output_scan_test(
    name = "critical_css_loading_test",
    rules = [":critical_css_is_blocking"],
    targets = [":app_bundle"],
)

file_size_test(
    name = "bundle_size_test",
    folder = ":app_bundle",
    pattern_size_map = {
        "**/vendors-*.js": 425,
        "**/app-shell-*.js": 350,
        "**/i18n-*.js": 300,
        "**/*.css": 565,
    },
)

The exact rule names do not matter. The important choice is that the checks read the built files. They catch the things source analysis cannot: a placeholder that survived replacement, a server-only string that became reachable, a chunk that moved into the wrong public bucket, or a CSS policy that disappeared during extraction.

Source Checks Are Not Enough

Many output bugs do not exist in source form.

The source may contain import.meta.env.PUBLIC_URL, but the emitted bundle contains the actual string. The source may import a dynamic chunk, but the emitted manifest decides the filename. The source may configure sourcemaps, but the emitted comment determines what production debuggers see.

That is why output checks should inspect output. They validate the artifact the user, CDN, server, or monitoring system will actually see.

Generated Assets Need Checks Too

Generated runtime assets deserve the same treatment as bundles.

Translation catalogs can be structurally invalid. Locale files can miss keys. Icon sprites can reference symbols that do not exist in the master sprite. Route manifests can point to stale outputs. GraphQL persisted-query manifests can miss operations.

These checks are usually cheap compared with finding the problem after deployment. If a generated asset affects runtime behavior, it should have a verification target.

Deployment Is A Consumer

Deployment should not rediscover files from the working directory.

The cleaner path is:

1. Build targets produce artifacts.
2. Verification targets validate artifacts.
3. Deployment targets consume artifacts.

Server bundles, frontend images, CDN uploads, browser extensions, and edge workers are all consumers of the artifact graph.

Upload Checks Are Artifact Checks Too

Deployment checks should verify that upload targets and emitted paths agree.

For example:

• public asset uploads exclude source maps so .map files do not get served as ordinary static assets.
• source maps upload through a separate target with the same public URL prefix the browser will use for minified files.
• restricted or private debug artifacts use a separate destination from normal public assets.
• CDN base paths appear in the emitted bundle so runtime asset resolution matches the deployment environment.
• source map URLs do not contain doubled path segments such as /assets/assets/.
• environment placeholders are fully replaced and no placeholder-like values remain in emitted JS.
• success markers wait for every required side effect instead of marking a deployment ready after only one upload step.
• signed packages are conditional on signing material so local and CI builds can still produce unsigned artifacts without pretending to publish them.

In Bazel, these become ordinary graph edges:

upload_assets(
    name = "upload_public_assets",
    src = ":app_bundle",
    exclude = ["*.map"],
)

upload_sourcemaps(
    name = "upload_sourcemaps",
    src = ":app_bundle",
    minified_path_prefix = CDN_ASSET_PREFIX,
)

output_scan_test(
    name = "cdn_base_path_exists_test",
    rules = [":cdn_base_path_exists"],
    targets = [":app_bundle"],
)

This is the useful shift: the deployment script is no longer a pile of shell globbing. It is another consumer of the same verified artifact that tests and images consume.

Selective Side Effects

Build systems usually focus on selective computation: only rebuild what changed. Frontend deploys also need selective side effects.

Uploading assets, publishing sourcemaps, deploying preview workers, registering GraphQL persisted queries, or syncing extension bundles should not happen just because a broad CI script ran. They should happen because the artifact they consume actually changed.

That is the same idea behind changed-target CI pipelines: compute the affected build graph first, then run the expensive or external side effects only for the affected artifacts.

The practical benefits are not glamorous, but they matter:

• fewer unnecessary uploads
• fewer flaky network operations
• less CI time
• lower risk of overwriting unchanged release artifacts
• clearer audit trails for what changed

The build graph gives the deployment layer a better trigger than "some frontend file changed." It can say "this exact bundle changed, so re-upload this exact artifact."

Stamping And Preview Deploys

Deployment artifacts often need release metadata: commit SHA, version, environment, service name, or release ID. That does not mean every frontend build should be stamped. Stamping too much can hurt cacheability.

A practical split is: build cacheable artifacts first, verify them, then stamp or label only the targets that publish or package them.

Preview environments deserve the same treatment. They often use the same verified bundle as production with different hostnames, asset prefixes, routes, worker names, credentials, and cleanup policies.

Those differences should be modeled, not hidden in a script branch. The best preview systems are boring because they are just another consumer of the artifact graph.

The frontend graph is not done at dist. It is done when the verified artifact is ready to run.

The useful question is not:

Which monorepo tool is best?

It is:

Which model matches the problems this repository actually has?

Bazel, Turborepo, and Nx are not three skins over the same idea. They operate at different levels of granularity.

flowchart LR
  turbo["Turborepo\npackage tasks"] --> simple["Fast adoption"]
  nx["Nx\nproject graph"] --> structure["Workspace structure"]
  bazel["Bazel\naction/artifact graph"] --> precision["Precise artifacts"]

Turborepo: Package Task Orchestration

Turborepo is strongest when package scripts already describe the work well.

It gives teams task orchestration, caching, and an easy adoption path. If the main problem is "do not rerun unchanged build, test, and typecheck scripts," Turborepo is often the right answer.

That is a real need. Many frontend monorepos do not need custom build rules. They need to run familiar package scripts in the right order and avoid repeating work.

The tradeoff is granularity. Turborepo is fundamentally task-centered. You can add scripts for generated clients, output checks, and deployment packaging, but the model remains package-task orchestration. If a production artifact needs several typed intermediate artifacts and transitive metadata collections, those usually become scripts around the core model.

Nx: Project Graph And Workspace Tooling

Nx adds a richer project graph, affected workflows, generators, framework integrations, and module boundary rules.

It is a strong fit when a repository wants more structure than package scripts but still wants tooling close to common frontend workflows. Nx generators can make project creation consistent. Affected commands can make CI much smarter. Module boundary rules can encode architecture directly in workspace tooling.

The tradeoff is that custom artifact pipelines may need plugins or escape hatches. If the repository's needs fit the Nx project model, it is productive. If the build becomes highly custom, the model may stretch.

For many frontend-heavy teams, Nx lands in a useful middle: more structure than package scripts, less custom infrastructure than Bazel.

Bazel: Action And Artifact Graph

Bazel models targets, actions, inputs, outputs, providers, aspects, execution platforms, and caches.

That is more machinery. The reason to tolerate it is precision:

• generated packages as artifacts
• transitive metadata with aspects
• strict dependency declarations
• typed config targets
• output verification
• server/image/deploy targets
• cross-language contracts

The cost is real: steeper learning curve, more rule infrastructure, more BUILD metadata, and more need for build-platform ownership.

Bazel is usually not the cheapest initial choice. It starts to pay for itself when the repository already has artifact complexity that package tasks and project graphs struggle to express cleanly.

The Real Tradeoff

This comparison is mostly about granularity.

Turborepo asks: which package tasks should run?

Nx asks: which projects and tasks are affected?

Bazel asks: which targets and actions produce which artifacts from which inputs?

More granularity gives more precision, but it also exposes more complexity. If the repository does not need that precision, Bazel can feel like overhead. If the repository does need it, package-level task orchestration can become a pile of scripts.

The right answer depends on where the complexity already lives.

The Frontend-Specific Lens

For frontend monorepos, the dividing line is often generated and secondary artifacts.

If the repo mostly runs framework builds and tests, task orchestration may be enough. If it needs generated API packages, transitive translation extraction, icon sprites, output scans, server image assembly, and worker deploy targets, an artifact graph starts to look less optional.

That does not make Bazel universally better. It means Bazel is strongest when the build needs to understand things that are not naturally package scripts.

A Practical Rule

Use Turborepo when package-level tasks are the right abstraction.

Use Nx when project graph tooling and generators solve the workspace problem.

Use Bazel when the repository needs explicit artifact modeling and custom graph behavior.

These tools are not on one ladder. They solve different scaling problems.

The mistake is choosing Bazel because it is powerful. Choose it when the precision is worth the ownership cost.

It has users, APIs, documentation, errors, adoption curves, metrics, and maintenance costs. If it is painful, frontend engineers will route around it.

flowchart TD
  rules["Rule APIs"] --> workflows["Daily workflows"]
  docs["Docs"] --> workflows
  codegen["Generators"] --> workflows
  errors["Good errors"] --> workflows
  metrics["Metrics"] --> improve["Platform improvements"]
  workflows --> confidence["Confidence to change"]
  improve --> rules

Build Rules Are APIs

A package macro is an API. A test rule is an API. An app rule is an API. A deploy rule is an API.

Good rule APIs have stable names, clear inputs, useful defaults, understandable outputs, documented escape hatches, and actionable failures.

The common path should be boring: add a component, add a test, split a package, update a generated client, run one app, debug CI. Those workflows should not require deep knowledge of providers, runfiles, execution platforms, or action graphs.

Documentation, Errors, And Metrics

Strict systems need good docs and good errors.

A bad error says a target failed. A good error says which import is missing, which dependency list should change, and whether the problem is runtime, test, config, or generated code.

Useful metrics include CI duration, affected target count, cache hit rate, local test latency, dependency violations, bundle size trends, flaky test rate, and package split frequency.

These metrics are useful because they show whether the build system is helping the codebase change.

Design For Deletion

Build platforms accumulate compatibility layers: old macros, aliases, migration flags, temporary generated files, special-case targets, and deprecated wrappers.

Every temporary path should have a way out. Can you find all remaining users? Is there a migration target? What condition allows deletion?

Bazel queries and dependency metadata can make cleanup practical. Without that discipline, yesterday's migration helper becomes tomorrow's permanent complexity.

A good build system is not only easy to add to. It is possible to simplify.

Avoid The Platform Bottleneck

A build platform team should not have to approve every new package, test, app, or generated client.

The way out is self-service: generators, templates, documented patterns, and stable rule APIs. The platform team should spend most of its time improving the system, not translating every frontend change into build metadata by hand.

When common workflows are self-service, the build platform scales with the repository instead of becoming its narrowest point.

Tighten Gradually

Do not turn every strict check on at once.

Measure first. Warn before failing. Start with new packages. Add autofixes. Ratchet over time.

The point is a repository that is easier to change, not a purity contest.

The Final Point

This series has one recurring idea: large frontend monorepos are graph problems.

That graph includes source, tests, configs, generated clients, translations, sprites, bundles, output checks, servers, images, workers, and deployments.

Bazel is useful when teams need to model that graph precisely. But precision is not enough. The platform also needs ergonomics, codegen, documentation, good errors, metrics, and incremental adoption.

The thing you want is confidence: a change rebuilds the right things, tests the right things, ships the right artifacts, and leaves the rest alone.