Documenting your web component with the custom element manifest file format.

A wonderful achievement has been performed by the web component community, that helps provide a "united" interop between web components - the custom element manifest. It allows the web component to be leveraged in all versions of React, can be used to auto generate documentation, and also helps browser extensions that assist with debugging web components.

Because the approach this library takes deviates a bit from other approaches, we've found it necessary to build our own library to generate such files.

Steps:

1. First, I agree with all the sound advice found here.

2. Since the custom element manifest is a json file, make sure to add the following to your package.json (or some variation to ensure it is included with the published artifacts):

  "files": [
    "*.js",
    "types.d.ts",
    "*.json"
  ],

3. The custom element manifest generator we use is keyed off of the typescript types file, in addition to the config object used to define the (JSON-serializable) features of the web component.

To link the two together, you will need to write a little bit of code in your project. Suggested name: doc.js:

import { analyze } from './node_modules/may-it-be/analyze.js';
import { resolve } from "path";
import {config} from './config.js';
import * as fs from 'fs';
const info = analyze(resolve("types.d.ts"), config);
const cem =  JSON.stringify(info.package, null, 2);
fs.writeFileSync('./custom-elements.json', cem, {encoding: 'utf-8'});

4. For this to work, the typings file must conform to some conventions (following the ruby on rails model of convention being easier than configuration):

Define one interface for where all the public properties are defined, including read only props that the end user would be expected to set dynamically via setters or through setting attributes, and give it the name "AllProps".

5. Add a script to package.json:

  "scripts": {
    ...
    "doc": "node doc.js"
  },

<= Mount based web components => Directed Scoped Specifiers