npm は Node Package Manager の頭文字をとった略で、 Javascript のパッケージをコマンドラインで管理できるオープンソース＆無料のソフトです。 node.js 本体を全く使わない人でも、非常に使えるソフトです。

例えば、Javascript で動く Web アプリゲームを作る時、npm を使うとこんな素敵なメリットがあります。

• アプリで使う関連ライブラリ（パッケージ類）をネットから簡単に集めてこれる。しかも依存関係も解決してくれる。
• アプリで使いたいライブラリの名前やバージョンを記録したテキストファイル(package.json ファイル)を作って保存しておくだけで、別の環境でもすぐに依存関係をネットから集めて環境構築ができる。
• 外から集めてくるパッケージ達は保存しなくても良い。Git とか SVN とか使ってプロジェクトの管理をしてる人は、パッケージ類を含めて保存する必要がなく、ディスク容量も削減できる。

うーん、すごく便利。いろんなアプリ作成でお世話になってます。

公式の使えるパッケージはWebのhttps://www.npmjs.com/から見ることが出来ます。

よく使うコマンドと意味

npm でパッケージ管理する基本知識

公式ドキュメントベースで基本をまとめてます。

npm でプロジェクトのパッケージ管理を開始

新しくフォルダを作り npm init コマンドで、そのフォルダ以下を npm パッケージ管理できます。情報は同じフォルダの package.json ファイルにテキストで記録されます。

下は新しい test フォルダ内で npm init を実行した例です。

コマンドラインから、１～9の質問に入力することで、package.json ファイルが生成されます。 後から package.json の中身はいくら出も変更できるので適当に入力してもＯＫです。

一般公開するパッケージはちゃんと考えて記入する必要がありますが、 自分達で開発する非公開のパッケージであれば、分かりやすさ優先で 入力していくといいです。

※ライセンスは非公開パッケージなら「UNLICENSED」で記入でＯＫです。

入力が完了すると、生成する package.json の中身が表示されます。

これで npm での管理ができるようになりました。

レジストリと npm install

npm install コマンドで、プロジェクトで利用するパッケージを追加・ダウンロードできます。

npm のパッケージはレジストリで管理されてます。

npm install コマンドを使うと、package.json の中身を読み込み、 必要なパッケージをインターネット上のリモートレジストリ（published packages）からパッケージをダウンロードして、 ローカル（の現在のワーキングディレクトリ）にコピー＆使える状態に整えてくれます。

デフォルトだと、リモートレジストリには公式のhttps://www.npmjs.com/ が登録されてます。

npm install に「-g」と付けた時と付けない時の違い

-g は Global（グローバル）のローカルレジストリにパッケージをダウンロードして参照できるようにします。

npm install の -g あり、なしのインストール先は違います。

node.js を Scoop 経由でインストールした場合

Scoop で node.js をインストールしてる人以外は関係ない話です。

通常は「C:\Users{ユーザ名}\AppData\Roaming\npm\node_modules」配下にグローバル指定したパッケージがインストールされますが、

Scoop 経由だと「C:\Users\amaji\scoop\apps\nodejs{Node.jsのバージョン}\bin\node_modules\」配下にパッケージがインストールされます。

Scoop は実行ファイルのエイリアスを「C:\Users{ユーザ名}\scoop\apps\nodejs\current\bin\」配下に作るので、ここに実行可能パスを通しておくと良いです。 通常は勝手に Node.js をインストールしたときに PATH に追加されるから気にしなくていいかな。

Scoop で node.js をインストール Scoop で node.js をインストールするときは、安定版と最新版が選択できると思います。
scoop search node した結果、「nodejs」と「nodejs-lts」が表示されるので、 安定版である「nodejs-lts」をインストールすることをオススメします。

package.json について

npm init コマンドで生成される、npm のパッケージ管理をするフォルダにできるテキストファイルです。

package.json ファイルには、置いてあるフォルダ配下のパッケージを管理するパッケージ情報が書いてあります。

プロジェクトのバージョン管理するときには、この package.json があれば、npm で集めてきたライブラリのほうは 保存せずにすみます。

package.json ファイルがあるフォルダ内で npm install コマンドを実行すると、プロジェクトに必要な パッケージをリモートレジストリから集めてインストールしてくれます。便利。

package.json の中身

拡張子のとおり、普通の JSON ファイルで書かれてます。 例えば当サイト（ブログとか含む）は Gatsby という React ベースの静的サイトジェネレータで 作っていますが、下のような json ファイルです。

{
  "name": "nodachisoft_www",
  "author": "Amaji",
  "title": "nodachisoft_www",
  "description": "nodachisoft website",
  "homepage": "https://nodachisoft.com/",
  "license": "Private use only",
  "version": "1.2.1",
  "repository": {
    "type": "git",
    "url": "https://github.com/xxxxx/nodachisoft_www"
  },
  "scripts": {
    "develop": "gatsby develop",
    "build": "gatsby build",
    　　： 略
  },
  "dependencies": {
    "@babel/core": "~7.9.0",
        : 略
  },
  "devDependencies": {
    "babel-eslint": "^10.0.1",
　　　　： 略
  },
  "keywords": [
    "Simple_game"
  ]
}

package.json へのプロジェクトで使いたいパッケージの書き方

package.json ファイルに含まれる、「dependencies」、「devDependencies」に 使いたいパッケージの名前とバージョンを列挙してあげましょー。

（※他にもxxxDependencies はありますが普段開発で使うことはないので省略）

それぞれ、こんな使い分けがされます。

dependencies

npm install [パッケージ] でインストールすると、自動的に dependencies に追加されます。 --save オプションを付けても同じです。

例えば、以下のコマンドを打ちます。

npm install emotion

結果、package.json に以下の行が追加されました。

{
  "dependencies": {
    "emotion": "^10.0.27"
  }
}

devDependencies

主に npm プロジェクトのテストや自前パッケージング（ライブラリ開発）をする時の依存関係パッケージを書いておきます。

npm install コマンドに「--save-dev」オプションを付けると、package.json の devDependencies に 追加されます。

npm install --save-dev eslint

devDependencies に書いた依存関係パッケージは、 prepare スクリプトを package.json で定義＆実行したとき、 dependencies に加えてココのパッケージもインストールされます。

optionalDependencies

Win/MacOS　など環境によってエラーになるような直接自パッケージが参照するパッケージを書いておきます。

dependencies、devDependencies、optionalDependencies の違い

当サイトの別記事 - npm package.json の dependencies、devDependencies、peerDependenceiseの使い分けのページでまとめていますので、 是非ご参考くださいー。

package.json でパッケージのバージョンを指定する書き方

package.json の Dependencies （依存パッケージ）項目の書き方です。

"パッケージの名前" : "バージョン" の形式で書きます。 バージョンの記載は必須です。

下のような例です。

  "dependencies": {
    "@babel/compat-data": "~7.9.0",
    "@babel/core": "~7.9.0",
    　 ： （中略)
    "@emotion/core": "^10.0.28"
  }

詳細な書き方は(英語)公式 docs.npmjs.com - package.json - dependenciesページをご参照。

よく使う書き方のみピックアップです。

package-lock.json ファイルについて

package.json ファイルのあるフォルダに、package-lock.json が勝手に出来るかと思います。

npm のバージョン 5 から npm install コマンドを実行した時に自動生成される、パッケージ間の依存関係を記録したファイルです。

npm のタスク処理。npm-scripts を使おう！

npm は簡単なタスクをまとめて実行できる npm-scripts と呼ばれる機能をもっています。

有名なタスクランナーツールである webpack や gulp へのエイリアスを組み込むことで、 個々のタスクランナーの固有の実行コマンドを覚える必要がなくスッキリさせることができます。

npm run [自分で　package.json に登録しておいたコマンド] で予め package.json ファイルに書いておいたコマンド（スクリプト）を起動できます。

例えば、以下を package.json に書いておいて npm run clean とプロジェクトフォルダの中で実行すれば、 コマンドで rm -rf public && rm -rf .cache が実行されることとなり、 public フォルダと .cache フォルダを削除する、なんてことができます。

{
  "scripts": {
    "clean": "rm -rf public && rm -rf .cache"
  }
}

基本的に一行でかける程度のコマンドをまとめるのが良いかと思います。

筆者は複雑な処理は gulp などの専用ツールに投げて、大きな実行するタスクの塊をコマンドで登録しておく、という使い方をしています。

詳細な元情報はこちら (公式 docs.npmjs.com - using npm - life-cycle-scripts)をご参照ください。

VSCode と Npm-Scripts の連携

コマンドから npm rum [コマンド] と打ちこまなくても、 例えば VisualStudioCode であればパネルの「NPMスクリプト」から 書いておいたスクリプトをマウスクリックで起動することができます。

うーん、便利。

エラーとか警告ログへの対応

ここからはトラブルシューティング的な内容を記録したものです。

私の環境で発生した警告ログやエラーログへの対応について記録してます。

peer dependency のエラー

下のようなエラー（警告）メッセージがでるよ、という場合。

• npm list でパッケージの左に "UNMET PEER DEPENDENCY" と表示
• npm list でパッケージの左に "npm ERR! peer dep missing:" と表示
• npm install で〇〇 requires a peer of ×× but none is installed. You must install peer dependencies yourself と表示

必要とする依存関係パッケージがインストールできないときにでるエラーメッセージです。

例えば自分の環境で npm install コマンドを十呼応したときに表示された WARNING のログです。

npm WARN eslint-config-react-app@5.2.0 requires a peer of eslint@6.x but none is installed. You must install peer dependencies yourself

「eslint-config-react-app@5.2.0」が依存関係パッケージで「eslint@6.x」を欲しがってるんだけど、対象のバージョンがはいってないよう。自分で依存関係パッケージをインストールしてね。

という意味になります。

上の場合、 eslint 関連は開発用途で使用するパッケージで、6.x のバージョンより古いバージョン（5.x）を package.json の "devDependencies" で指定してしまっていたので、6.x インストールできないじゃん！ というのが原因です。

解消するため以下のように package.json のdevDependencies に求められるバージョンを追記。

再度 npm install 実行。無事に WARNING が消えました。

  "devDependencies": {
    "eslint": "^6.0.1"
  }

※WARNING を起こしている対象のパッケージは dependencies に書いてないもののケースもあります。きっと dependencies が依存しているパッケージですので、npm list [パッケージ名]でどのパッケージが依存元なのか確認できます。

> npm list prism-react
nodachisoft_www@1.0.1 C:\Users\amaji\Desktop\dev\htdocs\nodachisoft_www
`-- prism@4.1.2
  `-- prism-react@1.0.2

上の例だと、パッケージ「prism-react」は「prism」の依存パッケージですね！

npm list で"npm WARN optional SKIPPING OPTIONAL DEPENDENCY"

npm install コマンドを実行した時に "npm WARN optional SKIPPING OPTIONAL DEPENDENCY" とログが出る場合。

オプション扱いの依存パッケージをインストールしようとしたけど、 だめだったよー！という警告メッセージです。

この依存関係のあるパッケージを使わないなら害がないように作られているはずですので、 使わないなら無視してもいいです。

npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@2.1.3 (node_modules\chokidar\node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for fsevents@2.1.3: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})

• 上の例では、 chokidar というパッケージが依存している fsevents パッケージを入れようとしたよ。
• そのために MacOS(Darwin) が必要だけどアナタの端末は WindowsOS(win32) の x64 (CPUアーキテクチャ) だね。というログ。

fsevent でエラー停止する場合 もし package.json ファイルの dependency に fsevent を記載している場合は、optionalDependencies に記載しとけばエラー停止せずにうごくよ、とのこと。 ※stackoverflow にやりとりがあったので、ご参考です。

npm install --no-optional で OptionalDependencies の依存パッケージインストールをスキップし、結果的に警告ログが抑制されます。 ただこの場合は他の OptionalDependencies もインストールスキップされるので注意。

license should be a valid SPDX license expression

以下のようなWARNINGログがnpm install時に表示される。

npm WARN nodachisoft_www@1.0.1 license should be a valid SPDX license expression

package.json の license 欄に SPDX ^※のライセンス以外を書いたときにでる警告です。

SPDX とは SPDX… Software Package Data Exchange の略。Linux財団が主催し取り決める、ライセンスやコンポーネント、著作権の標準的な書き方などを決めた仕様。詳細は Linux Foundation - tools-managing-open-source-programs をご確認。

以下のように package.json を記述しエラーは解消しました。

前） "license": "Private use only"
後） "license": "UNLICENSED"

詳細な書き方は(英語)公式 - docs.npmjs.com - package.json - licenseをご確認ください。

npm install した最後に脆弱性の情報が表示される

npmのバージョン6 以降では、 npm install したときにアップデート可能なパッケージが表示されます。

audited 2466 packages in 10.09s
 : 中略
found 301 vulnerabilities (291 low, 10 high)
  run `npm audit fix` to fix them, or `npm audit` for details

上の例だとnpm install でチェックした 2466 パッケージ中、 301 件のセキュリティ脆弱性がみつかっており、291件は緊急度"低"、10件は緊急度"高"です。

脆弱性のあるライブラリを使ってWebアプリを公開することはリスクがありますので、なるべく最新版にアップデートしましょう。

npm audit で詳細確認

npm audit コマンドで検出した脆弱性の詳細を一覧表示できます。

以下、実行例です。

脆弱性を解決するには「# Run」の右に書いてある、 npm install --save-dev lighthouse@6.1.1 を実行します。

レポートには上の表示されてる例だとセキュリティリスクレベルは「Low（低）、 脆弱性の種類は「Prototype Pollution」。JavaScript でよくあるプロトタイプ汚染の脆弱性、 対象の npm パッケージは"minimist"、追加情報の URL などが記載されてます。

個々のパッケージ修正は上記の # Run のコマンドで対応できます。

なお、 npm audit コマンドの最後に以下のようなまとめがでてます。

found 301 vulnerabilities (291 low, 10 high) in 2466 scanned packages
  run `npm audit fix` to fix 297 of them.
  3 vulnerabilities require semver-major dependency updates.
  1 vulnerability requires manual review. See the full report for details.

• 3 行目：semver-major（セマンティックバージョニング上の大きなバージョンアップ）による依存パッケージのアップデートが 3 件あるよ！
• 4 行目：手動での確認が必要な脆弱性の修復が 1 件あるよ！

とのことでした。

npm audit fix コマンドで一気に修正

npm audit fixコマンドで一気に修正することができます。

件数が多いと少しだけ待ちます。

コーヒーを用意してまちます。 参考までに 2450 パッケージ、300 件程度の fix で 4 分くらで終了。

わりとコーヒーがアツアツのままで完了しました。

> npm audit fix
　　　： （省略・アップデートのログ）
added 315 packages from 294 contributors, removed 37 packages, updated 71 packages and moved 43 packages in 246.426s

156 packages are looking for funding
  run `npm fund` for details

fixed 297 of 301 vulnerabilities in 2466 scanned packages
  1 vulnerability required manual review and could not be updated
  1 package update for 3 vulnerabilities involved breaking changes
  (use `npm audit fix --force` to install breaking changes; or refer to `npm audit` for steps to fix these manually)

301 件中、297件を修正。残る 1 件は手動で、もう 3 件は破壊的な変更があるよ。 それを直すには npm audit fix --force してね。

とのこと。あとは npm audit で手動で個別に確認しながら対応する流れです！

今回は残る重要度はすべて LOW でしたので、これにてアップデート終了としました。

オフライン環境での npm install

npm install xxx.tar.gz のように tar ボールを指定することで直接パッケージファイルをインストールできます。

通常は LAN 内に NPM の Private Registry サーバを立てて、そこで LAN 内の開発者の方々が使うパッケージを 管理するほうが良さそう。

参考

• (英語)公式 - npmjs - npm-registry - The JavaScript Package Registry
• (英語)公式 - docs.npmjs.com - cli-commands - install
• (英語)公式 - docs.npmjs.com - npm-package-json
• (英語)公式 - docs.npmjs.com - using-npm - script
• (英語)公式 docs.npmjs.com - package.json - dependencies
• (英語)wiki - npm
• (英語)stackoverflow - where-does-npm-install-packages
• (英語)Slideshare - Introduction to NPM and building CLI Tools with Node.js
• (英語)stackoverflow- how-to-solve-npm-install-throwing-fsevents-warning-on-non-mac-os

変更履歴

• 2020/07/20 初版公開