Many teams, when first building a page platform, treat configuration as an appendage to the component code: a config.json to display a component list in the backend, a few fields to render a form in the editor – that seems sufficient.

But as system complexity increases, this view quickly breaks down.

In the MultipleSite multi-site page platform, what truly and stably links the entire chain is not the React components themselves, nor a specific backend page, but a single protocol consumed by multiple subsystems. This protocol connects component assets on one end to the backend, editor, builder, SSR runtime, and local preview on the other. Without this protocol, every new link in the system adds another layer of fragile manual alignment; with it, page production transforms from "writing code" into "running a constrained pipeline."

This article focuses on three things:

Why, during multi-subsystem collaboration, a protocol evolves from "auxiliary information" to a "system contract."
What this protocol actually looks like in the repository, not just as the abstract concept of "metadata."
How the backend, editor, builder, SSR, and local preview each consume the same protocol.

I. When the Frontend Has More Than One Runtime Surface, the Protocol is No Longer Optional

When simply building a component library, the component source code is often the single source of truth. A developer imports a component, checks the props types, reads the README, runs a demo, and that covers most of the work.

But a page platform has more consumers than just developers.

In this project, at least five subsystems need to understand "what a component actually is":

Backend: Needs to display components to operators, knowing their name, category, and appearance.
Editor: Needs to dynamically generate forms based on configuration, rather than hand-coding settings panels for each component.
Builder: Needs to know at compile time what data a component depends on, which parameters are for fetching data, and which are for the component itself.
SSR Runtime: Needs to perform versioned loading based on the build output and data contracts.
Local Preview / Development Environment: Needs to read component definitions without connecting to the backend for local development and debugging.

If these five systems each "guess" component information from the source code, the system quickly spirals out of control.

The backend maintains its own component registry, the editor maintains another type mapping, the builder relies on conventions to read the fetch export, and eventually, every field addition, type change, or compatibility effort requires notifying multiple systems to update in sync. The system isn't broken by complex business logic, but by repeatedly describing the same fact.

Therefore, what a multi-site page platform truly needs is not "to make components configurable," but "to make configuration the only trusted system contract."

The following diagram summarizes this relationship:

The key point here is: The protocol doesn't describe "how to implement a component," but rather "how the system understands a component."

II. What This Protocol Actually Looks Like in the Repository

In MultipleSite, this contract isn't just a verbal agreement; it's explicitly written into the schema and each component's config.json.

The top-level schema is defined in components/configSchema.json. The schema directly reveals that the protocol isn't concerned with internal hooks or style breakdowns, but with these cross-system fields:

{
  "version": "string",
  "fileList": ["string"],
  "key": "string",
  "name": "string",
  "preview": "string",
  "category": ["common", "store", "product"],
  "fetchArgs": {},
  "fetchData": {},
  "config": []
}

Among these, six are core:

key: The globally unique identifier for the component, fundamental for backend recognition, editor import, and build artifact naming.
version: Component version number, not just a display field, but a basic unit for subsequent publishing, canary releases, and rollbacks.
preview: The preview image an operator sees, solving the problem of choosing the right component.
category: Classification information used by the backend to filter and organize the component list.
fetchArgs: Explicitly declares which injected data parameters the component needs.
config: Defines which fields an operator can edit, what controls they should use, and what rules they follow.

If the schema seems abstract, a real component configuration from the repository makes it clearer. For instance, PromotionBanner's configuration looks roughly like this:

{
  "$schema": "../../../configSchema.json",
  "version": "0.0.1",
  "key": "PromotionBanner",
  "name": "促销Banner",
  "preview": "https://.../promotion-banner.png",
  "category": ["common"],
  "config": [
    {
      "key": "media",
      "type": "media",
      "label": "背景资源",
      "required": true
    },
    {
      "key": "title",
      "type": "input",
      "label": "标题"
    },
    {
      "key": "link",
      "type": "link",
      "label": "链接"
    },
    {
      "key": "mTextPosition",
      "type": "select",
      "label": "文本位置",
      "options": [
        { "label": "顶部", "value": "top" },
        { "label": "底部", "value": "bottom" }
      ]
    }
  ]
}

The greatest value of this configuration is not that it "allows a component to support a few form fields," but that it elevates a component from a pure implementation to a standardized asset recognizable by the platform. Other modules in the system don't need to know PromotionBanner's JSX structure but can still understand its name, category, display method, editing interface, and data boundaries.

III. What the Backend Sees is Not Component Source Code, but the Asset Catalog Exposed by the Protocol

For the backend, React component source code is too low-level.

What an operator sees when building a page should not be a list of directory names or TSX files; they need a "selectable component catalog": each component with a name, category, preview image, and ideally, applicable scenarios.

This is precisely the purpose of the key, name, preview, and category fields.

From this perspective, the protocol solves two core backend problems:

How are components discovered?: After scanning component configurations, the backend can organize them into a selectable material library without needing to understand component implementation details.
How are components correctly selected?: Preview images and categories allow operators to identify components visually and semantically, reducing selection errors and trial-and-error costs.

This seems basic, but it signifies a shift in system boundaries: The backend no longer manages frontend code, but page materials wrapped by the protocol.

Once a system accepts this premise, many capabilities naturally emerge, such as:

Filtering components by category.
Restricting certain merchants to see only specific components.
Retaining old component versions after upgrades to prevent forced replacement in existing pages.
Displaying more user-friendly component descriptions and visual previews to operators.

Without the protocol layer, these features would ultimately rely on hardcoded tables, meaning you're not building a platform, but continually paying the cost of synchronization.

IV. The Editor Depends Most on the Protocol, Because It Essentially "Translates" Components

The editor is the part of the system that can least directly depend on component source code.

The reason is simple: component props are written for engineers, while editor forms are for operators. These are two completely different language systems.

For example, a developer understands:

type Props = {
  media: MediaAsset;
  title?: string;
  link?: LinkValue;
  mTextPosition?: 'top' | 'bottom';
}

But an operator needs to see:

Background: Upload or select media asset.
Title: Input field.
Link: Link configurator.
Text Position: Dropdown options.

This is explicitly done as a dynamic mapping in page-editor. The editor doesn't write a separate settings UI for each component. Instead, it reads the type from the configuration item and maps it to the corresponding control.

The supported types are clear in the code:

switch (props.value.type) {
  case 'input':
  case 'switch':
  case 'input-number':
  case 'image':
  case 'video':
  case 'select':
  case 'media':
  case 'link':
  case 'multiple-select':
  case 'group':
  case 'date-picker':
  case 'color-picker':
}

The main logic of the settings panel also illustrates this: The editor iterates over configInterface and uniformly renders CompInput for each item, without branching based on component name.

return props.configInterface.map((config, index) => (
  <CompInput
    value={ config }
    getSetting={ () => initSettings.current[config.key] }
    readOnly={ props.readOnly }
    properties={ [config.key] }
  />
));

This represents an important design shift:

If the editor programs against component implementations, adding a new component often means adding a significant amount of form code.
If the editor programs against the protocol, adding a new component usually just means adding a new configuration and implementation; the editor itself doesn't need to change.

In other words, the protocol liberates the editor from being a "custom UI factory for components" to becoming a "universal protocol interpreter." This is key to the platform's ability to scale.

The following diagram illustrates this translation chain:

The more stable the protocol, the more generic the editor; the looser the protocol, the more likely the editor degenerates into a web of if-else statements.

V. What the Builder Values Most is Not `config`, But `fetchArgs`

If the backend and editor primarily consume display and editing information, the builder is more concerned with another question: What is the relationship between this component and its data dependencies?

This is why fetchArgs is particularly important.

In many "configuration-driven" systems, data dependencies are buried within the component implementation, written in fetch methods, hooks, or even side-effect logic. This seems flexible short-term but prevents the build system from understanding the page's true dependency graph at compile time.

MultipleSite handles this strictly: PageBuilder directly validates whether the component's exported fetch matches the fetchArgs in its configuration.

The constraints in the code are very clear:

if (isFetchComponent && !componentConfigJson.fetchArgs) {
  Logger.warning("组件文件提供了 'fetch' 导出参数但是配置文件未提供 'fetchArgs'");
}
else if (!isFetchComponent && componentConfigJson.fetchArgs) {
  Logger.error("配置文件提供了 'fetchArgs' 但是组件文件未提供 'fetch' 导出参数");
}

When assembling component parameters, the builder splits them into two parts based on fetchArgs:

One part consists of the fetch parameters for the data retrieval process.
The other part consists of the display parameters passed to the React component.

The significance of this step is immense. It elevates "what data a component depends on" from an implementation detail to an explicit contract. This enables the builder to:

Detect inconsistencies between configuration and implementation at compile time.
Generate a clearer page dependency graph.
Inject necessary data during SSR or pre-building stages.
Decompose data fetching and component rendering into two more stable processes.

This is a quintessential engineering judgment: The protocol is not just for configuring UI forms; its more important role is to shift implicit runtime constraints forward to the build phase.

Once this is achieved, the system's reliability increases significantly. Many errors that would only surface during asynchronous requests in production are identified before deployment.

VI. What SSR and the Runtime Actually Consume is "The Product Organized by the Protocol"

When people talk about SSR, the focus is often on "how the server renders React components into HTML." For a page platform, however, this isn't the hardest part.

More critical is: How does the runtime know which components to load for a specific page version, what data to inject, and how to interpret the page structure using configuration?

From this perspective, the SSR runtime certainly doesn't scan the source code directory. It actually consumes the results generated by the builder based on the protocol:

Which component belongs to which version.
What the configuration looks like for components in that version.
Which parameters are rendering parameters and which are data parameters.
Which build artifacts and manifests correspond to the final page.

In other words, while the runtime might not directly read each component's raw config.json, the entire worldview it consumes is pre-shaped by the protocol.

This is fundamentally different from a system where "components can write whatever they want, and the runtime adapts on the fly." The advantages of the former approach are:

More stable version manifests.
Traceable build artifacts.
Easier to trace page issues back to the protocol or build stage.
Rollbacks and canary releases don't become a dangerous full redeployment.

From a system design perspective, the protocol's role here is to "reduce the dimension" for the runtime. It doesn't need to understand all implementation details, only to consume the normalized result.

VII. Local Preview is Possible Precisely Because the Protocol is Sufficiently Uniform

A frequently overlooked fact is that the local development environment is also a consumer of the protocol.

Without a unified protocol, local preview often becomes a collection of makeshift scripts: one component gets manually fed mock data, another gets a separate demo page, and discrepancies appear when connecting to the backend or SSR.

In this project, components/README.md explicitly states the constraints: for a component to be correctly read, it must at least follow the directory structure and provide index.ts, render.tsx, and config.json. This means local preview, build upload, and backend integration all rely on the same component description method, not three mutually compatible temporary solutions.

This uniformity yields two direct benefits:

Consistent cognitive model between development and production: How a component is identified locally is the same as how it's identified when entering the backend and build process.
Shorter troubleshooting paths: If a component isn't read correctly, you first check the protocol and structure, rather than guessing if some environment script failed.

For a platform system, this benefit of "define once, use everywhere" outweighs flexibility at individual function points.

VIII. The Real Challenge of Protocol-Driven Development is Not Defining Fields, but Guarding the Boundaries of Evolution

Writing a configSchema.json isn't difficult. What's difficult is maintaining its trustworthiness as the system evolves.

The protocol-driven approach most commonly fails in three ways:

8.1 Treating the Protocol as Comments, Not Constraints

If the schema is just "for reference" – the builder doesn't validate it, the editor doesn't consume it strictly, and the backend can freely add fields – then the protocol quickly loses its authority. The team inevitably reverts to an "implementation-centric" approach.

A valuable aspect of this project is that the build pipeline has begun to treat the protocol as a hard constraint, for example, the consistency check between fetch and fetchArgs. The more this practice is adopted, the higher the protocol's trustworthiness.

8.2 Stuffing All Changes into the Protocol

The protocol should carry shared facts across systems, not consume every business detail.

For instance, key, version, category, config, and fetchArgs are naturally cross-system. But forcing highly localized, implementation-specific logic into the protocol results in a bloated and unmaintainable configuration center.

A practical judgment standard is: If a field is only relevant to one system and strictly tied to implementation details, it might not be suitable for the shared protocol.

8.3 Protocol Upgrades Without a Compatibility Strategy

A page platform is not a one-time system, and the protocol cannot remain unchanged forever. The real difficulty lies in how to upgrade while:

Allowing new components to use new fields.
Not requiring immediate migration for old components.
Enabling the editor and builder to recognize different protocol phases.
Preventing the release system from bulk-breaking existing pages due to protocol upgrades.

This is why the article emphasizes that version is important. It's not just a component version number; it's the system's handle for organizing compatibility. A protocol without version awareness will struggle to support long-term evolution.

IX. In Retrospect, the Essence of Protocol-Driven Development is Externalizing "Consensus" from Human Minds.

If this article only concluded that "configuration is important," it wouldn't be very meaningful. What's truly worth summarizing is this: the protocol-driven approach doesn't solve the problem of configuration files; it solves the problem of distributing consensus in complex systems.

The backend, editor, builder, SSR, and local preview all need to understand "what a component is." If this understanding relies on verbal communication, documentation, or experience, it inevitably diverges as the system scales. The protocol externalizes this consensus into a structured, verifiable, consumable, and evolvable contract.

Therefore, it is not a fallback for code; on the contrary, it is a higher-level system design.

For a multi-site page platform, what truly matters is not "having many components," but whether these components are first described as unified assets; not "whether the editor supports drag-and-drop," but whether the editor only needs to understand the protocol; not "whether SSR can render," but whether the build and runtime are based on the same contract.

In other words, the protocol-driven approach is not about replacing code with configuration; it's about using a protocol to pull multiple systems back into the same reality.

This is the most reusable part of the MultipleSite system.

0 Comments

Leave a Comment