公開

このガイドの手順に従って宣言ファイルを作成したので、次は npm に公開します。宣言ファイルを npm に公開するには、主に次の 2 つの方法があります。

1. npm パッケージにバンドルする
2. npm の @types 組織 に公開する。

型がソースコードによって生成される場合は、型をソースコードと一緒に公開します。TypeScript プロジェクトと JavaScript プロジェクトの両方で、declaration を介して型を生成できます。

それ以外の場合は、DefinitelyTyped に型を送信することをお勧めします。DefinitelyTyped は、npm の @types 組織に型を公開します。

（svgアイコン）npm パッケージに宣言を含める

パッケージにメインの .js ファイルがある場合は、package.json ファイルにもメインの宣言ファイルを指定する必要があります。 types プロパティを設定して、バンドルされた宣言ファイルを指すようにします。例：

json
{
  "name": "awesome",
  "author": "Vandelay Industries",
  "version": "1.0.0",
  "main": "./lib/main.js",
  "types": "./lib/main.d.ts"
}

"typings" フィールドは types と同義であり、同様に使用できることに注意してください。

（svgアイコン）依存関係

すべての依存関係は npm によって管理されます。依存するすべての宣言パッケージが、package.json の "dependencies" セクションで適切にマークされていることを確認してください。たとえば、Browserify と TypeScript を使用したパッケージを作成したとします。

json
{
  "name": "browserify-typescript-extension",
  "author": "Vandelay Industries",
  "version": "1.0.0",
  "main": "./lib/main.js",
  "types": "./lib/main.d.ts",
  "dependencies": {
    "browserify": "latest",
    "@types/browserify": "latest",
    "typescript": "next"
  }
}

ここでは、パッケージは browserify と typescript パッケージに依存しています。 browserify は npm パッケージに宣言ファイルをバンドルしていないため、宣言のために @types/browserify に依存する必要がありました。一方、typescript は宣言ファイルをパッケージ化しているため、追加の依存関係は必要ありませんでした。

パッケージはそれぞれからの宣言を公開しているため、browserify-typescript-extension パッケージのユーザーはこれらの依存関係も持つ必要があります。そのため、"devDependencies" ではなく "dependencies" を使用しました。そうでない場合、コンシューマーはこれらのパッケージを手動でインストールする必要があったためです。コマンドラインアプリケーションを作成しただけで、パッケージがライブラリとして使用されることを想定していなかった場合は、devDependencies を使用していた可能性があります。

（svgアイコン）要注意点

（svgアイコン）/// <reference path="..." />

宣言ファイルでは /// <reference path="..." /> を使用*しないでください*。

ts
/// <reference path="../typescript/lib/typescriptServices.d.ts" />
....

代わりに /// <reference types="..." /> を使用*してください*。

ts
/// <reference types="typescript" />
....

詳細については、依存関係の利用 セクションを再確認してください。

（svgアイコン）依存関係の宣言のパッケージ化

型定義が別のパッケージに依存している場合

• しないでください 自分の型定義と組み合わせないで、それぞれを独自のファイルに保持してください。
• しないでください パッケージ内の宣言をコピーしないでください。
• してください npm 型宣言パッケージが宣言ファイルをパッケージ化していない場合は、それに依存してください。

typesVersions によるバージョン選択

TypeScript がどのファイルを読み取る必要があるかを判断するために package.json ファイルを開くと、最初に typesVersions というフィールドを探します。

フォルダーのリダイレクト (* を使用)

typesVersions フィールドを持つ package.json は、次のようになります。

json
{
  "name": "package-name",
  "version": "1.0.0",
  "types": "./index.d.ts",
  "typesVersions": {
    ">=3.1": { "*": ["ts3.1/*"] }
  }
}

この package.json は、TypeScript に対して、最初に現在のバージョンの TypeScript を確認するように指示します。 3.1 以降の場合、TypeScript はパッケージを基準としたインポートパスを特定し、パッケージの ts3.1 フォルダーから読み取ります。

それが { "*": ["ts3.1/*"] } の意味です。 パスマッピング に精通している場合は、それとまったく同じように機能します。

上記の例では、"package-name" からインポートする場合、TypeScript 3.1 で実行されている場合、TypeScript は [...]/node_modules/package-name/ts3.1/index.d.ts (およびその他の関連パス) から解決しようとします。 package-name/foo からインポートする場合、[...]/node_modules/package-name/ts3.1/foo.d.ts と [...]/node_modules/package-name/ts3.1/foo/index.d.ts を探します。

この例で TypeScript 3.1 で実行されていない場合はどうでしょうか？ typesVersions のフィールドが一致しない場合、TypeScript は types フィールドにフォールバックするため、ここでは TypeScript 3.0 以前は [...]/node_modules/package-name/index.d.ts にリダイレクトされます。

ファイルのリダイレクト

一度に 1 つのファイルの解決のみを変更する場合、正確なファイル名を渡すことで、TypeScript に異なる方法でファイルを解決するように指示できます。

json
{
  "name": "package-name",
  "version": "1.0.0",
  "types": "./index.d.ts",
  "typesVersions": {
    "<4.0": { "index.d.ts": ["index.v3.d.ts"] }
  }
}

TypeScript 4.0 以降では、"package-name" のインポートは ./index.d.ts に解決され、3.9 以前では "./index.v3.d.ts に解決されます。

リダイレクトはパッケージの*外部* API にのみ影響することに注意してください。 プロジェクト内のインポート解決は typesVersions の影響を受けません。 たとえば、前の例にある import * as foo from "./index" を含む d.ts ファイルは、index.v3.d.ts ではなく index.d.ts にマップされたままですが、別のパッケージが import * as foo from "package-name" をインポートすると、*index.v3.d.ts* が取得されます.

マッチング動作

TypeScript がコンパイラと言語のバージョンが一致するかどうかを決定する方法は、Node の semver 範囲 を使用することです。

複数フィールド

typesVersions は、各フィールド名が一致する範囲によって指定される複数のフィールドをサポートできます。

{
  "name": "package-name",
  "version": "1.0",
  "types": "./index.d.ts",
  "typesVersions": {
    ">=3.2": { "*": ["ts3.2/*"] },
    ">=3.1": { "*": ["ts3.1/*"] }
  }
}

範囲は重複する可能性があるため、どのリダイレクトを適用するかは順序に依存します。 つまり、上記の例では、>=3.2 と >=3.1 の両方のマッチャーが TypeScript 3.2 以降をサポートしていますが、順序を逆にすると思わぬ動作をする可能性があるため、上記のサンプルは次のサンプルと同等ではありません。

{
  "name": "package-name",
  "version": "1.0",
  "types": "./index.d.ts",
  "typesVersions": {
    // NOTE: this doesn't work!
    ">=3.1": { "*": ["ts3.1/*"] },
    ">=3.2": { "*": ["ts3.2/*"] }
  }
}

@types への公開

@types 組織のパッケージは、types-publisher ツール を使用して DefinitelyTyped から自動的に公開されます。 宣言を @types パッケージとして公開するには、DefinitelyTyped にプルリクエストを送信してください。 詳細は、貢献ガイドラインページ を参照してください。