Custom Element Analyzer
What is this?
A CLI tool that generates a custom-elements.json
file from JSDocs in js files that define vanilla custom elements.
This utility uses JSDoc
under the hood to do all the parsing to maintain 100% compatibility.
Custom Elements JSON is a work in progress format that describes custom elements. Learn more
Storybook Docs supports reading custom-element.json
files directly. Learn more
Usage
$ npx custom-element-analyzer path/to/analyze
Help is also available at
$ npx custom-element-analyzer -h
Options
Usage: custom-element-analyzer [options] <directory> Options: -d, --debug output extra debugging and output to console instead of file -o, --out <file-name> output file name. Defaults to custom-elements.json -h, --help output usage information -n, --no-cache disable jsdoc caching to force regenerating source jsdoc
Supported tags
Tag | Usage | Example |
---|---|---|
@element | Defines a custom element | @element my-element |
@fires | Describes an event | @fires {string} done - Fires a done event with a string argument |
@attr | Describes an attribute | @attr {string} color=red - An attribute named colorwith a default color of red. e.g. <my-element color='blue'> |
@props | Describes a property | @prop {string} name=Untitled - Name with a default value of Untitled |
@slot | Describes a custom element slot | @slot {title} - Slot named 'title' |
@cssprop | Describes a custom css property | @cssprop --bg-color=#fff - Background color with a default value |
Tags that are declared more than once will merge into the previous declaration filling in only what wasn't previously there.
Supported expressions
observedAttributes
Even without any comments and jsdoc tags, the following statement
static { ... return 'attr1' 'attr2'}
will be interpreted as this:
/** * @attribute attr1 * @attribute attr2 */ static { ... return 'attr1' 'attr2'}
Example file
/** * @fires another-event - Event that is fired in a global method * @fires done=value - updates done event with a default value */ {} /** * Here is a description of my web component with a really long description * that also has a line break and also some usage examples: * * `<my-element>blah blah blah</my-element>` * * @element my-element * * @fires * * @attr * @attr * either the "on" or "off" value and the comment has newlines * * @prop value * * @slot - This is an unnamed slot (the default slot) * @slot title - This is a slot named "title" * * @cssprop --bg-color=#fff - This element has a custom css property with a default value */ /** * @attr * @attr */ static { return 'switch' 'disabled' 'color' } { Object /** * @prop */ thisvalue = 'Initial value' /** * @attr - The current opacity */ thisopacity = 05 }
Will generate the following custom-elements.json
file
Contributing
- Fork this repo.
- Modify code on a branch of that repo.
- Generate a pull request.