【Node.js】package.json の files フィールドを理解する

はじめに

npm パッケージを公開する際、すべてのファイルを含める必要はありません。むしろ、不要なファイルを含めてしまうと、パッケージサイズが大きくなり、インストール時間が長くなってしまいます。

files フィールドを使うことで、パッケージに含めるファイルを明示的に指定し、必要なファイルだけを配布することができます。

この記事では、files フィールドの使い方と、実際のパッケージ開発での活用方法を記載します。

filesフィールドとは

files フィールドは、npm パッケージとして配布する際に含めるファイルやディレクトリのパターンを指定する配列です。

{
  "name": "my-package",
  "version": "1.0.0",
  "files": [
    "dist",
    "lib",
    "README.md"
  ]
}

このように指定すると、npm publish した際。dist、lib ディレクトリと README.md ファイルのみがパッケージに含まれます。

基本的な動作

filesフィールドを指定しない場合

files フィールドを指定しない場合、デフォルトで ["*"] として扱われ、すべてのファイルが含まれます。ただし、後述する「常に除外されるファイル」は含まれません。

ファイルパターンの記法

files フィールドでは、.gitignore と似た記法を使えますが、意味が逆になっています。

• .gitignore: 指定したファイルを除外する
• files: 指定したファイルを含める

{
  "files": [
    "dist",           // distディレクトリ全体を含める
    "*.js",           // ルートディレクトリの.jsファイルを含める
    "**/*.d.ts"       // すべての.d.tsファイルを含める
  ]
}

常に含まれるファイル

以下のファイルは、files フィールドの指定に関わらず常に含まれます。

• package.json
• README (拡張子は任意。例: README.md, README.txt)
• LICENSE / LICENCE (大文字小文字、拡張子は任意)
• main フィールドで指定したファイル

常に除外されるファイル

以下のファイルは、files フィールドに指定しても常に除外されます。

• .git
• CVS
• .svn
• .hg
• .lock-wscript
• .wafpickle-N
• .*.swp
• .DS_Store
• ._*
• npm-debug.log
• .npmrc
• node_modules
• config.gypi
• *.orig
• package-lock.json (公開したい場合は npm-shrinkwrap.json を使用)

実践例

TypeScriptプロジェクトの場合

TypeScript で書かれたライブラリを公開する場合、通常はトランスパイル後の JavaScript ファイルと型定義ファイルのみを含めます。

{
  "name": "my-typescript-lib",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build"
  }
}

このようにすると、src ディレクトリの TypeScript ソースコードは含まれず、dist ディレクトリのビルド成果物のみが配布されます。

CLIツールの場合

CLI ツールの場合、実行ファイルとその依存ファイルを含めます。

{
  "name": "my-cli-tool",
  "version": "1.0.0",
  "bin": {
    "mytool": "bin/cli.js"
  },
  "files": [
    "bin",
    "lib"
  ]
}

ドキュメントやライセンスファイルも含める場合

{
  "name": "my-package",
  "version": "1.0.0",
  "files": [
    "dist",
    "docs",
    "LICENSE",
    "CHANGELOG.md"
  ]
}

.npmignoreとの併用

.npmignore ファイルを使うこともできます。ただし、注意点があります。

• ルートディレクトリの .npmignore は files フィールドを上書きしません
• サブディレクトリの .npmignore は有効に機能します
• .npmignore がない場合、.gitignore の内容が使われます
• 重要: files フィールドで指定したファイルは、.npmignore や .gitignore で除外できません

{
  "files": [
    "dist"
  ]
}

この場合、dist ディレクトリは .npmignore に記載しても除外されません。

公開前の確認方法

パッケージに何が含まれるか確認するには、以下のコマンドを使います。

# パッケージに含まれるファイル一覧を表示
npm pack --dry-run

# 実際にtarballを作成して確認
npm pack
tar -tzf my-package-1.0.0.tgz

これにより、実際に公開される内容を事前に確認できます。

ベストプラクティス

1. 明示的に files を指定する

デフォルトの ["*"] に頼らず、必要なファイルを明示的に指定することで、意図しないファイルの公開を防げます。

2. ビルド成果物のみを含める

ソースコードではなく、トランスパイルやバンドル後の成果物のみを含めることで、パッケージサイズを削減できます。

3. prepublishOnly スクリプトを使う

公開前に自動でビルドが実行されるようにします。

{
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build"
  }
}

4. 公開前に必ず確認する

npm pack --dry-run で、公開される内容を確認する。

まとめ

この記事では、files フィールドの使い方と、実際のパッケージ開発での活用方法を記載しました。
filesフィールドを適切に使うことで、以下のメリットがあります。

• パッケージサイズの削減
• インストール時間の短縮
• 不要なファイルの公開を防止
• パッケージの品質向上

参考

• package.json