先にまとめ

• npm ci は npm install と同じように、全依存パッケージをインストールする
• npm install は package-lock.json を更新することがある
• npm ci は package-lock.json を更新しない
• npm ci は node_modules を削除してからインストールする

npm ci ってなんだ

npm install に似ているが、CI のような自動化された環境での利用が想定されているもの。あるいは開発環境でクリーンインストールするのにも使える。処理はいくつかの機能を省略するので、npm install より圧倒的に高速な場合がある。

ドキュメントを読むとそんな感じらしい。

基本的には CI で回す場合はこちらを使いましょう、という理解で良さそう。CI ってなに？くらいの段階の方は別に npm install だけでも大きな問題はないはず。

npm install との違い

• package-lock.json or npm-shrinkwrap.json が必須。ないとコケる
• それらが package.json の記述と矛盾する場合、コケる
• 依存追加には使えない。（npm install xxx でやる）
• node_modules はいったん全消しされる
• package-lock.json を更新しない

npm install の問題点

npm install は package-lock.json を更新することがしばしばあります。

理由は package.json に記述する semver が幅のあるバージョンを許すためで、また package-lock.json は（”lock” という名前に反して）node_modules の実際を反映するものだからです。本当にロックしちゃうとそれはそれで問題があったため変更されたようで。マジかよ。

逆に npm ci は package-lock.json を元に node_modules を構築します。

npm ci の使いどころ

• CI で回す場合
• git clone 直後
• 何かがおかしいので node_modules を空にしてやり直すとき
• 過去の状態を復元するとき

インストールスクリプト

ちょっと仕組みがよくわかんないんだけど、npm ci したら以下のスクリプトは自動で実行されました。npm install 扱いなんですね。

• preinstall
• install
• postinstall

ソース ちらっと見てみたけどなんもわからん。

おしまい

というわけで、CI では npm ci を使うと良さそうです。

package-lock.json については後日また改めて。

参考

• npm-ci | npm Documentation
• npm-scripts | npm Documentation
• node.js – Why does “npm install” rewrite package-lock.json? – Stack Overflow 「なんで npm install が package-lock.json を更新しちゃうの」
• セマンティック バージョニング 2.0.0 | Semantic Versioning
• npm semantic version calculator

パスは自動で追加されるので、気にせずそのまま実行ファイル名を指定してしまって大丈夫。

例えばこれ↓だけで node_modules/.bin/tsc が（あれば）実行されます。

{
  "scripts": {
    "build": "tsc"
  }
}

同様に npx も書く必要なし。プロジェクトの外、グローバルにインストールされたものを呼び出すってなら必要だけど、ローカルにインストールするべきですよ。

ドキュメントの記載

• npm-run-script | npm Documentation

In addition to the shell’s pre-existing PATH, npm run adds node_modules/.bin to the PATH provided to scripts. Any binaries provided by locally-installed dependencies can be used without the node_modules/.bin prefix.

だそうです。

先にまとめ

• 間に -- を挟む
  • e.g. npm run lint -- --fix

ESLint の例

例えばESLint は --fix で（可能な内容なら）自動で修正してくれます。

$ eslint src --fix

が、例えば npm run lint で ESLint が動くとして、これだと自動修正は動かないです。

$ npm run lint --fix

これは --fix が ESLint じゃなくて NPM の方の引数として認識されてしまうためです。

スクリプトの方に与える場合は -- を挟みます。

$ npm run lint -- --fix

これで OK 。

スクリプトの内容が複雑な場合

ls はディレクトリーの内容（ファイルとか）を一覧表示するコマンドです。

sl はジョークコマンドで、汽車が走るやつです。

&& で複数繋がっている場合

例えばこんなスクリプトだとどうなると思いますか。

$ npm run sl-ls -- -l

さあどれだ。

1. 最初のコマンド sl に -l がかかる
2. 最後のコマンド ls に -l がかかる
3. 両方のコマンド sl, ls に -l がかかる

ドキュメントにも特段乗っていないみたいなんだけど、試してみると最後のにのみかかります。

というかたぶん連結してるだけだよね。ターミナルの出力もそんな感じだし。

$ npm run slls -- -l

> @ slls /path/to/project
> sl && ls "-l"

total 308
drwxrwxrwx 1 ginpei ginpei   4096 Nov  2 00:29 node_modules
-rwxrwxrwx 1 ginpei ginpei    210 Nov  2 02:22 package.json
-rwxrwxrwx 1 ginpei ginpei 314804 Nov  2 00:26 yarn.lock
…

pre, post がある場合

さてこれはどうでしょう。

$ npm run ls -- -l

• prels に -l がかかる or かからない
• ls に -l がかかる or かからない
• postls に -l がかかる or かからない

これはドキュメントに掲載されています。

The arguments will only be passed to the script specified after npm run and not to any pre or post script.

引数は npm run の後ろに指定されたスクリプトにのみ渡され、pre や post のスクリプトには渡されません。

参考

• npm-run-script | npm Documentation
• shell – What does “–” (double-dash) mean? (also known as “bare double dash”) – Unix & Linux Stack Exchange

npm run build なんてのをターミナルに入力した経験があると思うんですが、実はこのサブコマンド run は run-script のショートカットです。

というわけでこれ↓が「正式」な入力ということになります。

$ npm run-script build

いやこんなの使ってるひと見たことないけど！

他の

あとまた他にも別名が用意されていて、rum というのも使えます。N と M 。タイポする人が多かったんだろか。

さらに urn というのも。慌ててるとやっちゃうのかな。

参考

--help で出てきます。

$ npm run --help
npm run-script <command> [-- <args>...]

aliases: run, rum, urn

毎年恒例のおれおれアドベントカレンダーです。

ちなみに去年は配列の話でした。

今年は NPM について調べながら記事にしていきます。あんまり詳しくないので頑張ります。

1. npm run は正式なコマンドじゃなかった件
2. npm run … のスクリプトに引数を与えるには --