repository·main·Indexed 19 days ago
https://github.com/webcomponents/custom-elements-manifestA standardized JSON file format for describing the API of Custom Elements. It provides a schema for documenting modules, class declarations, attributes, events, slots, and CSS custom properties, enabling tooling support for IDEs, documentation generators, and linters. Version 2.1.0.
The manifest format uses a schemaVersion field at the top level to manage evolution. The schema follows semantic versioning (semver).
Note that the schemaVersion may differ from the npm package version of custom-elements-manifest itself. The current schema version is 2.1.0.
To allow tools to discover custom element manifests in npm packages without downloading the entire package tarball, add a "customElements" field to your package.json. This field should point to the path of your manifest file.
{
"name": "example-package",
"customElements": "custom-elements.json"
}To use the custom-elements-manifest schema and types in your project, install the package as a development dependency using npm.
npm i -D custom-elements-manifestA custom elements manifest file is a JSON document that describes the public API of a package, including custom elements and other JavaScript concepts like modules, classes, and functions. The top-level object must contain modules and schemaVersion.
{
"schemaVersion": "2.1.0",
"modules": [
{ "name": "my-module" }
],
"readme": "# My Package"
}extends clause, they are listed in the mixins array. Mixins must be listed in the order of their application to the superclass, starting with the innermost mixin first (e.g., "S with A, B" means A is applied, then B).A manifest describes modules, their declarations (classes, functions, etc.), exports, and the specific properties of custom elements like attributes, members, and events.
Below is an example of a manifest generated for a class MyElement that defines a custom element <my-element> with a disabled attribute and a fire method.
{
"schemaVersion": "2.1.0",
"readme": "README.md",
"modules": [
{
"kind": "javascript-module",
"path": "my-project/my-element.js",
"declarations": [
{
"kind": "class",
"customElement": true,
"name": "MyElement",
"tagName": "my-element",
"description": "This is the description of the class",
"members": [
{
"kind": "field",
"name": "disabled"
},
{
"kind": "method",
"name": "fire"
}
],
"events": [
{
"name": "disabled-changed",
"type": {
"text": "Event"
}
}
],
"attributes": [
{
"name": "disabled"
}
],
"superclass": {
"name": "HTMLElement"
}
}
],
"exports": [
{
"kind": "js",
"name": "MyElement",
"declaration": {
"name": "MyElement"
}
},
{
"kind": "custom-element-definition",
"name": "my-element",
"declaration": {
"name": "MyElement"
}
}
]
}
]
}You can require the JSON Schema for validation or import the TypeScript types to ensure type safety when working with manifest objects.
// Require the JSON Schema
const customElementManifestSchema = require('custom-elements-manifest');
// Import the TypeScript types
import * as schema from 'custom-elements-manifest/schema';A CustomElementExport represents the result of a customElements.define() call, making an element available globally. It requires a name (the tag name), a kind set to "custom-element-definition", and a declaration which is a reference to the implementing class.
{
"kind": "custom-element-definition",
"name": "my-element",
"declaration": { "name": "MyElementClass" }
}kind (set to "class") and a name. It can include a superclass, mixins, members (fields or methods), and documentation like summary and description.modules array contains JavaScriptModule objects. These represent the public entrypoints of a package. A module can export various JavaScript entities such as classes, functions, and variables.Within a class, you can define:
kind: "field". Supports static, readonly, private (via privacy), and default values.kind: "method". Supports static, private (via privacy), parameters, and a return object containing the return type and description.{
"kind": "field",
"name": "count",
"static": false,
"readonly": true
}
{
"kind": "method",
"name": "increment",
"parameters": [],
"return": { "type": { "type": "number" } }
}The Reference object is used to point to an export of a module.
name: The name of the symbol (required).package: The npm package name. Use "global:" for global symbols like HTMLElement or Event. If undefined, the reference is local to the package.module: The specific module within the package.