{"id":20701,"library":"web-fragments","title":"Web Fragments","description":"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.","status":"active","version":"0.8.2","language":"javascript","source_language":"en","source_url":"https://github.com/web-fragments/web-fragments","tags":["javascript"],"install":[{"cmd":"npm install web-fragments","lang":"bash","label":"npm"},{"cmd":"yarn add web-fragments","lang":"bash","label":"yarn"},{"cmd":"pnpm add web-fragments","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Router/request handler for Cloudflare Workers, used in examples and likely runtime","package":"worktop","optional":true}],"imports":[{"note":"ESM import from subpath 'gateway'. CommonJS not supported.","wrong":"require('web-fragments')","symbol":"FragmentGateway","correct":"import { FragmentGateway } from 'web-fragments/gateway'"},{"note":"Import from 'client' subpath. Use ESM.","wrong":"const WebFragments = require('web-fragments')","symbol":"FragmentClient","correct":"import { FragmentClient } from 'web-fragments/client'"},{"note":"Export is a type only; use type import.","wrong":"import { FragmentConfig } from 'web-fragments'","symbol":"FragmentConfig","correct":"import type { FragmentConfig } from 'web-fragments/gateway'"},{"note":"Re-exported from Web Fragments gateway, not directly from worktop.","wrong":"import { HTMLRewriter } from 'worktop'","symbol":"HTMLRewriter","correct":"import { HTMLRewriter } from 'web-fragments/gateway'"}],"quickstart":{"code":"import { FragmentGateway } from 'web-fragments/gateway';\nimport { FragmentClient } from 'web-fragments/client';\n\n// Server-side gateway\nconst gateway = new FragmentGateway();\ngateway.on('fetch', async (req: Request, ctx: any) => {\n  const response = await gateway.route(req, ctx);\n  return response;\n});\n\n// Client-side integration\nconst client = new FragmentClient();\nclient.registerFragment('my-fragment', { url: '/fragment' });\nclient.start();","lang":"typescript","description":"Shows basic server-side FragmentGateway and client-side FragmentClient setup with ESM imports."},"warnings":[{"fix":"Use import syntax instead of require().","message":"Note: CommonJS require() is not supported. Must use ESM imports.","severity":"gotcha","affected_versions":">=0.5.0"},{"fix":"Update fragment registration to pass URL or fetch function.","message":"Breaking: Fragments must register using URL or function (Fetch API) since v0.5.1. Old string endpoint deprecated.","severity":"breaking","affected_versions":"<0.5.1"},{"fix":"Replace fetch option with gateway route handler.","message":"Deprecated: The 'fetch' option in FragmentConfig is replaced by route method. Use gateway.route() directly.","severity":"deprecated","affected_versions":">=0.7.0 <0.8.0"},{"fix":"Set Content-Security-Policy in FragmentConfig#iframeHeaders.","message":"CSP headers must be configured per fragment via iframeHeaders; missing CSP can cause script execution failures.","severity":"gotcha","affected_versions":">=0.8.0"},{"fix":"Attach event listeners to the fragment element instead of document.body.","message":"Breaking: Event system virtualization changed in v0.6.0 – event listeners on body may not work as expected.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Use polyfills for custom elements and shadow DOM if needed.","message":"Note: Browser support requires modern APIs (custom elements, shadow DOM). Not compatible with older browsers.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Replace require with import: import { FragmentClient } from 'web-fragments/client'.","cause":"Using CommonJS require() to import the ESM-only subpath.","error":"Error: Cannot find module 'web-fragments/client'"},{"fix":"Use gateway.route(req, ctx) inside Cloudflare Workers fetch handler instead of 'on'.","cause":"FragmentGateway may not have an 'on' method; misshapen usage.","error":"TypeError: gateway.on is not a function"},{"fix":"Use a modern browser or add a shadow DOM polyfill.","cause":"Browser does not support shadow DOM. Web Fragments require shadow DOM for piercing.","error":"Uncaught TypeError: failed to execute 'attachShadow' on 'Element'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}