# npm install の使い方

> dayjs や lodash などの npm パッケージを Proxyman の Application Support フォルダにインストールし、Proxyman Scripting で require() を使って利用する方法を解説します。

## Proxyman Scripting で npm パッケージを使う {#use-npm-packages-in-proxyman-scripting}

Proxyman Scripting は、Proxyman の Application Support フォルダにインストールされた、互換性のある npm パッケージを `require()` で読み込めます。これにより、よく使われる JavaScript のユーティリティを、同じロジックを一から書き直すことなくスクリプトで再利用できます。

この機能では、Proxyman が組み込みライブラリやユーザーアドオンで使っているのと同じ `require()` キーワードを使います。既存の `@libs`、`@addons`、`@users`、JSON ファイル、テキストファイル、ローカルファイルのインポートも、引き続き動作します。

### パッケージをインストールする {#install-a-package}

ターミナルを開き、Proxyman の Application Support フォルダにパッケージをインストールします：

* `dayjs` をインストール

```bash
$ cd "$HOME/Library/Application Support/com.proxyman.NSProxy"
$ npm install --prefix . dayjs --ignore-scripts --no-audit --no-fund
```

インストールが完了すると、次のフォルダにパッケージが作成されているはずです：

```
~/Library/Application Support/com.proxyman.NSProxy/node_modules
```

### スクリプトでパッケージを使う {#use-a-package-in-a-script}

パッケージ名を指定して `require()` を使います：

```javascript
const dayjs = require("dayjs");

async function onRequest(context, url, request) {
  const formattedDate = dayjs("2026-05-05T13:00:00Z").format("YYYY-MM-DD");
  request.headers["X-Proxyman-Dayjs"] = formattedDate;
  return request;
}
```

### 使用例 {#examples}

#### `dayjs` で日付をフォーマットする {#format-a-date-with-dayjs}

インストール：

```bash
cd "$HOME/Library/Application Support/com.proxyman.NSProxy" && npm install --prefix . dayjs --ignore-scripts --no-audit --no-fund
```

スクリプト：

```javascript
const dayjs = require("dayjs");

async function onRequest(context, url, request) {
  request.headers["X-Request-Date"] = dayjs().format("YYYY-MM-DD");
  return request;
}
```

#### `lodash` でテキストを正規化する {#normalize-text-with-lodash}

インストール：

```bash
cd "$HOME/Library/Application Support/com.proxyman.NSProxy" && npm install --prefix . lodash --ignore-scripts --no-audit --no-fund
```

スクリプト：

```javascript
const _ = require("lodash");

async function onRequest(context, url, request) {
  const label = _.kebabCase("Hello Proxyman Scripts");
  request.headers["X-Proxyman-Label"] = label;
  return request;
}
```

#### `validator` で入力値を検証する {#validate-input-with-validator}

インストール：

```bash
cd "$HOME/Library/Application Support/com.proxyman.NSProxy" && npm install --prefix . validator --ignore-scripts --no-audit --no-fund
```

スクリプト：

```javascript
const validator = require("validator");

async function onRequest(context, url, request) {
  const email = new URL(url).searchParams.get("email") || "";
  request.headers["X-Email-Is-Valid"] = validator.isEmail(email) ? "true" : "false";
  return request;
}
```

#### `slugify` でスラッグを作成する {#create-slugs-with-slugify}

インストール：

```bash
cd "$HOME/Library/Application Support/com.proxyman.NSProxy" && npm install --prefix . slugify --ignore-scripts --no-audit --no-fund
```

スクリプト：

```javascript
const slugify = require("slugify");

async function onRequest(context, url, request) {
  const title = new URL(url).searchParams.get("title") || "Hello Proxyman";
  request.headers["X-Proxyman-Slug"] = slugify(title, { lower: true });
  return request;
}
```

#### `js-base64` でデータをエンコードする {#encode-data-with-js-base64}

インストール：

```bash
cd "$HOME/Library/Application Support/com.proxyman.NSProxy" && npm install --prefix . js-base64 --ignore-scripts --no-audit --no-fund
```

スクリプト：

```javascript
const { Base64 } = require("js-base64");

async function onResponse(context, url, request, response) {
  response.headers["X-Proxyman-Encoded"] = Base64.encode("Proxyman");
  return response;
}
```

#### `he` で HTML エンティティをデコードする {#decode-html-entities-with-he}

インストール：

```bash
cd "$HOME/Library/Application Support/com.proxyman.NSProxy" && npm install --prefix . he --ignore-scripts --no-audit --no-fund
```

スクリプト：

```javascript
const he = require("he");

async function onResponse(context, url, request, response) {
  response.headers["X-Decoded-Title"] = he.decode("Proxyman & Scripting");
  return response;
}
```

### 互換性 {#compatibility}

Proxyman のスクリプトは Node.js ではなく JavaScriptCore で実行されます。npm パッケージは、純粋な JavaScript で CommonJS と互換性がある場合に最もよく動作します。

対応しているもの：

* `require("package-name")` で読み込む CommonJS パッケージ
* `main` や単純な `exports` など、`package.json` のパッケージエントリポイント
* インストールしたパッケージ内での相対パスによるインポート（`require("./helper")` など）
* パッケージが読み込む JSON ファイル

非対応のもの：

* `fs`、`path`、`crypto`、`http`、`child_process` などの Node.js 組み込みモジュール
* ネイティブの `.node` アドオン
* Node.js のランタイム全体を必要とするパッケージ
* CommonJS の `require()` で読み込めない ESM のみのパッケージ

### Node.js のネイティブライブラリ {#nodejs-native-libraries}

Proxyman Scripting は Node.js ランタイム内では実行されません。Node/npm はパッケージのインストールツールとしてのみ使われ、その後、互換性のある JavaScript ファイルが JavaScriptCore で読み込まれます。

そのため、Node.js のネイティブライブラリは対応していません：

* `require("fs")`、`require("path")`、`require("crypto")` など、その他の Node.js 組み込みモジュールはブロックされます。
* `require("node:fs")` や、`require("fs/promises")` などの組み込みサブパスはブロックされます。
* `.node` ファイルとしてコンパイルされたネイティブ C/C++ アドオンはブロックされます。
* `process.dlopen`、ファイルシステム API、ネットワークソケット、子プロセスなど、Node.js 固有の API を呼び出すパッケージは動作しません。

Proxyman Scripting では動作しないことが多いパッケージの例：

* `sharp`
* `sqlite3`
* `bcrypt`
* `canvas`
* `puppeteer`
* `fs`、`path`、`crypto`、`http`、`https`、`net`、`child_process` を必要とするパッケージ

代わりに、純粋な JavaScript パッケージや、CommonJS でブラウザに対応したビルドを提供しているパッケージを使ってください。

### トラブルシューティング {#troubleshooting}

`require("dayjs")` などのパッケージが `undefined` を返す場合は、パッケージが想定どおりのフォルダにインストールされているか確認してください：

```bash
ls "$HOME/Library/Application Support/com.proxyman.NSProxy/node_modules"
```

`node_modules` が見つからない場合は、`--prefix .` を指定して再度インストールしてください：

```bash
cd "$HOME/Library/Application Support/com.proxyman.NSProxy" && npm install --prefix . dayjs --ignore-scripts --no-audit --no-fund
```

`--prefix .` オプションは重要です。指定しないと npm が親フォルダの `package.json` を探してしまい、Proxyman のフォルダ外にパッケージがインストールされることがあるためです。