api-extractor.json

API Extractorの動作は、プロジェクトに保存されている設定ファイル**api-extractor.json**によって制御されます。開始するには、api-extractor initコマンドを使用してテンプレートファイルを作成できます。テンプレートには、各設定について説明するコメントが含まれています。これは、ソースコードのapi-extractor-template.jsonに基づいています。

個々のJSONフィールドについては、以下に説明します。

トップレベルの設定

extends

例

  "extends": "./shared/api-extractor-base.json",

  "extends": "my-package/include/api-extractor-base.json",

デフォルト値: ""

サポートされるトークン: なし

オプションで、このファイルが拡張する別のJSON設定ファイルを指定します。これにより、標準設定を複数のプロジェクトで共有する方法が提供されます。

パスが./または../で始まる場合、パスはextendsフィールドを含むファイルのフォルダを基準に解決されます。それ以外の場合は、最初のパスセグメントがNPMパッケージ名として解釈され、NodeJSのrequire()を使用して解決されます。

projectFolder

例

  "projectFolder": "..",

デフォルト値: "<lookup>"

サポートされるトークン: <lookup>

他の設定ファイル設定で使用できる<projectFolder>トークンを決定します。プロジェクトフォルダには通常、**tsconfig.json**と**package.json**の設定ファイルが含まれていますが、パスはユーザー定義です。

パスは、設定を含む設定ファイルのフォルダを基準に解決されます。

projectFolderのデフォルト値はトークン<lookup>であり、これはフォルダがapi-extractor.jsonを含むフォルダから始まり、**tsconfig.json**ファイルを含む最初のフォルダで停止する親フォルダをトラバースすることによって決定されることを意味します。この方法で**tsconfig.json**ファイルが見つからない場合、エラーが報告されます。

mainEntryPointFilePath

(必須)

例

  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",

サポートされるトークン: <projectFolder>、<packageName>、<unscopedPackageName>

分析の開始点として使用する.d.tsファイルを指定します。API Extractorはこのモジュールによってエクスポートされるシンボルを分析します。

ファイル拡張子は ".d.ts" でなければならず、".ts" ではありません。

パスは、設定を含む設定ファイルのフォルダを基準に解決されます。これを変更するには、<projectFolder>などのフォルダトークンを前に付けます。

bundledPackages

例

  "bundledPackages": [ "library2", "@my-company/*" ],

そのエクスポートがこのパッケージの一部として扱われるべきNPMパッケージ名のリスト。

たとえば、API extractorがプロジェクトlibrary1で実行され、Webpackを使用してプロジェクトlibrary1の分散バンドルが生成され、別のNPMパッケージlibrary2がこのバンドルに埋め込まれているとします。library2の一部の型はlibrary1のエクスポートされたAPIの一部になる可能性がありますが、デフォルトではAPI Extractorはlibrary2を明示的にインポートする.d.tsロールアップを生成します。これを回避するには、上記のように"bundledPackages": [ "library2" ]を指定することができます。これにより、API Extractorは、それらがlibrary1のローカルファイルであるかのように、これらの型を.d.tsロールアップに直接埋め込むように指示されます。

"bundledPackages"要素は、minimatch構文を使用してglobパターンを指定できます。決定論的な出力を確保するために、globは明示的に宣言されたトップレベルの依存関係のみを一致させることによって展開されます。たとえば、上記の"@my-company/*"パターンは、プロジェクトの**package.json**ファイルの"dependencies"または"devDependencies"などのフィールドに表示されない限り、@my-company/exampleとは一致しません。

newlineKind

例

  "newlineKind": "lf",

デフォルト値: "crlf"

API Extractorが出力ファイルを書き込む際に使用する改行の種類を指定します。デフォルトでは、出力ファイルはWindowsスタイルの改行で書き込まれます。POSIXスタイルの改行を使用するには、代わりに"lf"を指定します。OSのデフォルトの改行種を使用するには、"os"を指定します。

enumMemberOrder

例

  "enumMemberOrder": "preserve",

デフォルト値: "by-name"

api.jsonの生成時にAPI Extractorが列挙型のメンバをどのようにソートするかを指定します。デフォルトでは、出力ファイルはアルファベット順にソートされます（"by-name"）。ソースコードの順序を維持するには、"preserve"を指定します。

testMode

例

  "testMode": true,

デフォルト値: false

API Extractorのテストハーネスを呼び出すときにtrueに設定します。testModeがtrueの場合、.api.jsonファイルのtoolVersionフィールドには空の文字列が割り当てられ、テストのために追跡される出力ファイルの不必要な差分を防ぎます。

コンパイラセクション

TypeScriptコンパイラエンジンがAPI Extractorによってどのように呼び出されるかを決定します。

compiler.tsconfigFilePath

例

  "tsconfigFilePath": "<projectFolder>/tsconfig.json",

デフォルト値: "<projectFolder>/tsconfig.json"

サポートされるトークン: <projectFolder>、<packageName>、<unscopedPackageName>

プロジェクトの分析時にAPI Extractorによって使用されるtsconfig.jsonファイルへのパスを指定します。

パスは、設定を含む設定ファイルのフォルダを基準に解決されます。これを変更するには、<projectFolder>などのフォルダトークンを前に付けます。

注記: overrideTsconfigが使用されている場合、この設定は無視されます。

compiler.overrideTsconfig

例

  "compiler": {
    . . .
    "overrideTsconfig": {
      "$schema": "http://json.schemastore.org/tsconfig",

      "compilerOptions": {
        "target": "es5",
        "module": "commonjs",
        "declaration": true,
        "sourceMap": true,
        "declarationMap": true,
        "outDir": "lib"
      },
      "include": [
        "src/**/*.ts"
      ]
    },
    . . .
  }

デフォルト値: _overrideTsconfigセクションなし_

サポートされるトークン: <projectFolder>、<packageName>、<unscopedPackageName>

ディスクから**tsconfig.json**ファイルを読み取る代わりに使用されるコンパイラ構成を提供します。オブジェクトは、TypeScript tsconfig スキーマに準拠している必要があります。

省略した場合、**tsconfig.json**ファイルはprojectFolderから読み込まれます。

compiler.skipLibCheck

例

  "compiler": {
    . . .
    "skipLibCheck": true
  }

デフォルト値: false

このオプションにより、コンパイラは--skipLibCheckオプションを使用して呼び出されます。このオプションはお勧めできません。API Extractorが不完全または不正確な宣言を生成する可能性がありますが、依存関係にAPI Extractorが分析に使用するTypeScriptエンジンと互換性のない宣言が含まれている場合に必要になる可能性があります。可能であれば、skipLibCheckに依存するのではなく、根本的な問題を修正する必要があります。

APIレポートセクション

APIレポートファイル（*.api.md）の生成方法を設定します。

apiReport.enabled

(必須)

例

  "apiReport": {
    "enabled": true,
    . . .
  }

APIレポートを生成するかどうか。

apiReport.reportFileName

例

  "apiReport": {
    . . .
    "reportFileName": "<unscopedPackageName>",
    . . .
  }

デフォルト値: "<unscopedPackageName>"

サポートされるトークン: <packageName>、<unscopedPackageName>

APIレポートファイルのベースファイル名。reportFolderまたはreportTempFolderと組み合わせて、完全なファイルパスを生成します。reportFileNameには、\や/などのパスセパレータを含めないでください。reportFileNameにはファイル拡張子を含めないでください。API Extractorは、.api.mdなどの適切なファイル拡張子を自動的に追加します。reportVariants設定を使用する場合は、ファイル拡張子にバリアント名が含まれます（例：my-report.public.api.mdまたはmy-report.beta.api.md）。"complete"バリアントは常に単純な拡張子my-report.api.mdを使用します。

注記:以前のバージョンのAPI Extractorでは、reportFileNameに.api.md拡張子を明示的に含める必要がありました。後方互換性のために、これはまだ受け付けられますが、上記のルールを適用する前に破棄されます。

apiReport.reportVariants

例

  "apiReport": {
    . . .
    "reportVariants": [ "public", "beta" ],
    . . .
  }

デフォルト値: [ "complete" ]

異なるAPIレベルに対して異なる承認要件に対応するために、APIレポートの複数の「バリアント」を生成できます。reportVariants設定は、生成するバリアントのリストを指定します。省略した場合は、デフォルトで"complete"バリアントのみが生成されます。これには、すべての@internal、@alpha、@beta、および@publicアイテムが含まれます。

バリアント名	含まれるリリースタグ	ファイル拡張子
"complete"	@internal + @alpha + @beta + @public	my-report.api.md
"alpha"	@alpha + @beta + @public	my-report.alpha.api.md
"beta"	@beta + @public	my-report.beta.api.md
"public"	@publicのみ	my-report.public.api.md

apiReport.reportFolder

例

  "apiReport": {
    . . .
    "reportFolder": "<projectFolder>/etc/",
    . . .
  }

デフォルト値: "<projectFolder>/etc/"

サポートされるトークン: <projectFolder>、<packageName>、<unscopedPackageName>

APIレポートファイルが書き込まれるフォルダを指定します。ファイル名部分は、reportFileName設定によって決定されます。

APIレポートファイルは通常、Gitによって追跡されます。その変更を使用して、ブランチポリシー（例：APIレビュー）をトリガーできます。

パスは、設定を含む設定ファイルのフォルダを基準に解決されます。これを変更するには、<projectFolder>などのフォルダトークンを前に付けます。

apiReport.reportTempFolder

例

  "apiReport": {
    . . .
    "reportTempFolder": "<projectFolder>/temp/",
    . . .
  }

デフォルト値: "<projectFolder>/temp/"

サポートされるトークン: <projectFolder>、<packageName>、<unscopedPackageName>

一時レポートファイルが書き込まれるフォルダを指定します。ファイル名部分は、reportFileName設定によって決定されます。

一時ファイルがディスクに書き込まれた後、reportFolder内のファイルと比較されます。異なる場合、本番ビルドは失敗します。

パスは、設定を含む設定ファイルのフォルダを基準に解決されます。これを変更するには、<projectFolder>などのフォルダトークンを前に付けます。

apiReport.includeForgottenExports

例

  "apiReport": {
    . . .
    "includeForgottenExports": true,
    . . .
  }

デフォルト値: false

「忘れられたエクスポート」をAPIレポートファイルに含めるかどうか。忘れられたエクスポートは、ae-forgotten-export警告でフラグが付けられた宣言です。

Doc Model セクション

doc modelファイル（*.api.json）の生成方法を構成します。

docModel.enabled

(必須)

例

  "docModel": {
    "enabled": true,
    . . .
  }

doc modelファイルを生成するかどうか。

docModel.apiJsonFilePath

例

  "docModel": {
    . . .
    "apiJsonFilePath": "<projectFolder>/temp/<unscopedPackageName>.api.json",
    . . .
  }

デフォルト値: "<projectFolder>/temp/<unscopedPackageName>.api.json"

サポートされるトークン: <projectFolder>、<packageName>、<unscopedPackageName>

doc modelファイルの出力パス。ファイル拡張子は.api.jsonである必要があります。

パスは、設定を含む設定ファイルのフォルダを基準に解決されます。これを変更するには、<projectFolder>などのフォルダトークンを前に付けます。

docModel.includeForgottenExports

例

  "docModel": {
    . . .
    "includeForgottenExports": true,
    . . .
  }

デフォルト値: false

「忘れられたエクスポート」をdoc modelファイルに含めるかどうか。忘れられたエクスポートは、ae-forgotten-export警告でフラグが付けられた宣言です。

docModel.projectFolderUrl

例

  "docModel": {
    . . .
    "projectFolderUrl": "http://github.com/path/to/your/projectFolder"
  }

デフォルト値: ""

GitHubやAzure DevOpsなどのウェブサイトでプロジェクトのソースコードを表示できる基本URL。このURLパスは、ディスク上の<projectFolder>パスに対応します。

このURLは、doc modelにシリアル化されたファイルパスと連結されて、個々のAPIアイテムへのURLファイルパスが生成されます。たとえば、projectFolderUrlがhttps://github.com/microsoft/rushstack/tree/main/apps/api-extractorで、APIアイテムのファイルパスがapi/ExtractorConfig.tsの場合、完全なURLファイルパスはhttps://github.com/microsoft/rushstack/tree/main/apps/api-extractor/api/ExtractorConfig.jsになります。

APIドキュメントのリファレンスにソースコードリンクが必要ない場合は、この設定を省略できます。

.d.ts ロールアップ セクション

.d.tsロールアップファイルの生成方法を構成します。

dtsRollup.enabled

(必須)

例

  "dtsRollup": {
    "enabled": true,
    . . .
  }

.d.tsロールアップファイルを生成するかどうか。

dtsRollup.untrimmedFilePath

例

  "dtsRollup": {
    . . .
    "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
    . . .
  }

デフォルト値: "<projectFolder>/dist/<unscopedPackageName>.d.ts"

サポートされるトークン: <projectFolder>、<packageName>、<unscopedPackageName>

トリミングなしで生成される.d.tsロールアップファイルの出力パスを指定します。このファイルには、メインエントリポイントによってエクスポートされるすべての宣言が含まれます。

パスが空文字列の場合、このファイルは書き込まれません。

パスは、設定を含む設定ファイルのフォルダを基準に解決されます。これを変更するには、<projectFolder>などのフォルダトークンを前に付けます。

dtsRollup.alphaTrimmedFilePath

例

  "dtsRollup": {
    . . .
    "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-alpha.d.ts",
    . . .
  }

デフォルト値: ""

サポートされるトークン: <projectFolder>、<packageName>、<unscopedPackageName>

"alpha"リリースのトリミングを使用して生成される.d.tsロールアップファイルの出力パスを指定します。このファイルには、@public、@beta、または@alphaとしてマークされている宣言のみが含まれます。

パスが空文字列の場合、このファイルは書き込まれません。

パスは、設定を含む設定ファイルのフォルダを基準に解決されます。これを変更するには、<projectFolder>などのフォルダトークンを前に付けます。

dtsRollup.betaTrimmedFilePath

例

  "dtsRollup": {
    . . .
    "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
    . . .
  }

デフォルト値: ""

サポートされるトークン: <projectFolder>、<packageName>、<unscopedPackageName>

"beta"リリースのトリミングを使用して生成される.d.tsロールアップファイルの出力パスを指定します。このファイルには、@publicまたは@betaとしてマークされている宣言のみが含まれます。

パスが空文字列の場合、このファイルは書き込まれません。

パスは、設定を含む設定ファイルのフォルダを基準に解決されます。これを変更するには、<projectFolder>などのフォルダトークンを前に付けます。

dtsRollup.publicTrimmedFilePath

例

  "dtsRollup": {
    . . .
    "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts",
    . . .
  }

デフォルト値: ""

サポートされるトークン: <projectFolder>、<packageName>、<unscopedPackageName>

"public"リリースのトリミングを使用して生成される.d.tsロールアップファイルの出力パスを指定します。このファイルには、@publicとしてマークされている宣言のみが含まれます。

パスが空文字列の場合、このファイルは書き込まれません。

パスは、設定を含む設定ファイルのフォルダを基準に解決されます。これを変更するには、<projectFolder>などのフォルダトークンを前に付けます。

dtsRollup.omitTrimmingComments

例

  "dtsRollup": {
    . . .
    "omitTrimmingComments": true,
    . . .
  }

デフォルト値: false

宣言がトリミングされると、デフォルトではExcluded from this release type: exampleMemberなどのコードコメントに置き換えられます。宣言を完全に削除するには、omitTrimmingCommentsをtrueに設定します。

TSDoc メタデータ セクション

tsdoc-metadata.jsonファイルの生成方法を構成します。

注記:tsdoc-metadata.jsonの目的については、TSDoc RFC #7を参照してください。API Extractorの実装は、PackageMetadataManager.tsにあります。

tsdocMetadata.enabled

例

  "tsdocMetadata": {
    "enabled": true,
    . . .
  }

デフォルト値: true

tsdoc-metadata.jsonファイルを生成するかどうか。

tsdocMetadata.tsdocMetadataFilePath

例

  "tsdocMetadata": {
    . . .
    "tsdocMetadataFilePath": "<projectFolder>/dist/tsdoc-metadata.json",
    . . .
  }

デフォルト値: "<lookup>"

サポートされるトークン: <projectFolder>、<packageName>、<unscopedPackageName>

TSDocメタデータファイルを書き込む場所を指定します。

パスは、設定を含む設定ファイルのフォルダを基準に解決されます。これを変更するには、<projectFolder>などのフォルダトークンを前に付けます。

デフォルト値は<lookup>で、プロジェクトのpackage.jsonのtsdocMetadata、typings、またはmainフィールドからパスが自動的に推論されます。これらのフィールドのいずれも設定されていない場合、ルックアップはパッケージフォルダのtsdoc-metadata.jsonにフォールバックします。

メッセージ レポート セクション

分析中に生成されたエラーメッセージと警告メッセージのレポート方法を構成します。

メッセージには3つのソースがあります。コンパイラメッセージ、API Extractorメッセージ、およびTSDocメッセージです。

messages.<セクション>.<ルール>.logLevel

例

  "messages": {
    "compilerMessageReporting": {
      "default": {
        // Treat compiler messages as errors instead of warnings
        "logLevel": "error"
      }
    },
    . . .
  }

デフォルト値: "warning"

可能な値: "error"、"warning"、"none"

メッセージをツールの出力ログに書き込むかどうかを指定します。addToApiReportFileプロパティがこのオプションを上書きする場合があります。

エラーはビルドの失敗とゼロ以外の終了コードを返します。警告は本番ビルドの失敗とゼロ以外の終了コードを返します。非本番ビルド（例：api-extractor runに--localオプションが含まれている場合）、警告は表示されますが、ビルドは失敗しません。

messages.<セクション>.<ルール>.addToApiReportFile

例

  "messages": {
    "compilerMessageReporting": {
      "default": {
        "logLevel": "warning",

         // Don't break the build over compiler issues; instead write them to the API report
        "addToApiReportFile": true
      }
    },
    . . .
  }

デフォルト値: false

addToApiReportFileがtrueの場合：API ExtractorがAPIレポートファイル（.api.md）の書き込みを構成している場合、メッセージはそのファイル内に書き込まれます。そうでない場合は、代わりにlogLevelオプションに従ってメッセージがログに記録されます。

messages.compilerMessageReporting

例

  "messages": {
    "compilerMessageReporting": {
      "TS2551": {
        // Ignore TypeScript error TS2551 ("Property ___ does not exist on type ___")
        "logLevel": "none"
      }
    },
    . . .
  }

デフォルト値

  "messages": {
    "compilerMessageReporting": {
      "default": {
        "logLevel": "warning"
      }
    },
    . . .
  }

入力.d.tsファイルを分析している間にTypeScriptコンパイラエンジンによって報告された診断メッセージの処理を構成します。

TypeScriptメッセージ識別子は、TSの後に整数が付きます。例：TS2551

messages.extractorMessageReporting

例

  "messages": {
    . . .
    "extractorMessageReporting": {
      "ae-extra-release-tag": {
        // Completely disable the "ae-extra-release-tag" validation
        "logLevel": "none"
      },
    },
    . . .
  }

デフォルト値

(最新版の完全なテーブルについては、api-extractor-defaults.jsonを参照してください。)

  "messages": {
    . . .
    "extractorMessageReporting": {
      "default": {
        "logLevel": "warning"
      },
      "ae-forgotten-export": {
        "logLevel": "warning",
        "addToApiReportFile": true
      },
      "ae-incompatible-release-tags": {
        "logLevel": "warning",
        "addToApiReportFile": true
      },
      "ae-internal-missing-underscore": {
        "logLevel": "warning",
        "addToApiReportFile": true
      },
      "ae-unresolved-inheritdoc-reference": {
        "logLevel": "warning",
        "addToApiReportFile": true
      },
      "ae-unresolved-inheritdoc-base": {
        "logLevel": "warning",
        "addToApiReportFile": true
      }
    },
    . . .
  }

分析中にAPI Extractorによって報告されたメッセージの処理を構成します。

API Extractorメッセージ識別子は、ae-で始まります。例：ae-extra-release-tag

messages.tsdocMessageReporting

例

  "messages": {
    . . .
    "tsdocMessageReporting": {
      "tsdoc-link-tag-unescaped-text": {
        // Completely disable the "tsdoc-link-tag-unescaped-text" validation
        "logLevel": "none"
      },
    }
  }

デフォルト値

  "messages": {
    . . .
    "tsdocMessageReporting": {
      "default": {
        "logLevel": "warning"
      }
    }
  }

コードコメントの解析時にTSDocパーサーによって報告されるメッセージの処理を構成します。

TSDocメッセージ識別子はtsdoc-で始まります。例：tsdoc-link-tag-unescaped-text