【初心者向け】npmとnpxの違いとは？自作CLIツールをローカルで開発・実行する方法まで徹底解説

Node.jsを触っていると必ず出会うnpmとnpx。
「npm installはよく使うけど、npxって何が違うの？」
「なんとなく使っているけど、実はよく分かっていない…」
「自分で作ったツールをコマンドみたいに使ってみたいけど、npmに公開するのはハードルが高い…」

そんな風に感じていませんか？

npmとnpxは、セットで理解することでNode.jsのエコシステムを最大限に活用できる、非常に強力なツールです。そして何より、必ずしもnpmにパッケージを公開しなくても、ローカル環境で自作のツールを開発し、手軽に利用できることを知れば、開発の幅はぐっと広がります。

この記事では、npmとnpxの明確な違いから、実際に簡単なパッケージやCLIツールを自作し、ローカルで利用する手順まで、より実践的なコードを交えてステップバイステップで解説します。
Windowsユーザー向けの注意点も併せて紹介するので、OSを問わず安心して学べます。

---

この記事で得られること/できるようになること

• npmとnpxの役割の違いが明確に理解できる

• 実用的なnpmパッケージを自作し、ローカルの別プロジェクトから利用できるようになる

• コマンドライン引数を扱えるCLIツールを自作し、ローカルで実行できるようになる

• npm linkを使った効率的なローカル開発のテクニックが身につく

• Windows・macOS・Linuxの違いを理解した上で、自作パッケージを使いこなせる

---

npmとは？パッケージの「管理人」 👨‍💼

npm (Node Package Manager) は、その名の通りNode.jsのパッケージを管理するためのツールです。

主な役割は以下の3つです。

1. 依存関係の管理: プロジェクトで利用するライブラリ（パッケージ）をpackage.jsonファイルで管理します。npm installコマンドで必要なパッケージを一括でインストールできます。
2. ライブラリの導入: npm install <パッケージ名>で、世界中の開発者が公開している便利なパッケージを簡単に自分のプロジェクトに追加できます。
3. スクリプトの実行: package.jsonのscriptsに登録したコマンドをnpm run <スクリプト名>で実行できます。（例: npm run start, npm run build）

npmは、プロジェクトに必要な道具（パッケージ）を揃えたり、管理したり、決まった手順（スクリプト）を実行したりする、縁の下の力持ち、いわば「管理人」のような存在です。

---

npxとは？パッケージを「実行する」便利屋さん 🏃‍♂️

一方、npx (Node Package Executer) は、npm 5.2から同梱されるようになった、パッケージを実行するためのツールです。

npxの最大のメリットは、パッケージをローカルにインストールすることなく、一度きりで実行できる点にあります。

# create-react-appを一度きり実行してプロジェクトを作成
npx create-react-app my-app

npxの動作原理: npxはコマンドを実行する際、まずローカルのnode_modules/.binやシステムグローバルにコマンドが存在するか探します。見つからない場合、npmレジストリからパッケージを一時的にダウンロードし、実行可能な領域（キャッシュ）に配置して実行します。実行が終わると、そのパッケージは自動的にクリーンアップされるため、システムを汚すことがありません。

npxは、必要なときにサッと現れてコマンドを実行してくれる、いわば「便利な実行屋さん」です。たまにしか使わないコマンドや、お試して使ってみたいパッケージを実行するのに非常に役立ちます。

---

一目でわかる！npmとnpxの違い 比較表

項目	npm	npx
主な役割	パッケージ管理 (インストール、更新など)	パッケージ実行
公開必要？	必須ではない (ローカルでも可)	必須ではない (ローカルでも可)
主な利用場面	・プロジェクトの依存関係管理 ・ライブラリの導入	・CLIツールの実行 ・パッケージのお試し利用
コマンド例	npm install eslint	npx eslint .

---

実践編①：実用的なnpmパッケージを作ってローカルで使ってみよう

他のプロジェクトからrequireやimportで呼び出して使える、基本的なnpmパッケージの作り方を学びます。

ステップ1: パッケージの作成

作業用のディレクトリを作成し、その中でnpm initを実行します。今回はスコープ付きパッケージとして作成します。これにより、他のユーザーが公開しているパッケージ名との重複を避けることができます。

Bash

# ディレクトリを作成して移動
mkdir my-npm-package
cd my-npm-package

# スコープ付きでpackage.jsonを生成 (@your-usernameはご自身のnpmユーザ名に)
npm init --scope=@your-username -y

次に、パッケージの本体となるindex.jsファイルを作成します。単一の関数だけでなく、複数の機能を提供できるよう、オブジェクトをエクスポートするのが一般的です。

**index.js **

JavaScript

// 複数の関数や値をエクスポートする
module.exports = {
  sayHello: (name = 'world') => {
    console.log(`Hello, ${name} from my awesome npm package!`);
  },
  version: '1.0.0'
};

ステップ2: ローカルで利用する (npm link)

作成したパッケージを、公開せずに別のプロジェクトから利用してみましょう。

1. パッケージをリンク可能にする

   my-npm-packageディレクトリで以下のコマンドを実行し、PC内にこのパッケージへの「リンク」を作成します。

   Bash

   # my-npm-package ディレクトリで実行
   npm link
   

2. 利用側プロジェクトでリンクする

   次に、このパッケージを利用したい別のプロジェクト（例: my-app）で、先ほど作成したパッケージ（@your-username/my-npm-package）をリンクします。

   Bash

   # my-app ディレクトリを作成して移動
   mkdir ../my-app && cd ../my-app
   npm init -y
   
   # パッケージ名を指定してリンク
   npm link @your-username/my-npm-package
   

3. 動作確認

   my-appディレクトリにapp.jsを作成して、パッケージを呼び出してみましょう。

   app.js

   JavaScript

   // パッケージを読み込む
   const myPackage = require('@your-username/my-npm-package');
   
   // 実行！
   myPackage.sayHello('Developer');
   console.log('Package version:', myPackage.version);
   

   実行すると、無事にメッセージとバージョンが表示されるはずです。

   Bash

   node app.js
   #=> Hello, Developer from my awesome npm package!
   #=> Package version: 1.0.0
   

このようにnpm linkを使えば、パッケージをnpmに公開する前に、ローカルで徹底的にテスト・開発を進めることができます。

(任意) ステップ3: npmに公開する

Bash

# npmにログイン (初回のみ)
npm login

# パッケージを公開 (スコープ付きパッケージは--access publicが必要)
npm publish --access public

※注意: package.jsonのnameは世界中でユニーク（一意）である必要がありますが、スコープ付きにすることでその心配がほぼなくなります。

---

実践編②：引数が使えるnpxツールを作ってみよう

次に、npx my-cli-tool <引数>のように、引数を渡して動的に動作を変えられるCLIツールを作成します。

ステップ1: CLIツールの作成

作業用ディレクトリ（例: hello-cli）を作成し、npm initを実行します。

package.json

binフィールドに加え、authorやlicenseなど、公開を視野に入れた情報を記載します。

コード スニペット

{
  "name": "@your-username/hello-cli",
  "version": "1.0.0",
  "description": "A simple CLI tool example that greets the user.",
  "main": "index.js",
  "bin": {
    "hello-cli": "./index.js"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": ["cli", "example", "hello-world"],
  "author": "Your Name <your.email@example.com>",
  "license": "MIT"
}

次に、実行ファイル本体のindex.jsを作成します。

index.js

一行目の#!/usr/bin/env nodeは、このファイルがNode.jsで実行されるスクリプトであることを示す シバン (Shebang) です。

process.argvを使ってコマンドライン引数を取得し、処理を分岐させます。

JavaScript

#!/usr/bin/env node

// process.argvには実行パスやファイルパスが含まれるため、3番目以降が引数になる
const args = process.argv.slice(2);

if (args.length === 0) {
  console.log("Hello! This is my first CLI tool! Try passing your name as an argument.");
} else {
  // 最初の引数を名前として挨拶する
  console.log(`Hello, ${args[0]}! Welcome to my first CLI tool!`);
}

ステップ2: ローカルで実行する

これもnpm linkを使えば、公開せずにローカルでテストできます。

1. コマンドをリンクする

   hello-cliディレクトリでnpm linkを実行します。

   Bash

   # hello-cli ディレクトリで実行
   npm link
   

2. 実行してみる

   ターミナルで、設定したコマンド名（hello-cli）を引数あり・なしで実行してみましょう。

   Bash

   # 引数なし
   hello-cli
   #=> Hello! This is my first CLI tool! Try passing your name as an argument.
   
   # 引数あり
   hello-cli Gemini
   #=> Hello, Gemini! Welcome to my first CLI tool!
   

見事、引数によって動作が変わる自作コマンドが実行できました！

---

応用と注意点

💡 npm versionでスマートにバージョン管理

パッケージを更新したら、バージョン番号を更新するのが作法です。npm versionコマンドを使えば、package.jsonのバージョンを更新し、Gitのタグ付けまで自動で行えます。

Bash

# バージョンを0.0.1上げる (例: 1.0.0 -> 1.0.1)
npm version patch

# バージョンを0.1.0上げる (例: 1.0.1 -> 1.1.0)
npm version minor

# バージョンを1.0.0上げる (例: 1.1.0 -> 2.0.0)
npm version major

🔧 トラブルシューティングとTips

• （Unix系OS）実行できない？実行権限を確認しよう

  npm linkでコマンドが実行できない場合、スクリプトファイルに実行権限がない可能性があります。以下のコマンドで権限を付与してください。

  chmod +x index.js

• お片付けも忘れずに！npm unlink

  ローカルでの開発が終わったら、作成したリンクを解除してクリーンな状態に戻しましょう。

  Bash

  # 利用側プロジェクトで実行
  npm unlink @your-username/package-name
  
  # パッケージのディレクトリで実行（グローバルリンクを削除）
  npm unlink
  

• 公開する前に：セキュリティに関する注意点

  パッケージを公開する際は、タイポスクワッティング（有名パッケージに似た名前で悪意あるコードを公開する攻撃）を避けるため、パッケージ名は慎重に選びましょう。スコープ付きパッケージはこれを防ぐ有効な手段です。

---

💻 Windowsユーザー向け補足

npmやnpxの基本動作はWindowsでもmacOS/Linuxと同じですが、いくつか注意点があります。

1. シバン行（#!/usr/bin/env node）

• Unix系（macOS/Linux）: そのまま実行可能。

• Windows: 直接は使えませんが、npm link時に自動で.cmdファイルが生成され、コマンド呼び出し時にNode.js経由で実行されます。
  → Windowsユーザーは 意識せずそのままでOK です。

💡 シバン行ってなに？ プログラムの一番上に書く「このファイルはどのアプリで動かすのか」を伝える合図のことです。 Node.js の場合はこう書きます：

#!/usr/bin/env node

これがあると、ターミナルで

./index.js

のようにファイル名だけで実行できるようになります。 （「このファイルはNode.jsで動かしてね」と最初に宣言してあるイメージです）

• macOS/Linux → この合図がそのまま有効
• Windows → 直接は使われませんが、npm linkをすると裏で自動的に .cmd ファイルが作られるので、気にせずそのまま使えます

2. 実行権限（chmod）

• Unix系: chmod +x index.js で権限付与が必要。

• Windows: 不要。npm link時にPowerShell/CMD用の実行ファイルが生成されるため、そのまま実行できます。

3. パス区切り

• Windowsのファイルパスは \ ですが、Node.jsのコード内では/でも問題ありません。

• コマンド入力例は PowerShell を前提に書くとユーザーに親切です。

4. npxのキャッシュ場所

• macOS/Linux: ~/.npm/_npx/

• Windows: %AppData%\npm-cache\_npx
  キャッシュを使わず毎回新規実行したい場合は、以下のようにオプションを付けます。

npx --no-cache create-react-app my-app

---

応用と注意点

（元記事の内容に加え、Windows関連を補足）

• リンク解除トラブル: npm linkを多用するとリンクが残り、不具合の原因になることがあります。npm ls -g --depth=0で確認し、不要ならnpm unlinkで整理しましょう。

• セキュリティ注意: 公開前は依存関係を必ずチェック。特にWindowsではアンチウイルスソフトが動作をブロックすることもあるため、エラー時はセキュリティソフトのログを確認しましょう。

---

まとめ

• npmは、パッケージをインストール・管理する「管理人」

• npxは、パッケージを気軽に一時実行する「便利屋さん」

• npm linkを使えば、npmに公開しなくてもローカルで開発・利用できる

• WindowsでもmacOS/Linuxとほぼ同じ手順で動作（権限設定だけ不要）

• npx --no-cache や npm exec など最新のオプションも活用するとさらに便利

自作のCLIツールは、日々の定型作業を自動化し、開発効率を大きく高めます。ぜひこの記事を参考に、あなた専用の「便利屋さん」ツール作りに挑戦してみてください。