Registry / web-framework / web-fragments

web-fragments

library4.0.0jsnpmunverified

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.

web-framework devops

npm install web-fragments

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WEB-FRAGMENTS

web-fragments

web-frameworkjavascriptv4.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

FragmentGateway

✓ import { FragmentGateway } from 'web-fragments/gateway'

✗ require('web-fragments')

ESM import from subpath 'gateway'. CommonJS not supported.

FragmentClient

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

✗ const WebFragments = require('web-fragments')

Import from 'client' subpath. Use ESM.

FragmentConfig

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

✗ import { FragmentConfig } from 'web-fragments'

Export is a type only; use type import.

HTMLRewriter

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

✗ import { HTMLRewriter } from 'worktop'

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

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();

Debug

Known issues

gotchaNote: CommonJS require() is not supported. Must use ESM imports.

fix

Use import syntax instead of require().

affects: >=0.5.0

breakingBreaking: 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.

affects: <0.5.1

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

fix

Replace fetch option with gateway route handler.

affects: >=0.7.0 <0.8.0

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

fix

Set Content-Security-Policy in FragmentConfig#iframeHeaders.

affects: >=0.8.0

breakingBreaking: 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.

affects: >=0.6.0

gotchaNote: 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.

affects: >=0.1.0

Errors

Common errors & fixes

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

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

fix

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

TypeError: gateway.on is not a function

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

fix

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

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

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

fix

Use a modern browser or add a shadow DOM polyfill.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

worktopoptionalRouter/request handler for Cloudflare Workers, used in examples and likely runtime

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/web-fragments/web-fragments ↗

packagehttps://www.npmjs.com/package/web-fragments ↗

homepagehttps://web-fragments.dev ↗