コンテンツにスキップ
machbase-neo
JSH
パッケージマネージャー

パッケージマネージャー

pkgコマンドは、package.jsonの作成、JSHパッケージのインストール、パッケージスクリプトの実行を行います。 JSHアプリケーションで、/workなどのプロジェクトディレクトリ内の依存関係を管理する場合に使用します。

概要

pkgコマンドは、以下の操作に対応しています。

  • 新しいpackage.jsonの作成
  • node_modulesへの依存関係のインストール
  • GitHubプロジェクトを任意のディレクトリにコピーし、その場所にプロジェクトの依存関係をインストール
  • package-lock.jsonの管理
  • package.jsonのscriptsの実行
  • インストールしたパッケージのbin項目から実行ラッパーを生成
  • 依存関係と生成したラッパーの削除

package.json

pkgは、package.jsonを選択したパッケージルートのマニフェストとして扱います。 通常のプロジェクトインストールでは、現在のディレクトリ、または--dirで指定したディレクトリがルートです。 pkg install -g、pkg uninstall -gでは、パッケージは/work/node_modulesにインストールされますが、/work/package.jsonと/work/package-lock.jsonは作成しません。

最小構成のプロジェクトマニフェストは以下のとおりです。

{
  "name": "demo-app",
  "version": "1.0.0",
  "scripts": {
    "start": "./main.js"
  },
  "dependencies": {
    "generic-pkg": "^1.2.0",
    "github.com/acme/demo": "#tag=v1.1.0"
  }
}

pkgが主に使用するフィールドは以下のとおりです。

フィールド型説明
nameStringプロジェクトのパッケージ名
versionStringプロジェクトのバージョン
scriptsObjectpkg runで実行する、名前付きのコマンドライン
dependenciesObjectパッケージ名とバージョン指定子のマップ

補足：

  • scriptsは、現在のプロジェクトマニフェストの項目で、pkg runだけが使用します。
  • dependenciesは、選択したパッケージルートを基準に、pkg installとpkg uninstallが更新します。
  • 通常のプロジェクトインストールでは、再現可能なインストールのため、pkgはpackage.jsonと同じ場所にpackage-lock.jsonも書き込みます。
  • binは、node_modules内の各インストール済みパッケージのpackage.jsonから読み取ります。pkgは、これに基づいてnode_modules/.binにラッパーを生成します。

たとえば、pkg install -g github.com/acme/demoを実行すると、パッケージのマニフェストは/work/node_modules/github.com/acme/demo/package.jsonに置かれ、pkgのグローバルメタデータは/work/node_modules/.pkg/に保存されます。

pkg init

現在のプロジェクトディレクトリに、新しいpackage.jsonを作成します。

構文
pkg init [options] <name>
オプション
  • -C, --dir <dir> 現在の作業ディレクトリではなく、指定したプロジェクトディレクトリを使用します。
  • -h, --help ヘルプを表示します。
使用例
/work > pkg init demo-app
Created /work/package.json

作成するファイルには、空のscriptsとdependenciesオブジェクトが含まれます。

{
  "name": "demo-app",
  "version": "1.0.0",
  "scripts": {},
  "dependencies": {}
}

pkg install

package.jsonに宣言した依存関係をインストールします。または、指定した単一のパッケージをインストールし、 package.jsonとpackage-lock.jsonを更新します。

構文
pkg install [options] [name]
オプション
  • -C, --dir <dir> 現在の作業ディレクトリではなく、指定したプロジェクトディレクトリを使用します。
  • -g, --global --dirを無視して、グローバルパッケージディレクトリにインストールします。このディレクトリはグローバルパッケージ専用のため、通常のプロジェクトルートに使用しないでください。
  • -h, --help ヘルプを表示します。

nameを省略すると、選択したプロジェクトマニフェストに宣言済みの依存関係をインストールします。-gでは、/work/node_modules/.pkg/内の内部メタデータを使用します。

グローバルインストール

pkg install -g <name>は、/work/node_modulesにインストールします。 -gを指定すると、pkgは--dirを無視します。 グローバルパッケージディレクトリは、グローバルパッケージとメタデータのための予約領域です。通常のプロジェクトは、/work自体ではなく、/work/my-appなどのサブディレクトリに作成してください。

この方式で、次の2つの用途に対応できます。

  • binラッパーをシェルのPATHから直接実行できる、グローバルコマンドパッケージのインストール
  • グローバルパッケージディレクトリへの共有ライブラリパッケージのインストール

例を示します。

/work > pkg install -g github.com/acme/demo
Installed github.com/acme/demo#tag=v1.1.0

npmパッケージ

パッケージ名がGitHubリポジトリのパスでなければ、npmレジストリからインストールします。

/work > pkg install generic-pkg
Installed generic-pkg@1.2.0

この場合、package.jsonには解決したnpmバージョン範囲を保存します。

{
  "dependencies": {
    "generic-pkg": "^1.2.0"
  }
}

GitHubリポジトリのパッケージ

パッケージ名がgithub.com/<org>/<repo>形式なら、GitHubリポジトリの内容を直接ダウンロードしてインストールします。

対応する形式は以下のとおりです。

  • github.com/<org>/<repo>
  • github.com/<org>/<repo>@<tag>
  • github.com/<org>/<repo>#tag=<tag>
  • github.com/<org>/<repo>#branch=<branch>

動作は以下のとおりです。

  • @<tag>または#tag=<tag>を指定すると、そのタグを使用します。
  • #branch=<branch>を指定すると、タグの有無に関係なく、そのブランチを使用します。
  • タグを指定せず、リポジトリにタグがある場合は、GitHub tags APIが返す最新タグを使用します。
  • タグを指定せず、リポジトリにタグがない場合は、リポジトリのdefault_branchを使用します。
使用例: 最新タグのインストール
/work > pkg install github.com/acme/demo
Installed github.com/acme/demo#tag=v1.1.0
使用例: 指定タグのインストール
/work > pkg install github.com/acme/demo@v1.0.0
Installed github.com/acme/demo#tag=v1.0.0

明示的なref構文も使用できます。

/work > pkg install github.com/acme/demo#tag=v1.0.0
Installed github.com/acme/demo#tag=v1.0.0
使用例: 指定ブランチのインストール
/work > pkg install github.com/acme/demo#branch=develop
Installed github.com/acme/demo#branch=develop
使用例: 既定ブランチへのフォールバック

リポジトリにタグがない場合は、既定のブランチを使用します。

/work > pkg install github.com/acme/notags
Installed github.com/acme/notags#branch=main

インストール先

インストールしたパッケージは、選択したnode_modulesディレクトリにコピーされます。 例を示します。

  • generic-pkg -> node_modules/generic-pkg
  • github.com/acme/demo -> node_modules/github.com/acme/demo

GitHubリポジトリのパッケージも、node_modulesにインストールされます。 pkg install -gを使用すると、この場所は/work/node_modulesになります。

インストールしたパッケージのpackage.jsonにbinがある場合、pkgはnode_modules/.binにラッパーを生成します。 ラッパー名は、パッケージマニフェストのbin設定に従います。

対応するbinの形式は、次の2つです。

  • 文字列形式："bin": "main.js"
  • オブジェクト形式："bin": { "demo": "demo.js" }

binが文字列の場合、pkgはパッケージ名からラッパー名を決めます。 たとえば、github.com/acme/demoはdemo.jsを生成します。 binがオブジェクトの場合、各キーがラッパー名になります。 ラッパー名には、英字、数字、.、_、-だけを使用できます。

たとえば、インストールしたパッケージのマニフェストが以下の場合、

{
  "name": "github.com/acme/demo",
  "bin": {
    "demo": "demo.js"
  }
}

node_modules/.bin/demo.jsが生成されます。ラッパーは、インストール済みパッケージのディレクトリに作業ディレクトリを変更してから、binの対象を実行します。

そのため、binの対象は、インストール済みパッケージのルートを基準とする有効なパスである必要があります。 ラッパーの後に指定した追加引数は、そのまま対象に渡されます。

生成された.binラッパーの実行

pkg runは、インストール済みパッケージの.binラッパーを実行しません。 pkg runは、現在のプロジェクトのpackage.jsonにあるscriptsだけを実行します。

シェル環境では、PATHに/work/node_modules/.binと./node_modules/.binが含まれています。 そのため、インストール済みパッケージの実行ファイルは、通常は名前だけで実行できます。

パッケージの実行ファイルを使用するには、シェルから生成されたラッパーを実行します。 例を示します。

/work > demo.js --help
/work > demo.js import sample.csv

必要に応じて、ラッパーのパスを直接指定して実行することもできます。

/work > ./node_modules/.bin/demo.js --help

同名のラッパーが存在する場合、インストールは続行し、警告を出力して競合するラッパーだけを生成しません。 パッケージ自体のインストールは成功しますが、その実行名だけを作成しません。

競合ファイルが他のインストール済みパッケージのラッパーの場合、警告に所有元のパッケージ名を含めます。 pkgの管理外の既存ファイルの場合は、単に既存のラッパーとして報告します。

ロックファイルの動作

通常のプロジェクトインストールでは、再現可能なインストールのため、pkgは解決したソースをpackage-lock.jsonに記録します。 GitHubパッケージでは、タグに基づくかブランチに基づくかも保存します。

例を示します。

  • github.com/acme/demo#tag=v1.1.0
  • github.com/acme/notags#branch=main

ロックファイルがある場合、pkg installはrefを再解決せず、記録済みのGitHub refを再利用します。

エラー報告

GitHub refを決定できない場合、pkgは2段階の失敗原因をまとめて表示します。 たとえば、タグの検索失敗と既定ブランチの検索失敗を、1つのメッセージで報告します。

pkg copy

GitHubリポジトリのパッケージを、node_modulesではなく、指定した対象ディレクトリに直接コピーします。 プロジェクトファイルをコピーした後、コピー先のプロジェクトルートと、存在する場合はcgi-binに依存関係をインストールします。

構文
pkg copy [options] <source> <dest>
オプション
  • -f, --force 対象ディレクトリが存在し、空でなくても続行します。
  • -h, --help ヘルプを表示します。

sourceには、pkg installと同じGitHubリポジトリの構文を使用する必要があります。 対応する形式は以下のとおりです。

  • github.com/<org>/<repo>
  • github.com/<org>/<repo>@<tag>
  • github.com/<org>/<repo>#tag=<tag>
  • github.com/<org>/<repo>#branch=<branch>

destは、現在の作業ディレクトリを基準に解釈するファイルシステムパスです。 対象ディレクトリがなければ、pkg copyが作成します。 対象ディレクトリが存在し、空でない場合は、--forceがなければ失敗します。

コピーの動作

pkg copyは、pkg installと同じGitHub refの解決規則を使用します。 明示的なタグやブランチがあればそれを使用し、なければ最新タグを解決します。タグがない場合は、リポジトリのdefault_branchを使用します。

リポジトリの内容は、<dest>に直接コピーされます。 pkg installと異なり、GitHubプロジェクトをnode_modules/github.com/...には配置しません。 元のディレクトリ構造は、対象ディレクトリ配下で保持されます。

コピー後、pkg copyは以下のプロジェクトルートを確認し、pkg installと同じインストール処理とロックファイルの動作で依存関係をインストールします。

  • <dest>/package.jsonがある場合は<dest>
  • <dest>/cgi-bin/package.jsonがある場合は<dest>/cgi-bin

そのため、コピーした各プロジェクトルートは、独自のnode_modulesとpackage-lock.jsonを個別に保持します。

使用例
/work > pkg copy github.com/acme/helloapp public/hello
Copying github.com/acme/helloapp#branch=main to /work/public/hello
Installing dependencies in /work/public/hello
Installing dependencies in /work/public/hello/cgi-bin

このコマンドを実行すると、以下のようになります。

  • リポジトリのファイルが/work/public/helloにコピーされます。
  • /work/public/hello/package.jsonの依存関係が、/work/public/hello/node_modulesにインストールされます。
  • /work/public/hello/cgi-bin/package.jsonがある場合、その依存関係が/work/public/hello/cgi-bin/node_modulesにインストールされます。

指定パスにプロジェクトツリーをそのまま配置し、GitHub refの解決とコピー先の依存関係のインストールをpkgに任せる場合は、pkg copyを使用します。

pkg run

package.jsonのscriptsを実行します。

構文
pkg run [options] <key> [...args]
オプション
  • -C, --dir <dir> 現在の作業ディレクトリではなく、指定したプロジェクトディレクトリを使用します。
  • -h, --help ヘルプを表示します。

pkg runは、スクリプトの実行前に、現在の作業ディレクトリを選択したプロジェクトディレクトリに変更します。 そのため、./main.jsなどの相対パスのコマンドは、パッケージディレクトリを基準に解釈します。

使用例

以下のマニフェストがある場合、

{
  "scripts": {
    "start": "./main.js --mode prod"
  }
}

次のように実行できます。

/work > pkg run start

追加引数は、スクリプトのコマンドラインの末尾に追加されます。

/work > pkg run start --verbose

実際に実行するコマンドラインは以下のとおりです。

./main.js --mode prod --verbose

pkg uninstall

依存関係と、その生成済みラッパーを削除します。

構文
pkg uninstall [options] <name>
オプション
  • -C, --dir <dir> 現在の作業ディレクトリではなく、指定したプロジェクトディレクトリを使用します。
  • -g, --global --dirを無視して、/work/node_modulesからパッケージを削除します。
  • -h, --help ヘルプを表示します。

pkg uninstallは、pkgが管理する以下の項目を削除します。

  • package.jsonの依存関係の項目
  • インストール済みパッケージに属するnode_modules/.binラッパー
  • インストール済みパッケージのディレクトリ
  • 依存関係が残らない場合のpackage-lock.json

pkg install -gでインストールしたパッケージを削除するには、pkg uninstall -gを使用します。

/work > pkg uninstall -g github.com/acme/demo
Removed github.com/acme/demo

インストール時にエイリアスの競合でラッパー生成をスキップした場合は、削除するラッパーがないことがあります。 また、pkg uninstallは、pkgの管理外のユーザー作成のnode_modules/.binファイルを削除しません。

使用例
/work > pkg uninstall github.com/acme/demo
Removed github.com/acme/demo

一般的な作業手順 

/work > pkg init demo-app
/work > pkg install github.com/acme/demo
/work > pkg install generic-pkg
/work > pkg run start

注意

  • パッケージ名なしのinstall、またはrunの実行には、有効なpackage.jsonが必要です。
  • pkg runは、POSIXシェルではなくJSHのコマンド解決でスクリプト行を実行します。
  • プロジェクト内の実行ファイルは、./tool.jsなどの相対パスで定義することを推奨します。
  • パッケージ開発者は、生成したラッパーがインストール先のパッケージディレクトリで実行されることを前提に、./bin/demo.jsなどの相対binパスを使用してください。
  • 実行名を明示的に指定する場合はオブジェクト形式のbinを、パッケージ名を実行名にする場合は文字列形式のbinを使用します。
  • GitHubリポジトリからインストールするには、ダウンロードした内容に有効なpackage.jsonが必要です。
最終更新日
サービスプロキシグローバル