Integration guide

Add modern JavaScript to server-rendered apps without a rewrite

Use progressive enhancement to add TypeScript state, lifecycle, events, and scoped routing to an existing server-rendered app without replacing its backend or initial HTML.

Package documentation API reference

Keep the server-rendered application authoritative

Incremental modernization works best when the existing platform keeps the responsibilities it already handles well: directly requestable URLs, initial semantic HTML, authentication, authorization, business rules, persistence, and canonical page metadata.

White Label can then own a narrower client-side boundary. That avoids turning a product filter, account control, cart status, or content interaction into a reason to rewrite the whole frontend.

Adopt one existing DOM region

Browser View can adopt an element that the server already rendered. When an attached root can be updated in place, an update(element, data) hook can handle model changes without introducing a second client-side template for the same markup.

Keep the ownership boundary narrow. The View owns its adopted root and lifecycle; unrelated headers, navigation, forms, siblings, and page chrome remain host-owned.

import {Model} from 'white-label-model';
import View from 'white-label-view';

const status = document.querySelector('[data-filter-status]');
const filters = new Model({color: ''});

const statusView = new View({
    parentElement: status.parentElement,
    element: status,
    model: filters,
    update(element, data) {
        element.textContent = data.color ? `Color filter: ${data.color}` : 'No color filter selected';
        return true;
    }
}).initialize();

Scope navigation to the feature that owns it

A page can contain more than one independently owned enhancement. Router navigationRoot limits data-pushstate click interception to one Document or Element instead of requiring every router to listen across the whole page.

The normal href remains authoritative. Links outside that root keep the host application’s behavior, while eligible links inside the enhanced region can use History API navigation.

const router = new Router();
router.navigationRoot = document.querySelector('[data-refinements]');
router.routes = {
    '/search': (_scope, location) => {
        filters.update({color: location.data.query.prefv1 || ''});
    }
};
router.initialize();

Compose only the pieces the feature needs

White Label packages are independently adoptable. Use Model when a feature needs observable state, Mediator when independent modules genuinely need to exchange intent, View when a DOM/rendering lifecycle needs an owner, and Router when URL state adds value.

Existing API clients, framework utilities, persistence layers, template engines, and backend services can stay in place. Translate or validate data at those application boundaries rather than adding product-specific adapters to the White Label runtime packages.

Preserve SEO and accessibility through progressive enhancement

For public content, important information should be present in the initial response. Keep real href values, semantic headings and controls, directly requestable routes, and server/static ownership of titles, descriptions, canonical URLs, robots directives, and structured data.

Client-side enhancement should preserve keyboard and modified-click behavior and deliberately manage focus or status announcements when content changes. Source metadata can make a page crawlable, but actual indexing and search performance must be verified against the deployed site rather than inferred from source code.

Where incremental adoption fits—and where it does not

This approach is especially useful for commerce and CMS storefronts, account areas, search/refinement interfaces, content-heavy public sites, and long-lived server-rendered applications where a full frontend rewrite would be disproportionate to the feature being added.

It is less differentiated for experiences intentionally owned almost entirely by the client—such as design tools, complex editors, collaborative workspaces, games, or other deeply stateful SPA-style applications—where a full component framework may provide more useful shared conventions.