🧱 Chapter 81: Web Components Architecture

Publishing Web Components to NPM

Distributing production-grade Web Components: Custom Elements Manifest (`custom-elements.json`), modern ESM packaging, TypeScript definitions, and IDE autocomplete.

LEARNING OBJECTIVES ⌵

Structure a production-grade Web Component package configured for NPM distribution.
Generate and validate the standardized Custom Elements Manifest (custom-elements.json) using @custom-elements-manifest/analyzer.
Configure package.json with standard exports maps, "customElements", and TypeScript types fields.
Enable automated IDE autocomplete (VS Code / WebStorm) and Storybook documentation directly from source code annotations.

🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation

🌐

1. Input

Directives & Tags

⚙️

2. Parse

Tokenizer & AST

🌳

3. Layout

Box Model & Flow

🎨

4. Render

GPU Paint & Composite

PHASE 1: INPUT & DIRECTIVES

Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

Imagine a specialized semiconductor manufacturer manufacturing high-precision microcontrollers.

When they ship thousands of microcontrollers to circuit board designers, they don't just dump a bag of raw black silicon chips on the loading dock. They include an authoritative Standard Datasheet (Pinout Diagram) detailing:

Exact pin voltages (Properties & Attributes)
Output signal frequencies (Custom Events)
Mounting dimensions and socket connectors (Slots & Parts)

+-------------------------------------------------------------------------------+
|                       THE UNIVERSAL COMPONENT DATASHEET                       |
+-------------------------------------------------------------------------------+
| SOURCE CODE WITH JSDOC ANNOTATIONS:                                           |
|   /**                                                                         |
|    * @tag ui-button                                                           |
|    * @attr {string} variant - Visual style variant                            |
|    * @fires {CustomEvent} ui-click - Dispatched when button activates        |
|    * @cssprop --btn-bg - Background color token                               |
|    */                                                                         |
|                                       |                                       |
|                                       v                                       |
|                      [@custom-elements-manifest/analyzer]                     |
|                                       |                                       |
|                                       v                                       |
|               STANDARDIZED `custom-elements.json` MANIFEST                    |
|                                       |                                       |
|         +-----------------------------+-----------------------------+         |
|         |                             |                             |         |
|         v                             v                             v         |
|   VS Code IntelliSense     Storybook Automated Docs      React / Angular Wrappers
+-------------------------------------------------------------------------------+

The Custom Elements Manifest (CEM) is the official open W3C Community Group standard datasheet for Web Components. When you publish a component accompanied by custom-elements.json, IDEs, documentation engines, and framework compilers instantly understand how to provide autocomplete, type checking, and visual playgrounds.

Technical Deep Dive & Specifications

The Custom Elements Manifest (`custom-elements.json`)

The Custom Elements Manifest is a standardized JSON format describing all custom elements in a package:

{
  "schemaVersion": "1.0.0",
  "readme": "",
  "modules": [
    {
      "kind": "javascript-module",
      "path": "src/components/metric-card.js",
      "declarations": [
        {
          "kind": "class",
          "name": "MetricCard",
          "tagName": "metric-card",
          "description": "Displays an enterprise analytical metric card with trend indicators.",
          "attributes": [
            {
              "name": "value",
              "type": { "text": "string" },
              "description": "The numeric metric value to display."
            },
            {
              "name": "trend",
              "type": { "text": "'up' | 'down' | 'neutral'" },
              "default": "'neutral'",
              "description": "The directional trajectory of the metric."
            }
          ],
          "events": [
            {
              "name": "metric-refresh",
              "type": { "text": "CustomEvent<void>" },
              "description": "Fires when user clicks the refresh icon."
            }
          ],
          "slots": [
            {
              "name": "",
              "description": "Default slot for sub-metric descriptive text."
            }
          ],
          "cssParts": [
            {
              "name": "container",
              "description": "The main card wrapper div."
            }
          ],
          "cssProperties": [
            {
              "name": "--metric-accent",
              "description": "Accent border and highlight color.",
              "default": "#3b82f6"
            }
          ]
        }
      ]
    }
  ]
}

Modern `package.json` Distribution Architecture

A modern Web Component library should deliver pure ES Modules (ESM) and register its manifest so the ecosystem can discover it:

{
  "name": "@acme/design-system",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.js",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "customElements": "custom-elements.json",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    },
    "./button": {
      "types": "./dist/components/button/button.d.ts",
      "import": "./dist/components/button/button.js"
    },
    "./card": {
      "types": "./dist/components/card/card.d.ts",
      "import": "./dist/components/card/card.js"
    },
    "./custom-elements.json": "./custom-elements.json"
  },
  "files": [
    "dist",
    "custom-elements.json"
  ],
  "scripts": {
    "build": "tsc && cem analyze --litelement",
    "analyze": "cem analyze --litelement"
  },
  "peerDependencies": {
    "lit": "^3.0.0"
  },
  "devDependencies": {
    "@custom-elements-manifest/analyzer": "^0.9.0",
    "typescript": "^5.3.0"
  }
}

💻 Interactive Code Playground

Here is a fully documented, production-grade custom element (<metric-card>) annotated with standard JSDoc tags ready for @custom-elements-manifest/analyzer extraction.

Starter Code

Line-by-Line Code Breakdown

Lines 44–58: Standard JSDoc annotations. The CEM analyzer parses @tag, @attr, @slot, @csspart, @cssprop, and @fires to build the machine-readable custom-elements.json.
Line 60: export class MetricCard extends HTMLElement: Standard ES module class export for npm bundling.
Line 72: refresh-requested custom event is documented in the JSDoc header and dispatched with { bubbles: true, composed: true }.
Line 99: border-left: 4px solid var(--metric-accent, #3b82f6): Provides token customizability, documented in @cssprop.

Expected Browser Render Output

Two polished analytical metric cards display:

Monthly Recurring Revenue: Green up arrow ▲ +14.2% and Blue accent bar.
API Error Rate: Red down arrow ▼ -0.02% with customized Emerald accent bar via --metric-accent: #10b981.

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL playground.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Documented NPM Component: Metric Card</title>
  <style>
    body {
      font-family: system-ui, -apple-system, sans-serif;
      background: #090d16;
      color: #f8fafc;
      padding: 3rem;
      display: flex;
      flex-direction: column;
      align-items: center;
      gap: 2rem;
    }
  </style>
</head>
<body>

<h1>Production NPM Component: <code>&lt;metric-card&gt;</code></h1>

<div style="display: flex; gap: 2rem; flex-wrap: wrap;">
    <metric-card 
      label="Monthly Recurring Revenue" 
      value="$124,500" 
      trend="up" 
      trend-value="+14.2%">
      Compared to $109,000 last month.
    </metric-card>

<metric-card 
      label="API Error Rate" 
      value="0.04%" 
      trend="down" 
      trend-value="-0.02%"
      style="--metric-accent: #10b981;">
      Target threshold is &lt; 0.10%.
    </metric-card>
  </div>

constructor() {
        super();
        this.attachShadow({ mode: 'open' });
      }

connectedCallback() {
        this.render();
        this.shadowRoot.addEventListener('click', () => {
          this.dispatchEvent(new CustomEvent('refresh-requested', {
            bubbles: true,
            composed: true,
            detail: { label: this.getAttribute('label') }
          }));
        });
      }

attributeChangedCallback(name, oldValue, newValue) {
        if (oldValue !== newValue) {
          this.render();
        }
      }

render() {
        const label = this.getAttribute('label') || 'Metric';
        const value = this.getAttribute('value') || '$0';
        const trend = this.getAttribute('trend') || 'neutral';
        const trendValue = this.getAttribute('trend-value') || '';

const trendIcons = { up: '▲', down: '▼', neutral: '●' };
        const trendColors = { up: '#22c55e', down: '#ef4444', neutral: '#94a3b8' };

this.shadowRoot.innerHTML = `
          <style>
            :host {
              display: block;
              width: 280px;
              font-family: inherit;
            }
            .card {
              background: var(--metric-bg, #1e293b);
              border: 1px solid #334155;
              border-left: 4px solid var(--metric-accent, #3b82f6);
              border-radius: 10px;
              padding: 1.5rem;
              box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.3);
              cursor: pointer;
              transition: transform 0.15s ease;
            }
            .card:hover {
              transform: translateY(-2px);
            }
            .label {
              font-size: 0.85rem;
              font-weight: 600;
              color: #94a3b8;
              text-transform: uppercase;
              letter-spacing: 0.05em;
            }
            .value {
              font-size: 2rem;
              font-weight: 800;
              color: #ffffff;
              margin: 0.5rem 0;
            }
            .trend-row {
              display: flex;
              align-items: center;
              gap: 0.4rem;
              font-size: 0.85rem;
              font-weight: 700;
              color: ${trendColors[trend] || trendColors.neutral};
            }
            .details {
              margin-top: 0.75rem;
              font-size: 0.8rem;
              color: #64748b;
            }
          </style>

<div class="card" part="card">
            <div class="label">${label}</div>
            <div class="value" part="value">${value}</div>
            <div class="trend-row">
              <span>${trendIcons[trend] || ''}</span>
              <span>${trendValue}</span>
            </div>
            <div class="details">
              <slot></slot>
            </div>
          </div>
        `;
      }
    }

customElements.define('metric-card', MetricCard);

document.addEventListener('refresh-requested', (e) => {
      console.log('Refresh requested for:', e.detail.label);
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

🏋️ Hands-On Exercise

🎯 The Challenge: Package & Document `<color-swatch>`

Build a documented <color-swatch> component with complete JSDoc annotations and write the corresponding custom-elements.json JSON block.

Instructions:

Implement class ColorSwatch with attributes: hex (color string) and name (label).
Document @tag, @attr, @fires color-selected, and @csspart swatch-box.
When clicked, copy the hex code to clipboard (navigator.clipboard.writeText) and dispatch CustomEvent('color-selected', { detail: { hex, name } }).
Provide the exact JSON declaration node that @custom-elements-manifest/analyzer will generate.

🏁 Starter Code Sandbox

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

STARTER CODE SANDBOX exercise.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Solution: Color Swatch Package</title>
  <style>
    body {
      font-family: system-ui, sans-serif;
      background: #0f172a;
      color: #f8fafc;
      padding: 3rem;
      display: flex;
      flex-direction: column;
      align-items: center;
    }
  </style>
</head>
<body>

  <h2>Brand Color Palette</h2>

  <div style="display: flex; gap: 1.5rem; margin-top: 1rem;">
    <color-swatch hex="#3b82f6" name="Brand Blue"></color-swatch>
    <color-swatch hex="#10b981" name="Emerald Green"></color-swatch>
    <color-swatch hex="#f43f5e" name="Rose Red"></color-swatch>
  </div>

  <p id="toast" style="margin-top: 2rem; color: #38bdf8; font-weight: 600; min-height: 24px;"></p>

  <script type="module">
    /**
     * @summary Displays an interactive color swatch pill that copies color values on click.
     * @tag color-swatch
     * 
     * @attr {string} hex - The hex color code (e.g. #3b82f6).
     * @attr {string} name - The human-readable color title.
     * 
     * @csspart swatch-box - The interactive swatch container.
     * @csspart preview - The circular color preview circle.
     * 
     * @fires {CustomEvent} color-selected - Dispatched with { hex, name } on click.
     */
    export class ColorSwatch extends HTMLElement {
      static get observedAttributes() {
        return ['hex', 'name'];
      }

      constructor() {
        super();
        this.attachShadow({ mode: 'open' });
      }

      connectedCallback() {
        this.render();
        this.shadowRoot.addEventListener('click', () => {
          const hex = this.getAttribute('hex') || '#000000';
          const name = this.getAttribute('name') || 'Color';

          if (navigator.clipboard) {
            navigator.clipboard.writeText(hex).catch(() => {});
          }

          this.dispatchEvent(new CustomEvent('color-selected', {
            bubbles: true,
            composed: true,
            detail: { hex, name }
          }));
        });
      }

      render() {
        const hex = this.getAttribute('hex') || '#3b82f6';
        const name = this.getAttribute('name') || 'Color';

        this.shadowRoot.innerHTML = `
          <style>
            :host { display: inline-block; font-family: inherit; }
            .swatch {
              display: flex;
              align-items: center;
              gap: 0.75rem;
              background: #1e293b;
              border: 1px solid #334155;
              padding: 0.5rem 0.85rem;
              border-radius: 8px;
              cursor: pointer;
              user-select: none;
              transition: all 0.15s ease;
            }
            .swatch:hover {
              transform: translateY(-2px);
              border-color: #475569;
            }
            .circle {
              width: 20px;
              height: 20px;
              border-radius: 50%;
              background-color: ${hex};
              box-shadow: 0 0 0 2px rgba(255, 255, 255, 0.1);
            }
            .info { display: flex; flex-direction: column; }
            .name { font-size: 0.85rem; font-weight: 600; color: #f8fafc; }
            .hex { font-size: 0.75rem; color: #94a3b8; font-family: monospace; }
          </style>

          <div class="swatch" part="swatch-box">
            <div class="circle" part="preview"></div>
            <div class="info">
              <span class="name">${name}</span>
              <span class="hex">${hex}</span>
            </div>
          </div>
        `;
      }
    }

    customElements.define('color-swatch', ColorSwatch);

    const toast = document.getElementById('toast');
    document.addEventListener('color-selected', (e) => {
      toast.textContent = `📋 Copied ${e.detail.name} (${e.detail.hex}) to clipboard!`;
    });
  </script>
</body>
</html>

Why this works:

JSDoc annotations provide a single source of truth for both developers and automated static analyzers.
The generated manifest allows IDEs to provide autocomplete directly in HTML and JSX templates when importing @acme/design-system.

⚠️ Common Pitfalls

Bundling Peer Dependencies into the NPM Bundle: If your component uses Lit and you bundle Lit inside dist/index.js, downstream applications that also use Lit will load two separate copies of the Lit runtime, bloating bundles and breaking instanceof checks. Always declare "lit" in "peerDependencies" or "dependencies", never bundle it as an inlined dependency.
Missing "customElements" in package.json: Forgetting to add "customElements": "custom-elements.json" in your package.json root prevents tools like Storybook, VS Code Custom Data, and WebStorm from auto-discovering your component manifest.

💡 Pro Tips

Subpath Exports for Granular Tree-Shaking: Configure exports in package.json so consumers can import individual elements without loading the whole suite:
```
import '@acme/ui/button.js'; // Imports only 2 KB button code
```
VS Code HTML Custom Data Generation: Use @custom-elements-manifest/to-vscode to generate a vscode-html-custom-data.json file. Adding this to your repository gives all VS Code users rich attribute suggestions and documentation tooltips when authoring HTML.

📌 Key Takeaways

The Custom Elements Manifest (custom-elements.json) is the standardized W3C JSON schema describing custom elements, properties, slots, events, and CSS tokens.
Use @custom-elements-manifest/analyzer to extract documentation automatically from JSDoc and TypeScript source code.
Always declare "customElements": "custom-elements.json" in package.json.
Configure fine-grained subpath exports in package.json to enable optimal consumer tree-shaking.
Declare shared libraries (e.g. Lit) as peerDependencies or external modules to avoid duplicate runtime bundling.
--

⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE

? Question 1 / 3

What is the purpose of the `custom-elements.json` manifest file?

Topic: HTML Fundamentals

? Question 2 / 3

Why is it an anti-pattern to bundle and inline `lit` inside your published NPM package distribution files?

Topic: HTML Fundamentals

? Question 3 / 3

Which `package.json` property allows modern bundlers to discover the Custom Elements Manifest automatically?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

The Custom Elements Manifest (custom-elements.json)

Modern package.json Distribution Architecture

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Package & Document <color-swatch>

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

What is the purpose of the custom-elements.json manifest file?

Why is it an anti-pattern to bundle and inline lit inside your published NPM package distribution files?

Which package.json property allows modern bundlers to discover the Custom Elements Manifest automatically?

The Custom Elements Manifest (`custom-elements.json`)

Modern `package.json` Distribution Architecture

🎯 The Challenge: Package & Document `<color-swatch>`

What is the purpose of the `custom-elements.json` manifest file?

Why is it an anti-pattern to bundle and inline `lit` inside your published NPM package distribution files?

Which `package.json` property allows modern bundlers to discover the Custom Elements Manifest automatically?