Unified Access for Multiple Rendering Modes: A Design Approach for a BFF Page Architecture

When building a BFF page system, we quickly encountered a problem: different pages have different rendering requirements.

Some pages need SEO, some have heavy interaction, some prioritize first-screen performance, and others care more about stability. More troubling is that once an error occurs on the SSR path, users may not even get a usable page. Interface timeouts, abnormal data formats, module loading failures, and renderToString errors can all break a page request.

If each type of page adopts its own rendering flow, it may be fast in the short term, but over time it becomes a pile of scattered entry points, templates, and exception handling logic. Eventually, the team is not maintaining pages but rather various historical access methods.

This article documents a reorganization of our BFF page architecture: the unified aspect is the page access method, not the page rendering method. Pages can choose SSR, CSR, static generation, or a hybrid mode, but they must declare, register, render, and degrade in the same way.

The Problem Is Not SSR vs. CSR

The difference between SSR and CSR is not hard to understand.

SSR has a fast first screen, is SEO-friendly, and content appears earlier in the HTML. However, it puts data fetching, template execution, and component rendering all into the server request chain; any error in any part can affect the entire page output.

CSR has a weaker dependency on the server and is generally more stable, but it suffers on the first screen and SEO. For highly interactive pages, this is not a problem; for marketing pages, landing pages, and public detail pages, it becomes more apparent.

A more common situation in real projects is that a team cannot stick to just one mode.

Marketing pages need SSR or static generation.
Backend pages and configuration pages are better suited for CSR.
Some pages prefer SSR but want to fall back to CSR on failure.
Others just need to reuse unified routing and templates without caring about the underlying rendering flow.

So the real issue here is not "choose SSR or CSR", but: how can pages be accessed in a unified way, how can the platform select the rendering flow based on the page declaration, and how can it continue to deliver a usable page on failure?

Why Place This at the BFF Layer

The BFF sits right between the user request and the business services. It knows the domain, path, language, and device information of the current request, and can also chain data fetching, page templates, error handling, and log reporting.

If we put multi-rendering access at the pure frontend layer, the page is already in the browser, and there is no discussion of SSR success or failure. If we place it further up at the gateway layer, the gateway should not understand React components, page templates, or business rendering contexts.

The BFF layer is suitable for this because it can handle several types of information simultaneously:

Request context: domain, path, language, AB experiments, device type.
Page configuration: page type, routing rules, rendering template, degradation strategy.
Rendering runtime: server entry loading, data fetching, HTML slot injection.
Failure handling: SSR exception capture, logging, CSR fallback output.

This does not mean every project should adopt a BFF page platform. It is suitable for teams with many pages, diverse rendering requirements, and a desire for unified access standards. For small projects with a single page type and no SEO or server-side rendering requirements, this approach would be overkill.

How Pages Are Accessed in a Unified Manner

The key to unified access is to let pages declare themselves first, rather than forcing developers to modify entry files everywhere.

A page can be described with a config.toml like this:

[page]
type = "react-ssr-fallback-csr"
 
[router]
domain = "<%=SERVER_OFFICIAL_DOMAIN%>"
path = ["/cart"]
 
[render]
fallback = "csr"
timeout = 3000

This configuration expresses several things:

type determines which type of template the page uses.
router determines under which domain and path the page is mounted.
fallback determines how to continue delivery after SSR failure.
timeout gives a clear upper limit for the server-side rendering chain.

The page integrator only needs to maintain the page configuration and business entry. Route registration, template selection, client entry, server entry, and exception fallback are all filled in by the platform based on the configuration.

Once a request comes in, the flow is roughly like this:

The key here is not how complex the flowchart is, but that both success and failure paths are built into the platform flow. Failure is not scattered try/catch in business code; it is part of the page system.

Templates Handle Different Rendering Modes

The type in the page configuration ultimately maps to a template selection.

Templates describe how a class of pages is delivered, for example:

react-csr: outputs only the client entry and basic HTML.
react-ssr: renders HTML on the server first, then the client hydrates.
react-ssr-fallback-csr: SSR first, falls back to CSR Shell on failure.
static: generates static content at build time.

The value of templating is not just "supporting more modes", but extracting the rendering flow from business pages. Business pages no longer need to repeatedly worry about creating client entries, loading server entries, injecting HTML slots, or handling SSR failures.

When the team needs to adjust the rendering strategy for a certain class of pages, they modify the template capabilities, not rewrite dozens of pages one by one.

This is also why "unified access" and "unified rendering" should be considered separately. Unified rendering would force all pages to follow the same mode, which eventually leaves someone unsatisfied; unified access means different modes hang under the same platform protocol.

How to Degrade to CSR after SSR Failure

The most worth elaborating on in this architecture is the automatic fallback to CSR after SSR failure.

It does not aim to "make errors disappear", but to turn errors into a manageable state. After SSR fails, the user may not get the ideal first-screen HTML, but at least they get a runnable CSR page.

Common sources of SSR failure include:

Server interface timeout or abnormal data returned.
Page module loading failure.
Errors thrown during React rendering.
Dependence on browser-only APIs such as window or localStorage.
Errors in template slot injection, serialization, or data transformation.

The platform-level handling logic can be simplified like this:

async function renderPage(ctx: RenderContext): Promise<Response> {
  const page = await matchPage(ctx);
  const template = await resolveTemplate(page.type);
 
  if (!template.ssr) {
    return template.renderCSR(ctx);
  }
 
  try {
    return await withTimeout(
      template.renderSSR(ctx),
      page.render.timeout ?? 3000,
    );
  } catch (error) {
    reportSSRFailure(error, {
      pageId: page.id,
      url: ctx.url,
      fallback: page.render.fallback,
    });
 
    if (page.render.fallback === 'csr') {
      return template.renderCSR(ctx);
    }
 
    throw error;
  }
}

This logic has several key points.

First, SSR failure must be recorded. Degradation is not about swallowing errors; otherwise, online would become "users don't report errors, but the system has been silently degrading." Logging, metrics, and alerts should be done here.

Second, degradation must be controlled by page configuration. Not all pages are suitable for CSR fallback. For strongly SEO pages, degradation to an empty shell would cause search engines to see nothing; while for some post-login pages, configuration pages, or activity pages, CSR fallback might be a more reasonable trade-off.

Third, the CSR Shell must also be a formal artifact. It is not a temporary error page, but an HTML that allows the browser to re-fetch data and re-render the business page.

The entire process can be seen in a sequence diagram:

The value of this fallback path is turning "what to do after failure" from a temporary patch into platform behavior. Pages do not need to invent their own error recovery logic, and the platform can uniformly observe SSR failure rates and degradation status.

Three-Layer Division

Breaking down the implementation, this system roughly consists of three layers.

The Page Layer describes the page itself: page configuration, routing information, page entry, and which template the page selects. It answers "who is this page and how does it want to be delivered."

The Runtime Layer handles request processing and rendering: matching routes, loading templates, executing SSR, outputting CSR Shell, and handling degradation and error reporting. It answers "how does the system deliver the page to the user."

The Business Capability Layer provides APIs, shared components, business hooks, and common utilities. It answers "what business capabilities are needed during page rendering."

By splitting into these three layers, a page is no longer an isolated piece of code but a standard unit in the platform. Business pages focus only on business expression, the runtime layer handles rendering and failure recovery, and the underlying capabilities remain reusable.

What Scenarios Is This Approach Suitable For?

This architecture is not the sooner the better. It is suitable for the following scenarios:

There are many pages with different requirements for SSR, CSR, and static generation.
The team wants to unify routing, templates, entries, and page access standards.
The business cares about SEO, first-screen experience, and online stability simultaneously.
SSR failures cannot directly affect user access, and a formal degradation strategy is needed.
Multiple page teams share one page platform and need to consolidate underlying rendering capabilities.

Scenarios where it is not suitable are also clear: small projects, single page type, no SEO requirements, and no need for server-side rendering. In those cases, directly using plain CSR or the framework's default capabilities is lighter.

Whether an architecture is reasonable does not depend on how complete it looks, but on whether it matches the scale of the problem. Building a platform for three pages is likely over-engineering; unifying entry points, templates, and degradation strategies for dozens of pages brings real benefits.

Summary

Unified access for multiple rendering modes is not about adding more rendering methods to pages. It is about converging page access methods, template selection, and failure recovery into the same BFF page platform.

After doing this, business pages no longer need to repeatedly set up entry points and rendering flows; the platform can uniformly handle routing, templates, SSR execution, CSR fallback, and exception monitoring. Different rendering modes can still coexist, but they no longer each develop their own access method.

In the end, what is actually saved is not just a few lines of entry code, but the maintenance cost as pages grow.

2026-04-24

0 Comments

Leave a Comment