Skip to main content

Use npm install

Install npm packages such as dayjs or lodash into Proxyman's Application Support folder and use them in Proxyman Scripting with require().

Use npm Packages in Proxyman Scripting​

Proxyman Scripting supports require() for compatible npm packages installed in Proxyman's Application Support folder. This lets a script reuse popular JavaScript utilities instead of rewriting common logic by hand.

This feature keeps the same require() keyword that Proxyman already uses for built-in libraries and user add-ons. Existing imports such as @libs, @addons, @users, JSON files, text files, and local files continue to work.

Install a package​

Open Terminal and install packages into Proxyman's Application Support folder:

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

After installation, the package should exist in:

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

Use a package in a script​

Use the package name with require():

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​

Format a date with dayjs​

Install:

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

Script:

const dayjs = require("dayjs");

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

Normalize text with lodash​

Install:

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

Script:

const _ = require("lodash");

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

Validate input with validator​

Install:

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

Script:

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

Create slugs with slugify​

Install:

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

Script:

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

Encode data with js-base64​

Install:

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

Script:

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

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

Decode HTML entities with he​

Install:

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

Script:

const he = require("he");

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

Compatibility​

Proxyman runs scripts with JavaScriptCore, not Node.js. npm packages work best when they are pure JavaScript and compatible with CommonJS.

Supported:

  • CommonJS packages loaded with require("package-name")
  • Package entry points from package.json such as main and simple exports
  • Relative imports used inside installed packages, such as require("./helper")
  • JSON files required by packages

Not supported:

  • Node.js built-in modules such as fs, path, crypto, http, or child_process
  • Native .node add-ons
  • Packages that require a full Node.js runtime
  • ESM-only packages that cannot be loaded with CommonJS require()

Node.js native libraries​

Proxyman Scripting does not run inside the Node.js runtime. It only uses Node/npm as a package installation tool, then loads compatible JavaScript files with JavaScriptCore.

Because of that, Node.js native libraries are not supported:

  • require("fs"), require("path"), require("crypto"), and other Node.js built-in modules are blocked.
  • require("node:fs") and built-in subpaths such as require("fs/promises") are blocked.
  • Native C/C++ add-ons compiled as .node files are blocked.
  • Packages that call Node-specific APIs such as process.dlopen, filesystem APIs, network sockets, or child processes will not work.

Examples of packages that usually do not work in Proxyman Scripting:

  • sharp
  • sqlite3
  • bcrypt
  • canvas
  • puppeteer
  • packages that require fs, path, crypto, http, https, net, or child_process

Use pure JavaScript packages or packages that provide a CommonJS browser-compatible build instead.

Troubleshooting​

If require("dayjs") or another package returns undefined, check that the package is installed in the expected folder:

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

If node_modules is missing, install again with --prefix .:

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

The --prefix . option is important because npm may otherwise walk up to a parent package.json and install packages outside Proxyman's folder.

Last updated on