# White Label JS

> Framework-independent TypeScript packages for progressive enhancement, observable state, rendering/lifecycle, application events, routing, and project generation.

Canonical site: https://whitelabeljs.org/

White Label is a set of focused packages rather than a required framework stack. Packages can be adopted independently or composed. Its strongest fit is application structure without a framework takeover: meaningful initial HTML, selective progressive enhancement, incremental modernization of existing server-rendered applications, and explicit browser/server lifecycle boundaries.

## Start here

- Documentation: https://whitelabeljs.org/docs/
- API index: https://whitelabeljs.org/api/
- Model: https://whitelabeljs.org/docs/model/
- View: https://whitelabeljs.org/docs/view/
- Mediator: https://whitelabeljs.org/docs/mediator/
- Router: https://whitelabeljs.org/docs/router/
- Generator: https://whitelabeljs.org/docs/generator/
- Sitemap: https://whitelabeljs.org/sitemap.xml

## Fit and integration model

- Progressive enhancement: public content and navigation should remain meaningful before client JavaScript runs.
- Existing server-rendered/CMS/commerce applications: keep the host platform's initial HTML, directly requestable URLs, authentication, authorization, business rules, and persistence; adopt White Label only where client-side state/lifecycle/events/routing add value.
- View can adopt an existing attached DOM root and update it in place without a client template when `update(element, data)` handles the render.
- Router can scope `data-pushstate` click interception to a `navigationRoot` instead of requiring document-wide ownership. `navigationRoot` is separate from route callback `scope`.
- Model and Mediator remain independently useful standards-oriented primitives; they do not require the rest of White Label.
- The generator is for new projects and rejects non-empty destinations. Existing applications should install runtime packages directly rather than merging a generated scaffold into host code.
- White Label is not positioned as a universal replacement for full component frameworks. Deeply client-owned editors, design tools, collaborative workspaces, games, and similar SPA-style applications may benefit more from framework conventions.

## Important contracts

- Model and Mediator use standards-based EventTarget/CustomEvent semantics. Event payloads are read from `CustomEvent.detail`.
- Model owns synchronous observable state; networking and persistence stay application-owned. Retained proxies that still point to live aliased/reindexed state report mutations using a current path; proxies detached by root replacement or no longer reachable from current state stay silent.
- View binds observable models through `addEventListener`/`removeEventListener`; browser and server entry points remain distinct. Server cleanup resets internal binding state before attempting external listener removal so the instance remains reusable after cleanup failures. Its first-party rendering helper is `white-label-view/html`; third-party renderers remain application-owned choices.
- `white-label-view/html` escapes ordinary interpolated text and quoted attribute values. `attributes()` validates attribute names and rejects intrinsic `on*` handlers and `srcdoc`. `unsafeHTML()`, application-owned HTML strings, and third-party renderer output are explicit trust boundaries. HTML escaping is not a URL, CSS, or general application-policy sanitizer.
- Router progressively enhances real links. Modified clicks/downloads/alternate targets/cross-origin or unmatched navigation remain native. Rejected navigation does not destroy the current route or push a history entry. Object-route teardown stays paired with the lifecycle that actually initialized, even if route configuration later changes.
- Mediator is an in-memory application event boundary, not a durable queue or cross-process broker.
- Generator emits one canonical tagged-HTML TypeScript scaffold and refuses to overwrite non-empty destinations.
- Networking, persistence, authorization policy, sanitization policy, and cloud/provider/CMS/commerce adapters remain application concerns unless a package explicitly documents otherwise.

## Guides

- Incremental JavaScript for server-rendered apps: https://whitelabeljs.org/guides/incremental-javascript-for-server-rendered-apps/
- State management without React: https://whitelabeljs.org/guides/typescript-state-management-without-react/
- Progressive-enhancement routing: https://whitelabeljs.org/guides/typescript-progressive-enhancement-routing/
- Server-side rendering: https://whitelabeljs.org/guides/server-side-rendering-without-component-framework/
- TypeScript event bus: https://whitelabeljs.org/guides/typescript-event-bus/

## Integration guidance

- Existing server-rendered applications: https://whitelabeljs.org/guides/incremental-javascript-for-server-rendered-apps/
- Server-side rendering: https://whitelabeljs.org/guides/server-side-rendering-without-component-framework/
- Progressive-enhancement routing: https://whitelabeljs.org/guides/typescript-progressive-enhancement-routing/

## Source

- Generator: https://github.com/bshack/white-label
- Model: https://github.com/bshack/white-label-model
- View: https://github.com/bshack/white-label-view
- Mediator: https://github.com/bshack/white-label-mediator
- Router: https://github.com/bshack/white-label-router