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
