npm publishするパッケージを必要最低限のファイルのみにする

慣れていない TypeScript で作成したちょっとしたライブラリ。

以下のコマンドの動作も問題なく、

$ npm install

$ npm run build

あとは GtiHub Packages に publish できたらいいやと思っていた矢先、以下のようなご指摘が。

エンジニア

dist 配下だけの package を配布してね

今回は、npm publish する際のパッケージ構成について紹介します。

あわせて読みたい

Mavenリポジトリを簡易的に作るための3つの方法(AWS, GitHub)

パッケージはdistの中身だけで事足りる

確かに npm run build した際に、dist 配下に生成物ができあがります。

ライブラリを参照する側としては、このファイルと package.json があれば問題なく、他のファイルは不要となるのですよね。

しかし、丁寧にライブラリのソースコード(トランスパイル前)も詰め込んでいたので、npm install した際に node_modules 配下の当該ライブラリに余分なファイルが・・・。

publishするファイルの指定

npm publish する際に何を含めるのかは、以下の 2 つのファイルで制御されていると思っていました。

間違いではないですが、npm の仕様で設定に関係なく必ず含まれるファイル・絶対に含められないファイルがあります。

files に書いていなくても、次のものは常にパッケージに入ります。

• package.json
• README（拡張子・大文字小文字は問わない）
• LICENSE / LICENCE（同上）
• main フィールドで指定したファイル
• bin フィールドに書いたファイル

逆に、次のものは files に明示しても含められません。

• .git / node_modules
• .npmrc
• package-lock.json / yarn.lock / pnpm-lock.yaml / bun.lockb

また、ルートディレクトリでは package.json の files の定義が優先され、そこに書かれているものだけが node_modules へのインストール対象となるわけですね。

この「ルートディレクトリでは」という但し書きが実は重要で、サブディレクトリに置いた .npmignore は files より優先されます。

files で dist を含めたつもりなのに一部が入らない、という場合は dist の中に .npmignore が紛れていないか確認してみてください。

具体例として、ビルド成果物の入った dist だけを配布したい場合は、package.json に次のように files を書きます。

{
  "name": "my-lib",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ]
}

こうしておくと、npm publish 時に dist と package.json・README などの必須ファイルだけがパッケージに含まれ、トランスパイル前のソースなどは自動的に除外されます。

npm publish 時のログを見ていると、必要なファイルのみ tar ball パッケージングしてくれていることが良くわかります。

公開する前に中身を確認する

とはいえ、publish してから気づくのは避けたいところです。

公開前に中身を確認するなら npm pack が便利ですね。

$ npm pack --dry-run

--dry-run を付けると実際に tarball を作らずに、何が含まれるかだけを報告してくれます。

意図しないソースや設定ファイルが並んでいないか、ここで一度目視しておくと安心です。

OpenAPI Generatorの生成コードの場合

なお、同様のことを OpenAPI Generator で自動生成したコード群で実現する場合は、ちょっとした作業が必要になります。

デフォルトでは、package.json に files の項目は定義されません。

そこで、コード生成時のオプションでテンプレート(template)を差し込む形になります。

手順としては、テンプレートを取り出す → 書き換える → 生成時に指定するの 3 段階です。

まず author template でテンプレート一式を取り出します。

$ openapi-generator author template -g typescript-axios -o templates

-o で出力先を指定します（省略すると out になります）。

取り出した package.mustache に files を書き足したら、生成時に -t でそのディレクトリを指定します。

$ openapi-generator generate -g typescript-axios -i openapi.yaml -o client -t templates

全部のテンプレートを抱える必要はなく、変更したいファイルだけ残しておけば大丈夫です。

OpenAPI Generator は Java のソースコードを生成する時に色々と苦労しましたが、言語やバージョンによって意識しておくポイントも多く大変ですね。

今回はコードジェネレート時の共通した話題なので、まだ良かったかな。

あわせて読みたい

【OpenAPI Generator】バージョン6.0.0でJavaのビルドが通らないので5.4.0に戻す

まとめ

今回、以下の記事もすごく参考になったので紹介しておきます。

参考(出典)

• package.json の files フィールド(npm Docs)
• npm pack(npm Docs)
• Using Templates(OpenAPI Generator)

saratoga

フリーランスエンジニア

XYouTube

仕事にも趣味にも IT を駆使するフリーランスエンジニア。技術的な TIPS や日々の生活の中で深堀りしてみたくなったことを備忘録として残していきます。