NPM のパッケージのディレクトリ構成として推奨されるものを、いくつかの情報ソースをもとにまとめてみた。必ずしもこのディレクトリ構成に従う必要はないが、従っておけば、他の人がパッケージの中身を見たときにパッケージの構造を理解しやすくなる。情けは人のためならず。 ## 情報ソース - [package.json | npm Documentation#directories](https://web.archive.org/web/20180723154127/https://docs.npmjs.com/files/package.json#directories)（過去のドキュメント） - [npm package.json 日本語版 取扱説明書#directories](http://liberty-technology.biz/PublicItems/npm/package.json.html#directories)（上の日本語訳） - [package.json | npm Docs#directories](https://docs.npmjs.com/cli/v7/configuring-npm/package-json#directories)（最新のドキュメント） - [Packages/1.0 - CommonJS Spec Wiki#Package Directory Layout](http://wiki.commonjs.org/wiki/Packages/1.0#Package_Directory_Layout) - [Anatomy of a JavaScript/Node project.](https://gist.github.com/tracker1/59f2c13044315f88bee9) - [Publishing an NPM package - Best practices | BetterStack](https://betterstack.dev/blog/npm-package-best-practices/) - [Quick Start | The AssemblyScript Book#Setting up a new project](https://www.assemblyscript.org/quick-start.html#setting-up-a-new-project) ## ディレクトリ構成 ### assembly [AssemblyScript の初期化時に、ソースファイルの格納場所として指定される](https://github.com/AssemblyScript/assemblyscript/blob/6fe4b288d31b9e08895e80e06c53c7cf426eda90/bin/asinit#L70)。AssemblyScript と TypeScript のソースファイルは拡張子が同じ`.ts`でとても紛らわしいので、一般に TypeScript のソースファイルが格納される`src`ディレクトリとは異なるディレクトリにきっちり分けて AssemblyScript のソースファイルを格納するのは良いアイデアと考えられる。 ### bin モジュールの構成物のうち、コマンドラインより呼び出して使うスクリプトファイルやバイナリファイルなどを格納する。 例えば、AssemblyScript の NPM パッケージをインストールすると、`asc`と`asinit`の二つのコマンドが利用可能になる。このコマンドで実行されるスクリプトはそれぞれ`asc`と`asinit`という名前（本文ママ）のファイルで[bin ディレクトリ](https://github.com/AssemblyScript/assemblyscript/tree/master/bin)に収められており、また、これらは[package.json 中の bin オプションでパスを指定される](https://github.com/AssemblyScript/assemblyscript/blob/6fe4b288d31b9e08895e80e06c53c7cf426eda90/package.json#L65-L68)ことにより、コマンドラインで実行可能となる。 ### build [ビルドに使うスクリプトやツール類を格納するディレクトリ](https://gist.github.com/tracker1/59f2c13044315f88bee9#build)とも言われ、[dist と同じ意味で使われる](https://betterstack.dev/blog/npm-package-best-practices/#heading-directory-structure-conventions)とも言われている。 後者の例として、[AssemblyScript では初期化時にコンパイルした WASM の出力先にはこのディレクトリが指定される](https://github.com/AssemblyScript/assemblyscript/blob/6fe4b288d31b9e08895e80e06c53c7cf426eda90/bin/asinit#L79)ことが挙げられる。 ### dist Web ページの HTML ファイルから呼び出して使用することを主眼に置いた、単一ファイルにバンドル済みの JavaScript ファイルの出力先にはここが適している。 ところで、バンドル済みのファイル名は`(module)-(version).(platform).[min].js`という形式に則ることがおすすめされている。例えば、`foo-0.1.0.browser.min.js`や`foo-0.1.0.amd.js`とか。 ### doc ドキュメント類を格納。 [かつての package.json のドキュメント](https://web.archive.org/web/20180723154127/https://docs.npmjs.com/files/package.json#directoriesdoc)には`directories`オプションの子項目に`doc`が存在したが、[現在の package.json のドキュメント](https://docs.npmjs.com/cli/v7/configuring-npm/package-json#directories)では跡形もなくなってしまった。 ### example モジュールの利用例を示すものを格納する。 ### lib `Node.js`で実行可能な JavaScript ファイルの大部分を格納する。もちろん、モジュールごとに複数のファイルに分かれていてもよい。 ### man マニュアル（manual）を格納する。 ### src トランスパイル/コンパイルが前提のソースコードを格納する。 典型的な例として、Node.js からそのままでは実行できない TypeScript などの AltJS のソースファイルが挙げられる。あるいは、`Babel`ことが前提な、実行可能な環境が限られる新しい ECMAScript の構文を使用している JavaScript のソースファイルも、ここに収めるのが適切かもしれない。 ### test ユニットテスト用スクリプトを格納。 ### vendor `lib`と似ているが、サードパーティー製のコードを格納するという大きな違いがある。なお、JavaScript のライブラリは NPM のパッケージとしても提供されていることが多いため、NPM を利用してライブラリをプロジェクトに導入することが可能なことも多い。特段の事情がない限り、このようにしてライブラリを導入するのが一般的である。その場合、このディレクトリの出番は無い。 `vendor`ディレクトリが使われる場合、バンドル済みの単一ファイルを置くという使われ方を見かける。例えば、highlight.js の GitHub リポジトリにおいて、[tools/vendor](https://github.com/highlightjs/highlight.js/tree/master/tools/vendor)ディレクトリ中に`jQuery`と `Vue.js`のバンドル済みファイルが置かれていることを確認できる。