WC Toolkit Custom JSDoc Tags Plugin

This is a plugin maps custom JSDoc tags on your component classes to properties in Custom Elements Manifest using the Custom Element Manifest Analyzer.

Installation

npm i -D @wc-toolkit/jsdoc-tags

Usage

Add the information you would like to include with you component in the class's JSDoc comment using custom tags. In this example, the @dependency, @since, @status, and @spec tags are all custom.

// my-component.js

/**
 *
 * My custom element does some amazing things
 *
 * @tag my-element
 *
 * @dependency icon
 * @dependency button
 *
 * @since 1.2.5
 * 
 * @status beta - not ready for production
 * 
 * @spec https://www.figma.com/...
 *
 */
export class MyElement extends HTMLElement {
  ...
}

In the CEM analyzer config, import the plugin and add the mappings for the new tags.

// custom-elements-manifest.config.mjs

import { jsDocTagsPlugin } from "@wc-toolkit/jsdoc-tags";

export default {
  ...
  /** Provide custom plugins */
  plugins: [
    jsDocTagsPlugin({
      tags: {
        // finds the values for the `@since` tag
        since: {},
        // finds the values for the `@status` tag
        status: {},
        // finds the values for the `@spec` tag
        spec: {},
        // finds the values for the `@dependency` tag
        dependency: {
          // maps the values to the `dependencies` property in the CEM
          mappedName: 'dependencies',
          // ensures the values are always in an array (even if there is only 1)
          isArray: true,
        },
      }
    }),
  ],
};

Property-level Custom Tags

You can also add custom JSDoc tags to class properties. These will be extracted and included in the Custom Elements Manifest under the member's field for each property.

Example

export class MyComponent extends HTMLElement {
  /**
   * The greeting to display
   * @myCustomTag important
   */
  greeting = "Hello, World!";
}

Configuration

Add your custom property tag to the plugin config:

jsDocTagsPlugin({
  tags: {
    myCustomTag: {
      description: "A custom property tag",
      mappedName: "myCustomTag"
    }
  }
})

Result in custom-elements.json

{
  "kind": "field",
  "name": "greeting",
  "type": { "text": "string" },
  "myCustomTag": "important"
}

This allows you to document and extract custom metadata for properties in a structured way.

Result

The data should now be included in the Custom Elements Manifest.

// custom-elements.json

{
  "kind": "class",
  "description": "My custom element does some amazing things",
  "name": "MyElement",
  "tagName": "my-element",
  "since": {
    "name": "1.2.5",
    "description": ""
  },
  "status": {
    "name": "beta",
    "description": "not ready for production"
  },
  "spec": {
    "name": "https://www.figma.com/...",
    "description": ""
  },
  "dependencies": [
    {
      "name": "icon",
      "description": ""
    },
    {
      "name": "button",
      "description": ""
    }
  ],
  "customTags": {
    "myCustomTag": "important"
  }
}

Be sure to check out the official docs for more information on how to use this.