Nodachisoft Nodachi Sword Icon
  
@あまじ✎ 2020年7月21日に更新

npm で javascript や typescript プロジェクトのパッケージを管理する基本

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

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

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

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

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

よく使うコマンドと意味

コマンド 概要
npm npmコマンドの使い方が表示される。
npm help [コマンド] npmコマンドの詳細な使い方が HTML で表示される
npm init npmでカレントディレクト配下をパッケージ管理をする最初に使う。package.json を作る。
npm install [パッケージ名] カレントディレクトリ配下にパッケージをインストール
npm install -g [パッケージ名] ログインユーザがローカル内のどっからでも参照できる、グローバルなパス配下にパッケージをインストール
npm install ローカルの package.json ファイルを読み取ってプロジェクトに必要なパッケージをインストールする
npm uninstall [パッケージ名] 対象のパッケージをアンインストール
npm list --depth=0 現行プロジェクトにインストールしてあるメインパッケージ(依存パッケージとかは出さない)を表示
npx [パッケージ名] インストールせずに一時ファイルでパッケージをダウンロードして実行

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

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

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

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

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

npm_init_01

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

項目 入力する内
1.package name プロジェクトのパッケージ名
2.version xx.xx.xxのセマンティックバージョン形式でバージョンを記述
3.description パッケージ(作るプロジェクト)の概要
4.entry point パッケージを実行する開始ファイル
5.test command プロジェクトのテストを行うコマンド
6.git repository git管理する時のリポジトリURL
7.keywords npmで検索するときのキーワード
8.author パッケージの作者
9.license 利用にあたってのライセンス形式。MITとかApacheLiscene2とか

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

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

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

npm_init_02

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

レジストリと npm install

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

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

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

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

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

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

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

  -g なし -g あり
インストール場所 .\node_modules\ 配下 %nodejsインストール場所%\bin 配下

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 ファイルです。

当サイトのpackage.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 本番動作で使うパッケージはココ。パッケージとして動かすのに必要なものを書く。
devDependencies 開発するときに使うよ。テストで使うようなパッケージをココへ。
optionalDependencies 環境依存で導入するパッケージを書く。Linux, Win, Mac とか環境で使えないものはインストールがスキップされる。

dependencies

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

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

npmでemotionパッケージのインストール
npm install emotion

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

package.json
{
  "dependencies": {
    "emotion": "^10.0.27"
  }
}

devDependencies

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

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

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ページをご参照。

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

書き方例 取得するバージョン
"1.2.3" 1.2.3 のみ。
">1.2.3" 1.2.3 より大きい
">=1.2.3" 1.2.3 以上
"~1.2" 1.2.X の範囲で(Xは任意)
"~1" 1.X.X の範囲で(Xは任意)
"^1.2.3" 1.2.3~2.0.0 の間
"^0.1.2" 0.1.2~0.2.0 の間

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 フォルダを削除する、なんてことができます。

package.jsonでのscript例を抜粋
{
  "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 のログです。

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 を記述しエラーは解消しました。

package.json(SPDX仕様エラー)
前) "license": "Private use only"
後) "license": "UNLICENSED"

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

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

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

npmのインストールログにでる脆弱性情報
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 コマンドで検出した脆弱性の詳細を一覧表示できます。

以下、実行例です。

npm_audit_result.png

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

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

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

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

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 内の開発者の方々が使うパッケージを 管理するほうが良さそう。

参考

変更履歴

  • 2020/07/20 初版公開
 
 
送信しました!

コメント、ありがとうございます。

なんかエラーでした

ごめんなさい。エラーでうまく送信できませんでした。ご迷惑をおかけします。しばらくおいてから再度送信を試していただくか、以下から DM などでご連絡頂ければと思います。

Twitter:@NodachiSoft_jp
お名前:
 
連絡先:
 
メッセージ:
 
戻る
内容の確認!

以下の内容でコメントを送信します。よろしければ、「送信」を押してください。修正する場合は「戻る」を押してください

お名前:
 
連絡先:
 
メッセージ:
 
Roboto からの操作ではないという確認のため確認キーを入れてください。
確認キー=95
戻る
 / 
送信確認へ
コメント欄
コメント送信確認へ

関連ありそうな記事(3件)です!

Chocolatey の使い方とインストール手順

#パッケージ管理✎ 2020-10-16
Chocolatey をインストールする手順、基本的な使い方について。
広告領域
追従 広告領域
目次
npm で javascript や typescript プロジェクトのパッケージを管理する基本
npm で javascript や typescript プロジェクトのパッケージを管理する基本
よく使うコマンドと意味
よく使うコマンドと意味
npm でパッケージ管理する基本知識
npm でパッケージ管理する基本知識
npm でプロジェクトのパッケージ管理を開始
npm でプロジェクトのパッケージ管理を開始
レジストリと npm install
レジストリと npm install
npm install に「-g」と付けた時と付けない時の違い
npm install に「-g」と付けた時と付けない時の違い
node.js を Scoop 経由でインストールした場合
node.js を Scoop 経由でインストールした場合
package.json について
package.json について
package.json の中身
package.json の中身
package.json へのプロジェクトで使いたいパッケージの書き方
package.json へのプロジェクトで使いたいパッケージの書き方
dependencies
dependencies
devDependencies
devDependencies
optionalDependencies
optionalDependencies
dependencies、devDependencies、optionalDependencies の違い
dependencies、devDependencies、optionalDependencies の違い
package.json でパッケージのバージョンを指定する書き方
package.json でパッケージのバージョンを指定する書き方
package-lock.json ファイルについて
package-lock.json ファイルについて
npm のタスク処理。npm-scripts を使おう!
npm のタスク処理。npm-scripts を使おう!
VSCode と Npm-Scripts の連携
VSCode と Npm-Scripts の連携
エラーとか警告ログへの対応
エラーとか警告ログへの対応
peer dependency のエラー
peer dependency のエラー
npm list で"npm WARN optional SKIPPING OPTIONAL DEPENDENCY"
npm list で"npm WARN optional SKIPPING OPTIONAL DEPENDENCY"
license should be a valid SPDX license expression
license should be a valid SPDX license expression
npm install した最後に脆弱性の情報が表示される
npm install した最後に脆弱性の情報が表示される
npm audit で詳細確認
npm audit で詳細確認
npm audit fix コマンドで一気に修正
npm audit fix コマンドで一気に修正
オフライン環境での npm install
オフライン環境での npm install
参考
参考
変更履歴
変更履歴
Nodachisoft © 2020