Many BFFs end up becoming a simple "Node API forwarding layer." An incoming page request hits Node, which calls several APIs, stitches the JSON together, and passes it to the frontend. This model works, but as the page system grows more complex, several problems quickly emerge: site-wide rules like SSO, country paths, and multi-site configurations are scattered everywhere; every page duplicates the aggregation of first-screen data; rendering templates are tightly coupled with API field structures, so changing a rendering approach affects a mass of business code.

I prefer to think of a page-oriented BFF as a server-side pipeline. A request first passes through the static and module layer, then enters site-wide middleware, hits a specific page for data aggregation, and finally, the rendering template decides how to output HTML, streams, or a CSR fallback.

This article addresses only one question: why cross-cutting concerns, aggregation, and rendering should be separated, and what each should be responsible for after separation.

Don't Mix the Three Things

Let's clarify three terms first:

Cross-cutting concerns: Site-wide rules that should be handled before entering a specific page, such as domain, login state, country path, trailing slash, remote rendering toggle, etc.
Aggregation: After knowing which page it is, preparing the data needed for the first screen or the initial streaming segment for that page.
Rendering: After the data is ready, deciding how to output HTML, how to hand over state to the browser, and which fallback path to take on failure.

Once they are mixed together, future changes become difficult.

If site-wide rules are written into pages, then any change to SSO or multi-site rules requires modifications across many pages. If aggregation is scattered across components, the first screen and the browser side may each have their own set of requests, leading to inconsistencies in cookies, authentication, and gateway prefixes. If rendering is tightly bound to business APIs, switching to SSR, streaming, or degradation strategies will also affect API encapsulation.

The purpose of layering is not to make the BFF diagram more complicated, but to reduce cross‑contamination among three types of changes: changes to site-wide rules should not affect page aggregation; changes to API fields should not affect templates; changes to rendering strategy should not affect gateway encapsulation.

How a Request Flows Through the BFF

There's a potential misunderstanding here: the placement of Vite.

In development mode, Vite's middlewareMode does handle module graphs, HMR, /@vite endpoints, etc., within the request chain. In production, Vite does not typically handle user requests; instead, Nginx/CDN and build artifacts serve static assets. The diagram groups them together only to express that "the request first encounters the static and module layer," not that a Vite process handles traffic in production.

After that, the request passes through site-wide middleware before entering the router. Only after routing hits a specific page does the page handle become heavy: loading page configuration, fetching downstream data, assembling the view model, and then handing it over to the rendering template.

This order is important. The earlier the layer, the more it should handle site-wide consistent rules; the later the layer, the more it should handle page-specific business data and rendering details.

Cross‑cutting Concerns: Rules First, Then the Page

The principle of cross‑cutting logic is simple: Any rule that can be determined before knowing which page the request belongs to should be placed before page routing whenever possible.

For example, which clientId corresponds to the current Host, how to set the cookie domain, whether the request requires SSO, whether there's a country path in the URL, whether trailing slashes should be normalized, whether to attempt remote full‑page rendering and fall back on failure. None of these are unique to any single page; writing them into every page only increases maintenance cost.

The benefit of moving cross‑cutting concerns forward is straightforward: rules are centrally configured, applied consistently across the site, and business pages don't have to re‑implement them. The cost is also present: when troubleshooting, you can't just look at page code; you also need to know which middleware modified the request before it entered the page.

The most common pitfall here is the path. The path seen by page routing may not be the original path in the browser's address bar—it might have been processed by country segments, trailing slashes, or proxy rules.

Aggregation: What Data Does This Page Need?

After routing hits, the BFF truly enters the context of "this page." The aggregation layer needs to answer: what data does this page need for the first screen or the initial streaming segment, where does it come from, and how to handle failures.

Its difference from a regular JSON gateway is that the aggregation result often goes beyond just returning a REST JSON to the browser—it goes into HTML: part of it is used for SSR, and part is serialized into a global state for the browser to continue hydrating.

Anticorruption Layer: Don't Let Components Pierce Backend Fields

Simply concatenating the results from multiple interfaces has limited value. More critical is transforming JSON that is deeply nested, historically constrained in naming, or inconsistent with the UI model into a structure that components can directly bind to.

For example, the backend might return:

const raw = {
  goods_info: {
    goods_name: 'Argus 4 Pro',
    main_image_url: 'https://example.com/argus.png',
  },
  price_info: {
    sale_price: 129.99,
    currency_code: 'USD',
  },
  stock_state: {
    is_in_stock: true,
  },
};

What the page actually needs might be:

const viewModel = {
  title: 'Argus 4 Pro',
  image: 'https://example.com/argus.png',
  price: '$129.99',
  available: true,
};

If components frequently access goods_info.goods_name, price_info.sale_price, etc., the backend field structure leaks into the UI layer. When the API changes, components shake accordingly. The role of a Data Transformer is to block this at the BFF or page boundary: templates and components face the site's own View Model, not a literal mapping of backend fields.

The division of labor can be:

Fetching, retrying, parallelism: handled by API encapsulation and HTTP client.
How fields are transformed into UI models: handled by page or shared transformers.
Which data is allowed into the first‑screen state: constrained jointly by the page and template.

Request direction (to gateway):

Response direction (after returning to BFF):

A common practice is: pass the transformed View Model to the template, which then writes it into the global scope using a safe serialization method, e.g., the project–agreed window.__SSR_RENDER_DATA__. A good rule of thumb: anticorrupt first, then handoff.

Fetch order, dependency relationships, and failure strategies are decided by the page or layout; connection methods and default caching are pushed down to a unified HTTP client; the mapping from fields to UI models sits in the anticorruption layer. This way, three types of changes don't entangle.

Rendering: HTML, Streams, and Data Handoff

The rendering layer mainly handles two things.

First, decide the output form: SSR HTML, CSR Shell, streaming response, or fallback to an alternate path on failure.

Second, safely hand over the Node‑side state to the browser so the client bundle can continue hydrating.

In other words, the BFF side cares more about how the request enters, what context exists, and where the data comes from; the template cares more about how data enters the DOM and how to fall back in case of exceptions.

CSR, SSR, hybrid, streaming—these are all page delivery forms. Using the Handle lifecycle and template to contain them prevents scattered conditional branches like "if SSR, do this; if CSR, do that" throughout business code.

Handoff: Serialization and Hydration

After aggregation and anticorruption, the data is still a JavaScript object in Node memory. The browser bundle cannot access this reference, so in SSR scenarios, the state must be passed through the HTML.

This process can be broken into two steps:

Serialization: In Node, convert the View Model into a string that can be embedded into a <script>, using a project‑unified global name, e.g., window.__SSR_RENDER_DATA__.
Deserialization and Hydration: After loading the bundle, the browser reads the same state and aligns the framework with the already‑output DOM, avoiding a full page repaint or double rendering.

Two types of issues are most common here.

Security issues: If the object contains user‑controlled fields, directly embedding unescaped JSON.stringify into <script> introduces XSS risk. Use safe serialization methods like serialize-javascript, and explicitly define which fields are allowed into the first‑screen state.

Performance issues: The larger the inline state, the greater the HTML size and parsing overhead. Large lists, detail fields, and low‑priority information should not be crammed into the first screen; trim what you can, paginate if necessary, and pass only identifiers, with details fetched by the client later.

Anticorruption solves "whether the data shape fits the UI"; handoff solves "whether the state can safely and reliably cross the Node/browser boundary." The most common SSR issues in production often originate from these two points.

Caching Is a Boundary Issue

Caching is not a separate layer; it usually sits on the boundary between cross‑cutting concerns and aggregation, which is why it's most error‑prone.

For example, an API might appear to be public data, but the request carries country, site, login state, or A/B experiments. Or the HTTP client caches responses by default, but the page assumes every request gets fresh data. These problems are frustrating to debug because the bug looks like a business issue, but the root cause lies in the cache key or default TTL.

We can categorize caching into three types:

Type	Purpose	Risk
Connection‑level default caching	Reduce downstream load, lower repeated read latency	If cache keys for user‑related read paths are poorly designed, data may be mixed up.
Request‑configured TTL	For hot public data, adjustable per environment	Overly long TTLs may delay visibility of configuration changes to users.
Application‑level throttling and coalescing	Prevent cache stampede, merge concurrent requests	Semantics differ from HTTP‑layer caching; best not to mix.

It's recommended to define clear rules: which paths are cache‑prohibited, which allow short TTLs, and which context fields must be included in cache keys. Don't rely solely on default behavior, and don't let page developers guess.

Benefits and Costs

The benefits of this separation are clear:

Site‑wide cross‑cutting rules evolve centrally; the scope of changes to business pages is controlled.
Aggregation and anticorruption stay within the page boundary; components do not directly depend on backend field shapes.
Rendering forms are decoupled from downstream gateway; templates and API versions can iterate separately.
Responsibilities of the ingress layer and presentation layer are separated, facilitating division of work, code review, and layered testing.

However, it also increases system understanding costs:

The request chain is longer; troubleshooting requires examining middleware, router, handle, and template.
Differences exist between development and production, especially with Vite middleware vs. static asset serving.
Proper logging, monitoring, and trace fields are required; otherwise, issues are hard to locate.

Therefore, this layering is suitable for scenarios where the page system has already become complex. When there are few pages and a simple integration approach, there's no need to set up all layers in advance.

Summary

A BFF should not be understood merely as a "Node forwarding layer." In a page system, it's more like a server‑side pipeline: cross‑cutting concerns first handle site‑wide rules, aggregation prepares the View Model at the page boundary, and rendering is responsible for HTML output, fallback, and state handoff.

The value of this layering is not to make the architecture diagram look nicer, but to give changes clear boundaries. Changes to site‑wide rules do not pollute page aggregation; changes to API fields do not pollute templates; changes to rendering strategy do not require reworking business APIs.

0 Comments

Leave a Comment