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 a customTags 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.