Rush Stackショップブログイベント
本文へスキップ

.d.ts ロールアップの設定

この記事は、「API Extractor の実行」ページからのチュートリアルの続きです。そちらから始めることをお勧めします。

単純なケース​

.d.ts ロールアップの生成を有効にするには、**api-extractor.json** 設定ファイルで `dtsRollup.enabled` を true に設定するだけです。

デフォルトでは、ロールアップファイルは `"<projectFolder>/dist/<unscopedPackageName>.d.ts"` に書き込まれますが、`dtsRollup.untrimmedFilePath` 設定を使用して変更できます。

以前の例では、元の **package.json** ファイルは次のようになっていることを思い出してください。

awesome-widgets/package.json

{
  "name": "awesome-widgets",
  "version": "1.0.0",
  "main": "./lib/index.js",
  "typings": "./lib/index.d.ts"
}

ロールアップを実際に使用するには、` "typings"` フィールドをロールアップファイルを参照するように変更する必要があります。

awesome-widgets/package.json

{
  "name": "awesome-widgets",
  "version": "1.0.0",
  "main": "./lib/index.js",
  "typings": "./dist/awesome-widgets.d.ts"
}

これにより、TypeScript コンパイラは新しい場所にある型定義を探します。Webpack を使用して JavaScript をバンドルする場合は、` "main"` を `"./dist/awesome-widgets.js"` バンドルを参照するように変更し、**lib** フォルダー全体を **.npmignore** ファイルに追加してパッケージのサイズを小さくすることもできます。

重要な制限事項​

.d.ts ロールアップ機能は現在、パッケージに単一のエントリポイント（`mainEntryPointFilePath` 設定）があることを前提としています。これは必ずしも当てはまりません。一部のプロジェクトでは、次のようなパスベースのインポートに依存しています。

import { Button } from 'awesome-widgets/lib/Button';

このインポートステートメントは、**awesome-widgets** フォルダーツリー内で特定のファイルを探しています。一般的に、これはロールアップと互換性がありません。エクスポートされた宣言には、**lib** フォルダーとロールアップファイルの両方にある2つのコピーが存在するためです。TypeScript コンパイラは通常、重複した宣言を交換可能とは見なしません。非常にわかりにくいエラーメッセージにつながる可能性があります。

API 設計の観点から、パスベースのインポートには、フォルダーレイアウトがAPI コントラクトの一部になるという欠点があります。たとえば、**lib/Button** を **lib/controls/Button** フォルダーに再構成する場合、パスベースのインポートを行っているすべてのコンシューマーにとってこれが破壊的変更になるかどうかを心配する必要があります。TSDoc プロジェクトはこの問題を検討しており、その **tsdoc-metadata.json** ファイルは最終的にプロジェクトの公式にサポートされているエントリポイントを宣言する予定です。その宣言参照表記では、既にインポートパスが許可されています。

しかし現在、API Extractor はプロジェクトに単一のエントリポイントがあると想定しています。（API Extractor 開発者は、パスベースのインポートをベストプラクティスとは考えていないため、取り組んでいる数百の TypeScript パッケージからすべて削除しました。したがって、この機能強化は私たちにとって最優先事項ではありません。ただし、コミュニティから誰かが取り組みたい場合は、喜んで協力します。）

複数のエントリポイントは .d.ts ロールアップに問題を引き起こしますが、幸いなことに、API レポートファイルとドキュメント機能は引き続き使用できます。さまざまなエントリポイントをすべて再エクスポートする **src/api-extractor.ts** などのダミーソースファイルを作成し、それを `mainEntryPointFilePath` として指定するだけです。これにより、API Extractor は、すべての宣言が単一のエントリポイントから来たかのように分析できます。

リリースタグに基づくトリミング​

.d.ts ロールアップ機能は、「トリミング」、つまりリリースタグ（`@alpha`、`@beta`、`@public`、または `@internal`）に従って不要なメンバーを削除することもサポートしています。API Extractor の用語では、「ベータ」は、エンティアレリースブランチの準備状態を指しているわけではないことに注意してください。代わりに、「ベータ」を使用して、*個々のAPI メンバー* のサポートレベルを説明しています。したがって、トリミングされたバージョンとトリミングされていないバージョンは、通常、まったく同じソースファイルとまったく同じ Git ブランチからコンパイルされます。

トリミングを有効にするには、これらの設定を **api-extractor.json** ファイルに追加します。

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

  • `dtsRollup.publicTrimmedFilePath` - 「公開」リリースのトリミングで生成される .d.ts ロールアップファイルの出力パスを指定します。このファイルには、`@public` とマークされている宣言のみが含まれます。

ビルドのメカニズムはユーザーが決定しますが、通常、**package.json** の ` "typings"` フィールドはトリミングされていないロールアップファイルを引き続き指すことをお勧めします。関連するパッケージのコレクションに取り組んでいる場合、これにより、パッケージはビルド中にトリミングされていない宣言に引き続き完全にアクセスできます。たとえば、あるパッケージの `@internal` 関数は、他のパッケージの `@internal` 関数を呼び出す可能性があります。トリミングされたファイルは、`npm publish` の前にビルド後に接続されます。

以前の例プロジェクトを続けると、**api-extractor.json** ファイルを次のようなセクションを含むように変更できます。

awesome-widgets/config/api-extractor.json

{
  . . .
  "dtsRollup": {
    "enabled": true,
    "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
    "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",,
    "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts"
  },
}

まったく同じソースコードから3種類のリリースをビルドして公開すると想像してください。

  • **内部リリース：** バージョン `1.0.0-dev.0` は、会社のプライベート NPM レジストリに公開されます。
  • **ベータリリース：** バージョン `1.0.0-plusbeta` は、プレビューAPI を試したいコンシューマーのために npmjs.com レジストリに公開されます。
  • **公開リリース：** バージョン `1.0.0` も、本番コードを作成しているコンシューマーのために npmjs.com レジストリに公開されます。

内部リリースを公開するには、プロジェクトフォルダーで `npm publish` を実行するだけです。

ベータリリースを公開するには、最初に **package.json** の ` "typings"` フィールドを **awesome-widgets-beta.d.ts** を指すように更新します。（または、**dist/awesome-widgets.d.ts** をそのファイルで上書きすることもできます。）次に、`npm publish` を実行します。

公開リリースを公開するには、最初に **package.json** の ` "typings"` フィールドを **awesome-widgets-public.d.ts** を指すように更新します。（または、**dist/awesome-widgets.d.ts** をそのファイルで上書きすることもできます。）次に、`npm publish` を実行します。

他にも多くの方法が可能です。ビルドスクリプトは、これらのファイルを使用できます。ここで説明したアプローチには、コンシューマーがバージョン選択に基づいて異なるリリースの種類を簡単に切り替えることができるという利点があり、密接に関連する一連のNPMパッケージを公開する必要がある場合にうまく機能することがわかりました。