The webcomponents-bundle.js contains all Web Components polyfills in a single file, providing the simplest integration option for applications that don't require loading optimization.
Complete polyfill bundle that loads all Web Components APIs immediately.
/**
* Include webcomponents-bundle.js as a script tag
* All polyfills load immediately, no feature detection performed
* Each polyfill activates only if needed based on browser support
*/
// <script src="webcomponents-bundle.js"></script>
// After bundle loads, all Web Components APIs are available
// WebComponentsReady event fires when initialization is completeUsage Examples:
<!-- Simple bundle usage -->
<script src="webcomponents-bundle.js"></script>
<script type="module" src="my-element.js"></script>
<my-element></my-element>
<!-- CDN usage -->
<script src="https://unpkg.com/@webcomponents/webcomponentsjs@^2/webcomponents-bundle.js"></script>
<script type="module" src="my-element.js"></script>The bundle contains all available polyfills but only activates those needed by the browser.
Core Web Components Polyfills:
window.customElements APIPlatform Polyfills (for IE 11 and older browsers):
Event, CustomEvent, MouseEvent constructorsUnlike the dynamic loader, the bundle loads all polyfill code but conditionally applies it.
/**
* Bundle loading sequence:
* 1. All polyfill code loads immediately
* 2. Each polyfill checks if native implementation exists
* 3. Polyfills only activate if native support is missing
* 4. WebComponentsReady event fires when complete
*/
// WebComponentsReady event
interface WebComponentsReadyEvent extends CustomEvent {
type: 'WebComponentsReady';
bubbles: true;
}Usage Examples:
// Wait for bundle initialization
document.addEventListener('WebComponentsReady', () => {
// All polyfills loaded and custom elements upgraded
console.log('Web Components ready!');
});
// Check readiness programmatically
if (window.WebComponents && window.WebComponents.ready) {
// Already ready
} else {
// Wait for ready event
document.addEventListener('WebComponentsReady', handler);
}webcomponents-bundle.js Benefits:
webcomponents-bundle.js Drawbacks:
When to Use Bundle:
When to Use Loader:
<!DOCTYPE html>
<html>
<head>
<!-- Load bundle in head -->
<script src="webcomponents-bundle.js"></script>
</head>
<body>
<!-- Custom elements available immediately -->
<script type="module" src="my-element.js"></script>
<my-element></my-element>
</body>
</html><!-- Bundle first -->
<script src="webcomponents-bundle.js"></script>
<!-- Then modules -->
<script type="module">
import './my-element.js';
// Use custom elements immediately
document.body.appendChild(document.createElement('my-element'));
</script>// React/Vue/Angular applications
// Include bundle via script tag or webpack
// In your component code:
import { LitElement, html } from 'lit';
class MyElement extends LitElement {
render() {
return html`<p>Custom element works!</p>`;
}
}
customElements.define('my-element', MyElement);Bundle Sizes (approximate):
Loading Performance:
Runtime Performance:
// Handle bundle loading errors
const script = document.createElement('script');
script.src = 'webcomponents-bundle.js';
script.addEventListener('load', () => {
console.log('Bundle loaded successfully');
});
script.addEventListener('error', () => {
console.error('Failed to load Web Components bundle');
// Fallback strategy here
});
document.head.appendChild(script);The bundle itself handles polyfill initialization errors internally and will log warnings for any issues encountered during polyfill activation.