{"id":14990078,"url":"https://github.com/webcomponents/custom-elements-manifest","last_synced_at":"2025-04-13T02:02:55.487Z","repository":{"id":40678221,"uuid":"217740117","full_name":"webcomponents/custom-elements-manifest","owner":"webcomponents","description":"A file format for describing custom elements","archived":false,"fork":false,"pushed_at":"2024-10-02T15:58:14.000Z","size":78,"stargazers_count":391,"open_issues_count":46,"forks_count":26,"subscribers_count":38,"default_branch":"main","last_synced_at":"2025-04-02T07:03:56.852Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webcomponents.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-26T16:50:21.000Z","updated_at":"2025-03-31T21:04:17.000Z","dependencies_parsed_at":"2024-06-18T12:41:17.824Z","dependency_job_id":"32358e72-b28f-4be7-8ddd-cbe9e4971369","html_url":"https://github.com/webcomponents/custom-elements-manifest","commit_stats":{"total_commits":50,"total_committers":10,"mean_commits":5.0,"dds":0.54,"last_synced_commit":"676c48383af76dcb4f60f0d5b700e8affef454a1"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webcomponents%2Fcustom-elements-manifest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webcomponents%2Fcustom-elements-manifest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webcomponents%2Fcustom-elements-manifest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webcomponents%2Fcustom-elements-manifest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webcomponents","download_url":"https://codeload.github.com/webcomponents/custom-elements-manifest/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248654045,"owners_count":21140235,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T14:19:25.717Z","updated_at":"2025-04-13T02:02:55.441Z","avatar_url":"https://github.com/webcomponents.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# custom-elements-manifest\nA file format for describing custom elements.\n\nThe schema is published as a [JSON Schema](https://json-schema.org/) file, in `schema.json`. The schema is written in TypeScript (see [schema.d.ts](https://github.com/webcomponents/custom-elements-manifest/blob/master/schema.d.ts)) and then compiled to JSON Schema.\n\n# Usage\n\nInstall:\n\n```sh\nnpm i -D custom-elements-manifest\n```\n\nRequire the JSON Schema:\n\n```ts\nconst customElementManifestSchema = require('custom-elements-manifest');\n```\n\nImport the TypeScript types:\n\n```ts\nimport * as schema from 'custom-elements-manifest/schema';\n```\n\n## Referencing manifests from npm packages\n\nIn order to allow tools to find npm packages with custom element manifests without having to download package tarballs, packages should have a `\"customElements\"` field in their `package.json` that points to the manifest:\n\n```json\n{\n  \"name\": \"example-package\",\n  \"customElements\": \"custom-elements.json\",\n}\n```\n\n## Schema Versioning\n\nThe schema has a `schemaVersion` field in the top-level object to facilitate\nevolution of the schema. The schema follows [semver](https://semver.org/) versioning, the current schema version is `2.1.0`.\n\nThis version may not always match the npm package version, as some changes to the npm package might not have changes to the schema.\n\n| Schema Version | Date       | npm Version | git Tag |\n| -------------- | ---------- | ----------- | ------- |\n| 2.1.0          | 2024-05-06 | 2.1.0       | v2.1.0  |\n| 2.0.0          | 2022-09-13 | 2.0.0       | v2.0.0  |\n\n## Example\n\nGiven the following source code in directory `my-project`:\n\n`my-project/my-element.js`:\n```js\n/**\n * This is the description of the class\n */\nexport class MyElement extends HTMLElement {\n  static get observedAttributes() {\n    return ['disabled'];\n  }\n\n  set disabled(val) {\n    this.__disabled = val;\n  }\n  get disabled() {\n    return this.__disabled;\n  }\n\n  fire() {\n    this.dispatchEvent(new Event('disabled-changed'));\n  }\n}\n\ncustomElements.define('my-element', MyElement);\n```\n\nThe manifest would look like:\n\n`my-project/custom-elements.json`:\n```json\n{\n  \"schemaVersion\": \"2.1.0\",\n  \"readme\": \"README.md\",\n  \"modules\": [\n    {\n      \"kind\": \"javascript-module\",\n      \"path\": \"my-project/my-element.js\",\n      \"declarations\": [\n        {\n          \"kind\": \"class\",\n          \"customElement\": true,\n          \"name\": \"MyElement\",\n          \"tagName\": \"my-element\",\n          \"description\": \"This is the description of the class\",\n          \"members\": [\n            {\n              \"kind\": \"field\",\n              \"name\": \"disabled\"\n            },\n            {\n              \"kind\": \"method\",\n              \"name\": \"fire\"\n            }\n          ],\n          \"events\": [\n            {\n              \"name\": \"disabled-changed\",\n              \"type\": {\n                \"text\": \"Event\"\n              }\n            }\n          ],\n          \"attributes\": [\n            {\n              \"name\": \"disabled\"\n            }\n          ],\n          \"superclass\": {\n            \"name\": \"HTMLElement\"\n          }\n        }\n      ],\n      \"exports\": [\n        {\n          \"kind\": \"js\",\n          \"name\": \"MyElement\",\n          \"declaration\": {\n            \"name\": \"MyElement\"\n          }\n        },\n        {\n          \"kind\": \"custom-element-definition\",\n          \"name\": \"my-element\",\n          \"declaration\": {\n            \"name\": \"MyElement\"\n          }\n        }\n      ]\n    }\n  ]\n}\n```\n\n# Motivation\n\nMany tools need some machine-readable descriptions of custom elements: IDEs, documentation viewers, linters, graphical design tools, etc.\n\nThere have been several efforts in this area, including:\n- [Polymer Analyzer](https://github.com/Polymer/tools/tree/master/packages/analyzer)'s `analysis.json` file\n- [VS Code Custom Data format](https://github.com/microsoft/vscode-custom-data/tree/master/samples/webcomponents)\n- https://github.com/JetBrains/web-types\n\nThis repository is an effort to bring together tool owners to standardize on a common specification for a description format.\n\n# Use Cases\n\n## Editor Support\n\nDevelopers using custom elements should be able to get full-featured IDE support including auto-completion, hover-documentation, unknown symbol warnings, etc. These features should be available in HTML files, and in various template syntaxes via template-specific tools.\n\n## Documentation and demos\n\nDocumentation viewers should be able to display all the relevant information about a custom element, such as its tag name, attributes, properties, definition module, CSS variables and parts, etc.\n\nUsing a custom-elements manifest, it would be easy to generate or display demos for your component using tools such as [api-viewer-element](https://github.com/web-padawan/api-viewer-element), or automatically generate [Storybook](https://storybook.js.org/) knobs for your components.\n\n## Linting\n\nLinters should be able to produce warnings based on custom element defintions, such as warning if unknown elements are used in HTML templates.\n\n## Framework Integration\n\nReact currently is the only major framework where [custom elements require some special handling](https://custom-elements-everywhere.com/). React will pass all data to a custom element in the form of HTML attributes, and cannot listen for DOM events coming from Custom Elements without the use of a workaround.\n\nThe solution for this is to create a wrapper React component that handles these things. Using a custom elements manifest, creation of these wrapper components could be automated.\n\nSome component libraries like [Fast](https://www.fast.design/docs/integrations/react) or [Shoelace](https://shoelace.style/getting-started/usage?id=react) provide specific instructions on how to integrate with certain frameworks. Automating this integration layer could make development easier for both authors of component libraries, but also for consumers of libraries.\n\n## Cataloging\n\nA major use-case of custom elements manifests is that they allow us to reliably detect NPM packages that for certain contain custom elements. These packages could be stored, and displayed on a custom elements catalog, effectively a potential reboot of [webcomponents.org](https://www.webcomponents.org/). This catalog would be able to show rich demos and documentation of the custom elements contained in a package, by importing its components from a CDN like [unpkg](https://unpkg.com/), and its custom elements manifest.\n\n## Testing\n\nTooling would be able to detect whether or not the public API of a custom element has changed, based on a snapshot of the current custom elements manifest file to decide the impact of an update, and potentially prevent breaking API change in patch versions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebcomponents%2Fcustom-elements-manifest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebcomponents%2Fcustom-elements-manifest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebcomponents%2Fcustom-elements-manifest/lists"}