liveBook · Manning

Custom elements manifest

As explained in Web Component Development with Modern Libraries and Tooling

A Custom Elements Manifest is a machine-readable text document describing web-component metadata such as attributes, properties, styling, and API documentation.

A Custom Elements Manifest (CEM) is a JSON file that describes the public API of a project’s web components. It records details such as tag names, attributes, properties, slots, CSS custom properties, and CSS parts. Tools can use the same file to provide documentation, demos, and editor assistance. section 10.0 section 10.5

A greeting component

For a hello-world element, JSDoc can describe its color and name attributes, matching properties, slots, --border-color styling option, and greeting CSS part. The generated manifest puts those details into structured JSON rather than leaving each tool to interpret the component separately. section 10.2

Listing 10.5 HelloWorld JSDoc
/**
 * This displays a greeting message for a given name in a specified color.
 * @summary This displays a greeting message.
 * @tag hello-world
 * @attr {string} color - initial text color
 * @attr {string} name - initial name to greet
 * @prop {string} [color=black] - current text color
 * @prop {string} [name=World] - current name to greet
 * @slot - for content after the greeting
 * @slot before - for content before the greeting
 * @cssprop [--border-color=gray] color of border that surrounds the component
 * @part greeting - greeting message
 */

The component’s JSDoc shows how a tag name, attributes, properties, slots, and styling hooks are documented before manifest generation. section 10.2

To create and keep a manifest useful:

  • Install @custom-elements-manifest/analyzer, run cem analyze, and point package.json’s customElements field at the generated custom-elements.json file. section 10.1
  • Regenerate the file when a component API changes; the watch script regenerates it as source files are saved. Configure globs, exclusions, or library plugins when the project needs them. section 10.1
  • Add JSDoc descriptions where source analysis alone cannot supply them. Even when a library exposes attributes and properties to the analyzer, @attr and @prop provide their descriptions. section 10.2

In VS Code, the Web Components Language Server reads custom-elements.json from the project root to offer hover help and completions for element names and attributes. Reload the editor window after generating or changing the file. Other consumers include Storybook, API Viewer Element, and Markdown documentation tooling. Generating the JSON is preferable to maintaining it by hand, which is tedious and error prone. section 10.5 section 10.0

How Web Component Development with Modern Libraries and Tooling covers it

How deep it goes
Works through generation, JSDoc annotations, generated JSON structure, and editor setup rather than asking readers to author manifests manually.
Examples
Uses a greeting component’s JSDoc and generated JSON, plus VS Code hover help and completions.
What it assumes
Assumes web-component source files while spelling out the JSDoc tags used to describe their APIs.
What you can do after
Apply it via @custom-elements-manifest/analyzer to generate and maintain metadata for documentation and editor tools.
How it connects
Connects custom elements with JSDoc, API documentation, Storybook, and IntelliSense.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Web Component Development with Modern Libraries and Tooling. The section links point to the parts of the book it draws on.