NPMパッケージ開発者のためのtsconfig

パッケージを使う人にもTypeScriptによる型の享受を目指す

パッケージを公開するときは、動作する形で公開するのが前提なのでjsにする必要があります。つまりコンパイルは必須です。ですがせっかくTypeScriptで作ったのだからパッケージの型情報も提供しましょう。

型定義ファイルも出力する

型定義ファイルを一緒に出力しましょう。そのためにはtsconfig.jsonにあるdeclarationの項目をtrueに変更します。

json
"declaration": true,
/* Generates corresponding '.d.ts' file. */

json
"declaration": true,
/* Generates corresponding '.d.ts' file. */

このように設定するとコンパイルで出力したjsファイルと同じディレクトリに同名で拡張子がd.tsのファイルも出力されるようになります。これが型情報のファイルです。なおこの型定義ファイルだけをコンパイルで出力されたjsと別のディレクトリに出力するためのオプションは存在しません。

変哲もないnumber型のプロパティ持つValue Objectを作ったとします。

ts
class NumericalValueObject {
  private value: number;
 
  public constructor(value: number) {
    this.value = value;
  }
 
  public equals(other: NumericalValueObject): boolean {
    return this.value === other.value;
  }
 
  public toString(): string {
    return `${this.value}`;
  }
}

ts
class NumericalValueObject {
  private value: number;
 
  public constructor(value: number) {
    this.value = value;
  }
 
  public equals(other: NumericalValueObject): boolean {
    return this.value === other.value;
  }
 
  public toString(): string {
    return `${this.value}`;
  }
}

これをコンパイルし、型定義を生成するとこのようになっています。

ts
declare class NumericalValueObject {
  private value;
  constructor(value: number);
  equals(other: NumericalValueObject): boolean;
  toString(): string;
}

ts
declare class NumericalValueObject {
  private value;
  constructor(value: number);
  equals(other: NumericalValueObject): boolean;
  toString(): string;
}

内容自体はちょうどインターフェースのようなファイルとなっています。

宣言元へのジャンプでのtsファイルを参照できるようにする

IDEを使っているときに有用で、実際のTypeScriptのソースコードがどのようにコーディングされているかを閲覧することができるようになります。tsconfig.jsonにあるdeclarationMapの項目をtrueに変更します。

json
"declarationMap": true,
/* Generates a sourcemap for each corresponding '.d.ts' file. */

json
"declarationMap": true,
/* Generates a sourcemap for each corresponding '.d.ts' file. */

このように設定するとコンパイルで出力したjsファイルと同じディレクトリに同名で拡張子がd.ts.mapのファイルも出力されるようになります。このファイルは元のtsと実際に動作するjsの対応付けをしてくれます。ただしこの設定だけでは不十分で、参照元となる元のtsファイルも一緒にパッケージとして公開する必要があります。

元のtsも公開する

特に設定していなければ元のtsファイルも公開されますが、公開する内容を調整している場合は逆にpackage.jsonのfilesプロパティをを変更して元のtsファイルも公開するように変更が必要です。tsconfig.jsonのdeclarationMapを設定しても元のtsファイルを参照できないときはここで公開する内容を制限していないか確認してください。

json
{
  "name": "YYTS",
  "version": "1.0.0",
  "license": "CC BY-SA 3.0",
  "sideEffects": false,
  "main": "./cjs/index.js",
  "module": "./esm/index.js",
  "types": "./esm/index.d.ts",
  "files": ["dist", "src"],
  "scripts": {
    "build": "yarn build:cjs && yarn build:esm",
    "build:cjs": "tsc -p tsconfig.cjs.json",
    "build:esm": "tsc -p tsconfig.esm.json"
  }
}

json
{
  "name": "YYTS",
  "version": "1.0.0",
  "license": "CC BY-SA 3.0",
  "sideEffects": false,
  "main": "./cjs/index.js",
  "module": "./esm/index.js",
  "types": "./esm/index.d.ts",
  "files": ["dist", "src"],
  "scripts": {
    "build": "yarn build:cjs && yarn build:esm",
    "build:cjs": "tsc -p tsconfig.cjs.json",
    "build:esm": "tsc -p tsconfig.esm.json"
  }
}

この例はdistにコンパイルした結果のjs, d.ts, d.ts.mapがあり、srcに元のtsがあるものと想定しています。

実際にパッケージとなるファイルにどのようなファイルが含まれているかについては次のコマンドを実行してください。

sh
npm publish --dry-run

sh
npm publish --dry-run

JavaScriptのsourceMapも出力する

sourceMapとはAltJSがコンパイルされたJavaScriptとの行を一致させるものです。これがあることによってデバッグやトレースをしているときに、元のtsファイルの何行目で問題が発生しているかわかりやすくなります。module bundlerを使用するときはこのオプションを有効にしていないと基本的に何もわかりません。このオプションはパッケージを公開しないとしても有効にしておくことが望ましいでしょう。

tsconfig.jsonにあるsourceMapの項目をtrueに変更します。

json
"sourceMap": true,
/* Generates corresponding '.map' file. */

json
"sourceMap": true,
/* Generates corresponding '.map' file. */

こちらもコンパイルで出力したjsファイルと同じディレクトリに同名で拡張子がjs.mapのファイルも出力されるようになります。