[api-extractor] Defining and using custom release tags

[pankhur94]

Summary

As part of the iTwin.js team, we’ve been exploring ways to define and use custom "modifier" tags in our project using API Extractor. Currently, we’ve defined a custom tag (@stable) using the established approach of configuring tsdoc.json as follows:

{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
  "extends": ["@microsoft/api-extractor/extends/tsdoc-base.json"],
  "tagDefinitions": [
    {
      "tagName": "@stable",
      "syntaxKind": "modifier",
      "allowMultiple": false
    }
  ],
  "supportForTags": {
    "@stable": true
  }
}

This configuration ensures that API Extractor recognizes the @stable tag during processing and avoids errors related to undefined tags. However, we’ve encountered an issue where API Extractor still throws the following error: "(ae-missing-release-tag) "IModelApp" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)". While API Extractor accepts @stable as a valid tag, it does not recognize it as a valid release tag.

To address this, I’ve made some experimental changes to explore a potential solution. Although the current implementation is not yet polished, the idea is to eventually:

• Introduce a new property as "customReleaseTag" object in extractor config file.
• Define this property as an object with three initial fields:

1. tag: The custom tag name (e.g., @stable).
2. name: A human-readable name for the tag (e.g., Stable).
3. visibility: A numeric value to determine the tag’s precedence relative to existing release tags (@internal, @beta, @alpha, @public).

• The configuration would look something like this:

{
"customReleaseTag": 
  {
    "tag": "@stable",
    "name": "Stable",
    "visibility": 5 
  }
}

With this approach, we aim to:

• Allow the use of custom release tags in API Extractor.

• Avoid errors related to missing release tags.

• Provide flexibility in defining the precedence of custom tags relative to existing ones.

While this idea is still in its early stages, I believe it has the potential to enhance our workflow and provide greater flexibility in managing API documentation. I’d appreciate your feedback and thoughts on this proposal

Repro steps

• clone this repo and switch to branch "pankhur/support-for-custom-release-tag".
• install and build the repo.
• form a symlink for this version to be used instead of hosted npm version of it.

Expected result:

.ts file

.api.md file

without any errors.

Actual result:

.ts file

error:

Details

Standard questions

Please answer these questions to help us investigate your issue more quickly:

Question	Answer
@microsoft/api-extractor version?	7.49.1
Operating system?	Windows
API Extractor scenario?	reporting (.api.md)
Would you consider contributing a PR?	Yes
TypeScript compiler version?	5.6.2
Node.js version (node -v)?	^20.0.0 or ^22.0.0

[ahnpnl]

I actually have kind of similar issue, which is related to any custom tags not recognized by api-extractor

[pankhur94]

Hey Team, just checking in, any updates on this issue?