Web Fragments

0.8.2 verified Sat Apr 25 auth: no javascript

Web Fragments (v0.8.2) is a framework-agnostic micro-frontends architecture that isolates each fragment's JavaScript execution in a separate context while sharing the same DOM. Developed by Cloudflare, it supports client and server-side rendering, soft navigation, custom CSP, and SSR piercing. Released regularly (monthly patches/minors), it is production-tested at Cloudflare. Unlike other solutions, it offers true JS context isolation via a custom gateway and client-side virtualization, enabling incremental migration from monolithic apps.

Common errors

error Error: Cannot find module 'web-fragments/client' ↓

cause Using CommonJS require() to import the ESM-only subpath.

fix

Replace require with import: import { FragmentClient } from 'web-fragments/client'.

error TypeError: gateway.on is not a function ↓

cause FragmentGateway may not have an 'on' method; misshapen usage.

fix

Use gateway.route(req, ctx) inside Cloudflare Workers fetch handler instead of 'on'.

error Uncaught TypeError: failed to execute 'attachShadow' on 'Element' ↓

cause Browser does not support shadow DOM. Web Fragments require shadow DOM for piercing.

fix

Use a modern browser or add a shadow DOM polyfill.

Warnings

gotcha Note: CommonJS require() is not supported. Must use ESM imports. ↓

fix Use import syntax instead of require().

breaking Breaking: Fragments must register using URL or function (Fetch API) since v0.5.1. Old string endpoint deprecated. ↓

fix Update fragment registration to pass URL or fetch function.

deprecated Deprecated: The 'fetch' option in FragmentConfig is replaced by route method. Use gateway.route() directly. ↓

fix Replace fetch option with gateway route handler.

gotcha CSP headers must be configured per fragment via iframeHeaders; missing CSP can cause script execution failures. ↓

fix Set Content-Security-Policy in FragmentConfig#iframeHeaders.

breaking Breaking: Event system virtualization changed in v0.6.0 – event listeners on body may not work as expected. ↓

fix Attach event listeners to the fragment element instead of document.body.

gotcha Note: Browser support requires modern APIs (custom elements, shadow DOM). Not compatible with older browsers. ↓

fix Use polyfills for custom elements and shadow DOM if needed.

Install

npm install web-fragments

yarn add web-fragments

pnpm add web-fragments

Imports

FragmentGateway
wrong
```
require('web-fragments')
```
correct
```
import { FragmentGateway } from 'web-fragments/gateway'
```
ESM import from subpath 'gateway'. CommonJS not supported.

FragmentClient

wrong

const WebFragments = require('web-fragments')

correct

import { FragmentClient } from 'web-fragments/client'

Import from 'client' subpath. Use ESM.

FragmentConfig

wrong

import { FragmentConfig } from 'web-fragments'

correct

import type { FragmentConfig } from 'web-fragments/gateway'

Export is a type only; use type import.

HTMLRewriter

wrong

import { HTMLRewriter } from 'worktop'

correct

import { HTMLRewriter } from 'web-fragments/gateway'

Re-exported from Web Fragments gateway, not directly from worktop.

Quickstart

Shows basic server-side FragmentGateway and client-side FragmentClient setup with ESM imports.

import { FragmentGateway } from 'web-fragments/gateway';
import { FragmentClient } from 'web-fragments/client';

// Server-side gateway
const gateway = new FragmentGateway();
gateway.on('fetch', async (req: Request, ctx: any) => {
  const response = await gateway.route(req, ctx);
  return response;
});

// Client-side integration
const client = new FragmentClient();
client.registerFragment('my-fragment', { url: '/fragment' });
client.start();