# 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}

Terminal을 열고 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")`)
* 패키지가 `require`하는 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`를 `require`하는 패키지

대신 순수 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 폴더 바깥의 패키지를 설치할 수 있기 때문입니다.