Building Web Components is something I enjoy, and it is really easy to create one using LitElement. However, the ecosystem around LitElement is not quite mature yet, and sometimes we don't have a replacement for certain important tools we used to have while developing with Polymer.
Documenting is one such missing piece. While we can use Storybook with a preset by open-wc.org for showcasing different states of our components, there is a thing that we are lacking: a simple tool to browse the API docs. This is exactly what the component I'm sharing today is intended to be.
What?
Meet the <api-viewer> element! It is built with LitElement and TypeScript. Check out the live demo to see what kind of documentation it provides.
Note, this is just 0.1.0 release and I have a lot of ideas on how to improve the API viewer. Also, the idea behind this component is that we might use it for Vaadin components in the future, so there might be some "internal" feature requests over time, but the community feedback is always welcome.
Why?
While we can still use polymer-analyzer tool and <iron-component-page> component by the Polymer team with LitElement and document properties, methods and events, it starts getting complicated if we switch to TypeScript. Also, these components and tools are no longer actively updated.
Thankfully, there is a web-component-analyzer, a CLI tool by Rune Mehlsen. It provides the ability to extract properties, attributes, methods, events, slots and custom CSS properties of the custom elements and outputs analysis as markdown or JSON (including the format proposed by VSCode team).
I was looking for a web component compatible with the Analyzer, and I found <wc-info> by Bruce B. Anderson. While I like the general idea, the component is still not exactly what I needed. So I decided to go ahead and build the <api-viewer> from scratch, and in a few days I built an MVP.
How?
Here is a minimal usage example which you can run using es-dev-server:
<!DOCTYPE html>
<html>
<head>
<script type="module">
import 'api-viewer-element';
</script>
</head>
<body>
<api-viewer src="./custom-elements.json"></api-viewer>
</body>
</html>
Follow the full usage instructions to learn how to generate the JSON file. The Web Component Analyzer documentation is also worth checking.
And of course, let me know if you have any comments, feature requests or any other feedback regarding <api-viewer>. Let's make it better together!
Top comments (0)