"Why does a seemingly small requirement end up requiring changes to three pieces of code?"

In multi-merchant projects, this sentence is usually not a complaint but a reality in work orders.

Initially, everyone thinks that multi-merchant is nothing more than adding a few extra condition checks to the common code. Today, you add an if (merchant === 'a') for Site A, tomorrow another if (merchant === 'b') for Site B, and the feature can go live quickly. In the short term, this approach even feels convenient.

The problem is that system loss of control often begins this way.

Once differences have no boundaries, they spread across components, APIs, layouts, tracking, styles, routing, and configurations. Eventually, the common layer gets mixed with merchant-specific cases, and merchant code in turn encroaches on the common implementation. Modifying one button makes you worry about the form; changing an API means you also have to regression-test SSR. The repository may still be one repository on the surface, but in reality, it has started sliding toward "multiple intertwined semi-finished products."

The real difficulty of multi-merchant is never "supporting multiple merchants" but "making differences have boundaries and fixed points, and preventing them from scattering everywhere."

In the MultipleSite multi-site page platform, we gradually converged on a more stable approach: not treating merchant differences as scattered conditional branches, but as something to be governed. The article below describes several methods that have been implemented in the repository and have genuinely helped us avoid pitfalls.

1. Why Systems Lose Control

Multi-merchant projects usually fail not because of business complexity, but because differences are not designed.

The most common ways of losing control are basically the same.

First, the scope of differences keeps expanding. Initially, it's just UI differences; after two rounds of requirements, APIs, tracking, form rules, and error handling all start diverging. If the team hasn't defined "which differences are allowed into the system and which are not," each new requirement pushes the boundary a bit further.

Second, condition checks are scattered. Merchant checks may appear in components, utility functions, data layers, SSR logic, or even style concatenation. Each if in isolation is not scary; the real trouble is that no one knows how many such checks exist. Maintenance costs don't rise linearly—they compound.

Third, the boundary between commonality and individuality becomes blurred. Common components quietly insert a merchant-specific flow to accommodate a particular merchant; merchant-specific components start depending on internal details of the common layer. Over time, the name "common module" remains, but the commonality is gone.

Fourth, changes start to interweave. You only wanted to modify the page style for Brand A, but you end up having to regression-test Brand B's APIs, forms, tracking, and SSR outputs. The requirement hasn't grown, but the test scope expands first.

Therefore, what multi-merchant governance truly aims to solve is four things:

When modifying one merchant, the impact should be as localized as possible
When reading code, one can quickly distinguish between commonalities and differences
When adding a new difference, the team knows which layer it should land on, rather than patching everywhere
When onboarding a new merchant, the cost of copying and adaptation can be estimated

Without achieving these points, as the system scales, the pace will be dictated by technical debt.

2. Governing Differences: Not Eliminating Them, but First Layering Them

When many teams talk about governance, they instinctively want to "unify." But in multi-merchant systems, differences are real. The real problem is not "why differences exist," but the following two questions:

Should this difference reside in configuration or implementation?
Should this difference be isolated in a directory, protocol, wrapper layer, or only appear in a few runtime branches?

In this project, we prefer to split differences into four categories:

Presentation differences: styles, copy, media resources, layout order
Protocol differences: component configuration, editable fields, default values
Dependency differences: upstream SDKs, component libraries, HTTP clients, session implementations
Runtime differences: few logic branches that must depend on the current merchant environment

After this layering, many arguments naturally disappear. Presentation differences are preferentially handled via configuration; protocol differences via naming conventions; dependency differences via wrapper layers; and runtime differences are strictly limited.

First, take a look at this decision framework:

Difference Type	Preferred Handling Method	Typical Example
Presentation Diff	Configuration override	Copy, images, order, styles
Protocol Diff	Merchant-specific config file	Field visibility, defaults, editor schema
Dependency Diff	Base layer wrapper	SDK, HTTP Client, shared modules
Runtime Diff	Few whitelist branches	Logic that must read current merchant environment

The methods below are all centered around this layering.

3. Method 1: Directory Isolation – Making Differences Visible at a Glance

If a component's differences between two merchants are more than "minor tweaks," the safest approach is usually not to keep piling branches in the same file but to split the implementations.

For example, the BtnTextWithPic component splits the implementation for two merchants into two files:

import aComp from "./render.a";
import bComp from "./render.b";
 
const exportComponent = __MERCHANT__ === "a" ? aComp : bComp;
export default exportComponent;

The real value of this pattern is not just "splitting files" but "a unified entry point." The caller only depends on one entry; the differences are sealed within the component boundary and do not leak outward.

This approach suits two scenarios:

The UI structures of the two merchants are already significantly different
Some dependencies, interactions, or lifecycles cannot be shared at all

Its benefits are straightforward:

Differences are explicit; no need to search for if/else across the codebase
Each merchant's implementation can evolve independently
The common caller does not need to understand merchant details

Of course, the trade-offs are real:

If only 10% differs between the two implementations, duplicated code can be ugly
Without a unified entry point, directory isolation can easily degrade into "forking everywhere"

So directory isolation should not be the default answer; it's more like a signal: the difference is large enough to warrant separate maintenance. In short, use physical boundaries in exchange for cognitive boundaries.

4. Method 2: Naming Conventions – Keeping Differences in the Configuration Layer

Not all differences are worth splitting implementations. Often, differences are just default copy, field toggles, resource URLs, or a few form items. In such cases, copying a component implementation is usually an overreaction.

A more stable approach is to copy configuration, not logic.

There are ready examples in the repository:

components/src/components/SubscribeLottery/config.a.json
components/src/pageLayoutComponents/CommonTpl/config.b.json

Behind these files lies an important constraint: merchant differences don't necessarily have to enter TSX; they can stay in protocol files.

This approach has several clear benefits.

First, the main component implementation is not polluted by differences. Editable items, default values, and validation rules visible to operators can be overridden per merchant, but the rendering logic remains stable.

Second, the toolchain can handle them uniformly. As long as the repository has a fixed convention for names like config.json, config.a.json, config.b.json, the editor, builder, and backend can load them following the same rules, rather than each component having its own special logic.

Third, configuration differences are easier to review than implementation differences. During code review, you can quickly determine whether this is just a merchant configuration change or if it's starting to encroach on common behavior.

This strategy is best suited for:

Copy and media resources
Default values and options
Some merchant-specific configuration fields
Configuration changes directly related to the editor protocol

If a difference can stay in the configuration layer, try not to push it into implementation. Because once a difference enters the implementation layer, the costs of testing, regression, and upgrades will follow.

5. Method 3: Dependency Wrapping – Blocking Upstream Forks from Business Code

There's another dangerous type of difference in multi-merchant: not your own business divergence, but the divergence of the dependencies you rely on.

Once business code directly depends on different merchants' SDKs, HTTP clients, or shared component libraries, consequences usually appear quickly. Every business module has to understand the merchant context, and soon the project is full of tacit knowledge like "which import is for whom."

Our approach is to use a merchant-specific wrapper layer to absorb the differences first.

For example, Subscribe.ts:

import { Subscribe as ASubscribe } from "@a-deps/web.fe.shared-modules";
import { Subscribe as BSubscribe } from "@b-deps/web.fe.shared-modules";
 
export const Subscribe = __MERCHANT__ === "a" ? ASubscribe : BSubscribe;

The value of such wrapper layers becomes especially noticeable once the project grows a bit larger.

First, it compresses merchant differences into a small number of basic modules. Page components, business modules, and utility functions do not need to directly perceive upstream forks.

Second, it provides a buffer for upgrades. When an upstream library needs upgrading, the adaptation can be handled first in @a-deps/* or @b-deps/* without directly impacting the entire business layer.

Third, it keeps the external API stable. Underlying dependencies can differ, but as long as the wrapper layer exposes a uniform interface, the upper-level code does not need large-scale changes.

The most important constraints here are only two:

Only expose a unified interface externally; do not continue leaking merchant details upward
Merchant branches should stay in the infrastructure layer as much as possible, not spread to the page layer

6. Method 4: `MERCHANT` Can Be Used, but Only as a Narrow Emergency Exit

In multi-merchant projects, global variables like __MERCHANT__ are basically unavoidable. The real problem is never "can we use it?" but "has it become the default solution?"

In this project, such branches do exist. For example, HttpClient.ts selects a different client at runtime based on __MERCHANT__, and logger.ts loads different implementations based on the current merchant. These positions are reasonable because they are inherently critical paths that must understand the runtime environment.

A pragmatic principle is:

Allow a small number of __MERCHANT__ usages in the infrastructure layer
Avoid __MERCHANT__ in page components as much as possible
Problems that can be solved with configuration or directory isolation should not be downgraded to global branches

Why enforce this? Because the biggest problem with global variables is not that they are hard to write, but that they are too convenient. Anyone can add a check anywhere, solve the current requirement in five minutes, and simultaneously break another piece of governance.

A more stable approach is to treat it as a whitelist capability:

Which directories are allowed to have __MERCHANT__
Which scenarios must first try configuration or directory isolation
Which new branches need a reason explanation

Only when this is done can the global variable be a safety net, not the default.

7. What Differences Go into Configuration, What Go into Implementation

This is the issue that most easily leads to back-and-forth debates in multi-merchant governance. A sufficiently practical criterion is:

If the difference changes content and presentation, prioritize configuration; if it changes flow and algorithms, then consider implementation.

More specifically:

Into configuration: usually styles, copy, images, videos, default values, toggles, field visibility, editable items
Into implementation: usually data processing flows, API adaptation, complex interactions, performance optimizations, merchant-specific business rules

What really causes problems are the gray areas that are "half-presentation, half-business." For example, a button color looks like a presentation difference, but if the button also carries tracking, eligibility checks, and navigation logic, it's no longer just a configuration problem.

So during code review, I suggest repeatedly asking these three questions:

Does this difference only change content, not behavior?
Does this difference really require the caller to be aware of the merchant?
If a third merchant is added in the future, will this approach still hold up?

These three questions may seem simple, but they can stop most impulses to "just write a condition check for now."

8. Effective Governance Is Not a Pattern Checklist but a Constraint Mechanism

Directory isolation, naming conventions, dependency wrapping, whitelisting global variables—these are all just means. Whether the system will continue to lose control ultimately depends on whether the team turns these means into constraints.

In practice, you should at least clarify the following four rules:

When adding a new merchant difference, first determine whether configuration can solve it; do not default to the implementation layer.
Merchant branches should be as close to the boundary layer as possible; do not spread into page orchestration and internal common components.
The responsibilities of common modules should be stable; do not keep injecting individual logic just to accommodate a particular merchant.
Periodically review the distribution of differences, such as how many __MERCHANT__ have been added, how many directories have merchant-specific implementations, and how many common modules have started depending on merchant-specific packages.

Whether multi-merchant governance is effective can ultimately be reduced to a few very specific questions:

If I only want to change A, how many files do I need to touch?
If I want to upgrade a common dependency layer, how many merchants will be affected?
If I want to onboard a new merchant, is it primarily reuse or copy?
If a merchant temporarily disables a feature, can it be done without affecting other merchants?

The faster and clearer these questions can be answered, the more controllable the system is.

Takeaways

In multi-merchant systems, the biggest fear is not having many differences, but having no fixed place for differences.
Differences that can go into configuration should not be rushed down to implementation; forks that can stay at the boundary layer should not spread to the page layer.
A truly maintainable multi-merchant architecture is not "supporting multiple sites," but "the team knows how each difference should be constrained."

Looking back, the most valuable experience in this project is not how many merchants we support, but how we gradually converged scattered condition checks into several fixed patterns: implementation differences via directory isolation, protocol differences via naming conventions, dependency differences via wrapper layers, and only a very few runtime differences via global variables.

Multi-merchant is not about copying sites; it's about governing differences. If this premise is not established, the codebase will eventually govern you back.

0 Comments

Leave a Comment