Web Component Runtime

Web Component Runtime is the shared engine that makes web component libraries work in Drupal. Install it once, and every library on your site loads correctly and plays well with the others.

A web component is a reusable piece of interface, like a button, a dialog, or a date picker, that works in any web page regardless of the framework used to build the rest of the site. Modules like Cordwainer Elements bring whole libraries of them into Drupal as Single Directory Components (SDCs). Those components need some shared plumbing at page load: something to tell the browser where each library's JavaScript lives, to load elements when they appear, and to place content into the right part of each component. Web Component Runtime provides that plumbing once, for every library on the site, so libraries don't each ship their own copy and collide.

Most site builders never install this module directly. It arrives automatically as a dependency of the component library modules and themes that need it.

This project is in early development. Follow the issue queue for progress.

Features

• One shared import map. Combines the JavaScript import entries from every registered library into a single import map, placed early in the page head where browsers require it. Each library's dependencies are scoped, so two libraries can use different versions of the same package without conflict. Supports CSP nonces and Drupal's asset cache busting.
• Named slot support in Twig. The slot_name filter places content into a component's named slots, such as a card's header or footer: {{ header|slot_name('header') }}. The has_slot_content test skips slots that render empty, so a component's fallback content still shows.
• Correct attribute rendering. A helper renders boolean props as present or absent (never disabled="false", which browsers treat as disabled) and encodes object and array props as JSON.
• Lazy element loading. Loads each element's code the first time its tag appears on the page, including content added later by AJAX, BigPipe, or a page builder.
• Library registry. Each library declares itself in a small, schema-versioned *.web_component_runtime.yml file: tag prefix, version, import entries, asset path, and component categories. No PHP is needed in library modules or themes.
• Asset and styling helpers. Sets each library's asset base path and adds rules that prevent unstyled flashes while elements load.
• Conflict detection. Reports duplicate tag names and clashing import entries between libraries on the status report, before they break pages.
• Works with or without Drupal Canvas. Nothing in the core module requires Canvas. The included Web Component Runtime Canvas submodule adds Canvas support: it hands import entries to Canvas so pages get one import map, and upgrades components live in the Canvas preview.
• Works for themes, too. Themes can't register Twig filters or page attachments themselves. A theme that ships web component SDCs declares this module as a dependency and gets every feature above.

Use this module when you

• Use a web component library module such as Cordwainer Elements (it will be installed for you).
• Want more than one web component library on the same site.
• Build a theme or module that wraps web components as SDCs and need slots, loading, and import maps handled for you.

Post-Installation

There is no configuration page. Once enabled, the module discovers every installed module and theme that ships a *.web_component_runtime.yml file and handles the rest automatically.

To confirm what it found, visit Reports > Status report (/admin/reports/status). It lists each registered library and flags any tag or import conflicts.

Themes: Drupal won't install a theme until the modules it depends on are already enabled, and it won't enable them for you. If a theme depends on Web Component Runtime, enable this module first.

Library authors: add a registry file to your module or theme, and declare web_component_runtime as a dependency in both .info.yml and composer.json. A minimal registry file:

my_library:
  schema: 1
  label: My Library
  version: 2.1.0
  prefix: my-
  base_path: vendor/my-library/dist
  loader: autoload
  scope: vendor/my-library/
  imports:
    lit: vendor/lit/index.js

Modules and themes generated by the Custom Elements Manifest to SDC Generator include this file and both dependency declarations automatically.

Additional Requirements

Drupal core ^11. No other contributed modules are required.

Visitors need a modern, evergreen browser that supports custom elements, ES modules, and import maps.

Recommended modules/libraries

• Cordwainer Elements provides 80+ ready-to-use web components as SDCs, built on this runtime.
• Custom Elements Manifest to SDC Generator generates a complete, runtime-ready module or theme from any web component library's Custom Elements Manifest.
• Drupal Canvas, together with the included Web Component Runtime Canvas submodule, lets editors place web components visually.

Similar projects

• Drupal Canvas builds its own import map for Canvas code components and lets other modules alter it. That map only exists where Canvas is installed. Web Component Runtime works on any site and hands its entries to Canvas when Canvas is present, so pages never get two import maps.
• Importmaps and Importmap provide general-purpose import map registration. Web Component Runtime is focused on web component libraries and adds slot handling, element loading, a library registry, and conflict detection on top.
• Drupal core is working on a native import map API in #3398525: Add an API for importmaps. When it lands, this module will register its entries through the core API instead of printing its own map. Library modules won't need to change.
• Library-specific integrations, such as the Web Awesome Components sandbox, bundle their runtime into a single library's module and require Canvas. Web Component Runtime is library-agnostic and shared, so several libraries can coexist on one site.

Supporting this Module

No funding links yet.

Community Documentation

This project is brand new. Documentation, a demo, and a live roadmap will be linked here as development progresses.