# Use npm install

> Instala paquetes npm como dayjs o lodash en la carpeta Application Support de Proxyman y úsalos en Proxyman Scripting con require().

## Usar paquetes npm en Proxyman Scripting {#use-npm-packages-in-proxyman-scripting}

Proxyman Scripting admite `require()` para paquetes npm compatibles instalados en la carpeta Application Support de Proxyman. Así, un script puede reutilizar utilidades populares de JavaScript en lugar de escribir a mano la lógica habitual.

Esta función mantiene la misma palabra clave `require()` que Proxyman ya usa para las librerías integradas y los addons de usuario. Las importaciones existentes, como `@libs`, `@addons`, `@users`, los archivos JSON, los archivos de texto y los archivos locales, siguen funcionando.

### Instalar un paquete {#install-a-package}

Abre Terminal e instala los paquetes en la carpeta Application Support de Proxyman:

* Instala `dayjs`

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

Después de la instalación, el paquete debería estar en:

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

### Usar un paquete en un script {#use-a-package-in-a-script}

Usa el nombre del paquete con `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;
}
```

### Ejemplos {#examples}

#### Dar formato a una fecha con `dayjs` {#format-a-date-with-dayjs}

Instalar:

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

Script:

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

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

#### Normalizar texto con `lodash` {#normalize-text-with-lodash}

Instalar:

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

Script:

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

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

#### Validar entradas con `validator` {#validate-input-with-validator}

Instalar:

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

Script:

```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;
}
```

#### Crear slugs con `slugify` {#create-slugs-with-slugify}

Instalar:

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

Script:

```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;
}
```

#### Codificar datos con `js-base64` {#encode-data-with-js-base64}

Instalar:

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

Script:

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

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

#### Decodificar entidades HTML con `he` {#decode-html-entities-with-he}

Instalar:

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

Script:

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

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

### Compatibilidad {#compatibility}

Proxyman ejecuta los scripts con JavaScriptCore, no con Node.js. Los paquetes npm funcionan mejor cuando son JavaScript puro y compatibles con CommonJS.

Compatible:

* Paquetes CommonJS cargados con `require("package-name")`
* Puntos de entrada del paquete definidos en `package.json`, como `main` y `exports` simples
* Importaciones relativas dentro de los paquetes instalados, como `require("./helper")`
* Archivos JSON requeridos por los paquetes

No compatible:

* Módulos integrados de Node.js como `fs`, `path`, `crypto`, `http` o `child_process`
* Addons nativos `.node`
* Paquetes que necesitan un entorno completo de Node.js
* Paquetes solo ESM que no pueden cargarse con `require()` de CommonJS

### Librerías nativas de Node.js {#nodejs-native-libraries}

Proxyman Scripting no se ejecuta dentro del entorno de Node.js. Solo usa Node/npm como herramienta para instalar paquetes y, después, carga los archivos JavaScript compatibles con JavaScriptCore.

Por eso, las librerías nativas de Node.js no son compatibles:

* `require("fs")`, `require("path")`, `require("crypto")` y otros módulos integrados de Node.js están bloqueados.
* `require("node:fs")` y las subrutas integradas, como `require("fs/promises")`, están bloqueadas.
* Los addons nativos de C/C++ compilados como archivos `.node` están bloqueados.
* Los paquetes que llaman a APIs específicas de Node, como `process.dlopen`, APIs del sistema de archivos, sockets de red o procesos hijos, no funcionarán.

Ejemplos de paquetes que normalmente no funcionan en Proxyman Scripting:

* `sharp`
* `sqlite3`
* `bcrypt`
* `canvas`
* `puppeteer`
* Paquetes que requieren `fs`, `path`, `crypto`, `http`, `https`, `net` o `child_process`

En su lugar, usa paquetes de JavaScript puro o paquetes que ofrezcan una build de CommonJS compatible con el navegador.

### Solución de problemas {#troubleshooting}

Si `require("dayjs")` u otro paquete devuelve `undefined`, comprueba que el paquete esté instalado en la carpeta esperada:

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

Si falta `node_modules`, vuelve a instalarlo con `--prefix .`:

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

La opción `--prefix .` es importante, porque de lo contrario npm podría subir hasta un `package.json` superior e instalar los paquetes fuera de la carpeta de Proxyman.