Distribution, Testing & Tooling

Building a custom element is only half of shipping a framework-agnostic UI system. The other half is the pipeline that turns source modules into a versioned package, proves the component’s contract under automated tests, degrades gracefully on older engines, and renders correctly on the server. This domain governs everything that happens after a component works on your laptop and before it works in a thousand consuming applications you will never see. Treating distribution, testing, and tooling as a first-class architectural concern is what separates a demo from a dependency teams can build on.

This domain is the natural counterpart to Core Architecture & Lifecycle Management and Styling, Theming & CSS Encapsulation: those define what a component is, while this defines how it travels. A registration pattern that is flawless in isolation can still corrupt a consumer’s bundle if the package’s exports map is wrong, and a perfectly encapsulated style can still flash unstyled content if the component is server-rendered without declarative Shadow DOM.

Spec & ecosystem authority

Unlike the rendering primitives, distribution is governed by a mix of formal specifications and de facto ecosystem standards. The authoritative references for this domain are:

• WHATWG HTML Standard — Declarative Shadow DOM: the <template shadowrootmode> parsing rules that make server-rendered Shadow DOM possible without JavaScript.
• WHATWG DOM Standard — Element.getHTML() and ShadowRoot serialization: the normative algorithm for serializing shadow trees, including the serializable flag.
• Node.js package.json “exports” field: the conditional-exports resolution algorithm that every modern bundler and the Node loader implement.
• Custom Elements & Web Components polyfills (@webcomponents/webcomponentsjs): the community-maintained reference implementation tracking spec behavior for engines that lack native support.
• WCAG 2.2 & ARIA in HTML: the accessibility contract that automated audits assert against, which Shadow DOM boundaries complicate.

These are not optional reading. A package published without a verified exports map, or a server-rendered component that ignores the declarative Shadow DOM parsing rules, will fail in ways that are invisible during local development and only surface in a consumer’s production build.

Packaging & publishing

The most common way to break a component library is to publish it incorrectly. A component can be architecturally pristine and still be unusable if its package metadata misroutes the import, ships CommonJS that defeats tree-shaking, or omits type declarations. Packaging & Publishing treats the package.json exports field as the public API surface of the library — every entry point a consumer can reach must be declared, typed, and side-effect annotated.

{
  "name": "@acme/elements",
  "version": "1.4.0",
  "type": "module",
  "sideEffects": ["**/define-*.js"],
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./button": {
      "types": "./dist/button/index.d.ts",
      "default": "./dist/button/index.js"
    },
    "./package.json": "./package.json"
  },
  "files": ["dist"]
}

Contract & visual testing

A published component is a contract: a set of attributes, properties, slots, CSS custom properties, and events that consumers depend on. Contract & Visual Testing verifies that contract on every commit, asserting both the shape of emitted event payloads and the rendered pixels of the Shadow DOM. Because Shadow DOM is invisible to jsdom-style mocks, these tests must run in a real browser engine.

import { test, expect } from '@playwright/test';

test('ds-stepper emits a typed change payload', async ({ page }) => {
  await page.setContent('<ds-stepper value="2"></ds-stepper>');
  const detail = await page.evaluate(() => new Promise((resolve) => {
    const el = document.querySelector('ds-stepper');
    el.addEventListener('change', (e) => resolve(e.detail), { once: true });
    el.shadowRoot.querySelector('[part="increment"]').click();
  }));
  // The contract: { value: number, delta: number }
  expect(detail).toEqual({ value: 3, delta: 1 });
});

Polyfills & progressive enhancement

Native Custom Elements and Shadow DOM are supported across all current evergreen browsers, but the trailing edge of locked-down enterprise environments, embedded webviews, and email clients still demands a degradation strategy. Polyfills & Progressive Enhancement covers when to ship the @webcomponents/webcomponentsjs loader versus when to design components that remain meaningful as plain HTML before any script runs.

// Load the polyfill bundle only when a primitive is missing — never ship it to engines
// that already implement the spec natively.
if (!('attachShadow' in Element.prototype) || !('customElements' in window)) {
  await import('@webcomponents/webcomponentsjs/webcomponents-bundle.js');
}
// WebComponentsReady fires once polyfills (if any) are installed.
window.addEventListener('WebComponentsReady', () => {
  document.documentElement.removeAttribute('hidden');
});

Server-side rendering & hydration

For content-driven and SEO-sensitive products, a component must produce meaningful markup before its JavaScript executes. Server-Side Rendering & Hydration is built on declarative Shadow DOM: the server emits a <template shadowrootmode="open"> that the HTML parser attaches as a real shadow root, so the encapsulated content is painted on first byte and the client only needs to adopt it.

<!-- Server output: the parser attaches this as a shadow root, no JS required -->
<ds-card>
  <template shadowrootmode="open">
    <style>:host { display: block; border: 1px solid var(--ds-border, #2b3d73); }</style>
    <slot name="title"></slot>
    <slot></slot>
  </template>
  <h2 slot="title">Quarterly report</h2>
  <p>Revenue grew 18% year over year.</p>
</ds-card>

Types, manifests, and editor data

A published component library ships code, and a usable one ships a description of that code. Without it, editors offer no completion for tag names or attributes, TypeScript reports every element as Element, JSX rejects tags it has never heard of, and documentation has to be written by hand and kept in sync by discipline alone. Types & the Custom Elements Manifest covers the three artefacts that solve it, and the important property they share is that all three are generated from one source rather than maintained separately.

The manifest is the widest of the three, because it describes things the type system cannot represent at all — slots, parts, and CSS custom properties are a large part of a component’s public contract and have no TypeScript expression.

{
  "name": "@wfc/components",
  "type": "module",
  "customElements": "custom-elements.json",
  "files": ["dist", "custom-elements.json", "vscode.html-custom-data.json"],
  "exports": {
    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
    "./custom-elements.json": "./custom-elements.json"
  },
  "scripts": {
    "analyze": "custom-elements-manifest analyze",
    "prepack": "npm run build && npm run analyze",
    "verify:manifest": "npm run analyze && git diff --exit-code custom-elements.json"
  }
}

Three fields carry the integration. customElements is the conventional pointer tooling looks for; files decides whether the artefact ships at all; and the explicit exports entry is what lets a consumer’s tooling read it, because an exports map blocks deep imports by default. The verify:manifest script is what keeps the committed artefact honest — regenerate in CI, fail on a diff, exactly as a lockfile check works.

Deferred hydration and island loading

A page with forty components does not need forty definitions before it is useful. Most are below the fold, several are never interacted with, and a few carry more JavaScript than the rest of the page combined. Custom elements make deferring them unusually safe, because an element that has not been upgraded is still in the DOM, still styled, and still readable — customElements.define upgrades every matching element already present, so a late definition is late rather than missing.

Deferring hydration with islands develops the pattern: each server-rendered region is complete without script, and its definition is fetched on a trigger.

const island = document.querySelector('wfc-island');
const load = async () => {
  await import(island.dataset.src);
  await customElements.whenDefined(island.dataset.tag);
};

// Visibility covers scrolling readers…
new IntersectionObserver(([entry], observer) => {
  if (!entry.isIntersecting) return;
  observer.disconnect();
  load();
}, { rootMargin: '200px' }).observe(island);

// …and focusin covers keyboard users, who never trigger an intersection.
island.addEventListener('focusin', load, { once: true });

Cross-domain integration

The pipeline only holds together when these gates respect the primitives defined elsewhere on the site. Contract tests assert the Event Composition & Bubbling payloads that components emit, so a breaking change to an event’s detail shape is caught before publish, not after a consumer upgrades. Server-side rendering depends directly on Shadow DOM Construction & Modes: only serializable shadow roots survive getHTML(), and only declaratively-attached roots hydrate without a flash. Styling travels too — a package that ships scoped styles via constructable stylesheets must guarantee those sheets are reachable both at runtime and in the server-rendered output, or the SSR tier and the CSR tier will visibly disagree.

The same applies to framework integration: the adapters that bridge a component into React, Vue, or Angular are themselves a versioned part of the package surface, and their compatibility must be asserted by the same contract suite that guards the core element.

Production validation & contract testing

The quality gates in this domain are most valuable when wired into continuous integration as blocking checks. A mature pipeline runs, on every pull request: a publint and @arethetypeswrong/cli audit of the package metadata, a Playwright contract suite across Chromium, WebKit, and Firefox, a visual-regression diff with a small pixel threshold, and an axe-core accessibility audit that pierces Shadow DOM. Each gate maps to a failure that is otherwise discovered by a consumer in production.

// CI gate: fail the build if the package would resolve incorrectly for consumers.
import { execSync } from 'node:child_process';
execSync('npx publint --strict', { stdio: 'inherit' });
execSync('npx @arethetypeswrong/cli --pack', { stdio: 'inherit' });

Distribution & publishing implications

Every architectural decision in the other two sections has a packaging consequence. Components that register themselves on import need their registration modules excluded from tree-shaking; components that ship CSS need that CSS expressed as constructable stylesheets or inline <style> rather than separate files a bundler might drop; components that support SSR need their declarative Shadow DOM templates serialized with the serializable: true option so getHTML({ serializableShadowRoots: true }) captures them. The exports map should expose a single side-effect-free entry that defines nothing, plus per-component registration entries, letting consumers choose between auto-registration and manual control.

Performance & bundle implications

Distribution decisions are where a component library’s runtime cost is actually set, and three of them dominate.

Entry-point granularity decides what a consumer can avoid. A package with a single barrel export forces every consumer to reach for a bundler’s tree-shaking to avoid shipping components they never use — and that only works if every module is genuinely side-effect free apart from the registrations, which is precisely the part that is not. Per-component entry points in the exports map let a consumer import one component and its dependencies, with no analysis required and no way for the bundler to be wrong.

Registration and implementation should be separable. A module that exports a class and a sibling module that calls define on it costs one extra file per component and buys two things: a consumer can subclass without registering the base tag, and a scoped-registry consumer can register the class under a name of their own. Bundling the two together forecloses both, permanently.

Styles travel differently from code. A constructable stylesheet shared at module scope is parsed once for every instance on the page; a <style> element cloned into each shadow root is parsed once per instance. For a list of two hundred rows the difference is measurable, and it is decided entirely by how the package authored its styling — a distribution-layer choice with a rendering-layer cost. Where the support floor allows it, adopt a shared sheet and keep the <style> route as the detected fallback.

Deferred loading multiplies the value of the first two. Per-component entry points only help if something decides not to load one, and that decision belongs to the page rather than the bundler: an island trigger, a route split, a media gate. A library that ships granular entry points and documents which components are heavy enough to defer gives an application team the information they need to make that call, instead of leaving them to discover it in a performance audit.

The general shape of all four: the package decides what the consumer can optimise. A library that ships one file, one entry point, and one bundle has made every one of these decisions on the consumer’s behalf, and made them badly for anyone whose usage is narrower than the library’s full surface.

A last observation about all of this: none of the checks in this section are expensive, and every one of them fails silently when it is missing. A tree-shaken registration produces inert markup rather than an exception. A stale manifest produces confident autocomplete for an attribute that no longer exists. A misordered types condition produces a package that resolves at runtime and not at compile time. An island with only a visibility trigger produces a control that is unreachable by keyboard. In each case the library’s own test page passes, the consuming application is where the failure appears, and the report arrives as “your component does not work” with no further detail. Automating the five gates on this page is the difference between finding those in CI and finding them in someone else’s issue tracker.

Conclusion

Distribution, testing, and tooling convert a working component into a dependable one. The registry contract guarantees the right code reaches the consumer; the test gates guarantee that code keeps its promises across engines; the polyfill strategy guarantees a sane experience across the residual set of older environments; and server-side rendering guarantees the component is useful before its script arrives. Together they close the loop opened by the architecture and styling primitives — a component that is correct, encapsulated, and shippable is what makes a framework-agnostic design system something other teams can actually adopt.

Feature detection as a distribution strategy

“Does this browser support Web Components” is the wrong question, and every codebase that asks it ends up with a boolean that is true on engines missing half the API. There is no single feature: customElements, attachShadow, ElementInternals, CustomStateSet, constructable stylesheets, declarative shadow roots, manual slot assignment, and scoped registries each shipped on their own timeline and each degrade differently.

Testing them individually costs a few lines and is dramatically more reliable, because it tests what the component actually needs. The four detection shapes cover everything: property presence for members that exist or do not, behavioural probing for parser features with no reflected property, CSS.supports() for selectors, and a try/catch construction for APIs that throw rather than being absent.

// capabilities.js — evaluated once, at module scope, exported frozen.
const detectDeclarativeShadowDom = () => {
  const probe = document.createElement('div');
  const markup = '<x-probe><template shadowrootmode="open"></template></x-probe>';
  if (typeof probe.setHTMLUnsafe === 'function') probe.setHTMLUnsafe(markup);
  else probe.innerHTML = markup;
  return Boolean(probe.firstElementChild?.shadowRoot);
};

export const CAPABILITIES = Object.freeze({
  shadowDom: 'attachShadow' in Element.prototype,
  declarativeShadowDom: detectDeclarativeShadowDom(),
  elementInternals: 'attachInternals' in HTMLElement.prototype,
  constructableStyleSheets: 'adoptedStyleSheets' in Document.prototype,
  manualSlotAssignment: 'assign' in HTMLSlotElement.prototype
});

Two habits make the results usable. Compute the capability object once, at module scope: a declarative-shadow-DOM probe parses a fragment, and repeating that per instance is a measurable cost on a page with hundreds of components, with no possible change in the answer. And make every branch degrade to something that works — a <style> element where constructable sheets are absent, a data attribute where custom states are, a hidden input where form association is — so a test can assert the outcome rather than the mechanism and one test covers both paths.

The distribution consequence is that a library’s support matrix stops being a version table and becomes a capability table. That is a more honest artefact: it tells a consuming team exactly which behaviour they lose on their oldest supported engine, instead of a binary that was never accurate.

Frequently Asked Questions

Related

• Packaging & Publishing — exports maps, tree-shaking, and registry metadata.
• Contract & Visual Testing — asserting event payloads and Shadow DOM pixels in real browsers.
• Polyfills & Progressive Enhancement — feature-detected loading and graceful degradation.
• Server-Side Rendering & Hydration — declarative Shadow DOM and mismatch-free adoption.
• Core Architecture & Lifecycle Management — the primitives this pipeline distributes.