# @andrei.fyi/devproxy

> > WIP

Latest version **1.1.0** (published 2026-09-23) · 0 weekly downloads

## Install

```sh
npm install @andrei.fyi/devproxy
pnpm add @andrei.fyi/devproxy
yarn add @andrei.fyi/devproxy
bun add @andrei.fyi/devproxy
```

Provides the command `devproxy`.

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2026-09-23 |
| First published | 2024-01-10 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=22 |
| Dependencies | 3 |
| Unpacked size | 23.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | andrei.fyi |

## Links

- npm: https://www.npmjs.com/package/@andrei.fyi/devproxy
- npm.io page: https://npm.io/package/@andrei.fyi/devproxy

## Dependencies (3)

- [zod](https://npm.io/package/zod.md) ^4.6.5
- [mockttp](https://npm.io/package/mockttp.md) ^4.6.3
- [gunsmith](https://npm.io/package/gunsmith.md) ^0.6.0

## Recent versions

- 1.1.0 (latest) — 2026-09-23
- 1.0.2 — 2025-02-14
- 1.0.1 — 2024-01-10
- 1.0.0 — 2024-01-10

## README

# devproxy

> WIP

A local HTTPS-intercepting proxy ([mockttp](https://github.com/httptoolkit/mockttp)) with user-defined request/response rewrite rules. It can also launch Chromium through the proxy.

Requires Node.js 22 or later.

## Usage

```
devproxy init                 write a starter config.js
devproxy check                validate config.js and list its rules
devproxy start                start the proxy for any browser or tool
devproxy start --browser      also launch Chromium through the proxy
devproxy start -o <url>       launch Chromium on a page (implies --browser)
devproxy ca                   show the CA certificate to trust, creating it if missing
```

Run `devproxy <command> --help` for each command's options. `start`, `check`,
and `ca` read `config.js` unless `-c <file>` names another file. `start` flags
override the corresponding config values.

The proxy signs intercepted HTTPS traffic with a local CA stored in `cert.pem`
and `cert.key` (paths set by the `ca` config key). Chromium launched by `start` trusts it
automatically. For other browsers or tools, import the certificate that
`devproxy ca` prints as a trusted authority. If the CA has expired, delete both
files and run `devproxy ca` to create a new one.

An invalid flag, a config file that is missing, fails to load, or does not match
the shape below, or an unusable CA exits with code 2 and names the problem.

## Configuration

```js
module.exports = {
  // launch Chromium when running `devproxy start` (default: false)
  browser: false,
  // page Chromium opens (default: "https://github.com/3rd/devproxy")
  open: "https://example.com",
  // chromium binary to launch (default: "google-chrome-stable")
  chromiumBinary: "google-chrome-stable",
  // proxy port (default: auto-assigned)
  port: 8080,
  // chromium profile directory (default: "<cwd>/devproxy_profile")
  profilePath: "./devproxy_profile",
  // launch chromium with --disable-web-security (default: false)
  disableWebSecurity: false,
  // CA used to intercept HTTPS, created on first use
  ca: {
    certPath: "cert.pem",
    keyPath: "cert.key",
  },
  // websockets pass through unless forwarded
  ws: {
    // apply the forward map (default: true)
    enabled: true,
    // optional hostname -> target forwarding
    forward: {
      "example.com": "ws://localhost:3000",
    },
  },
  rules: [
    {
      // match receives the intercepted request
      match: ({ url, method, headers }) => url.includes("example.com"),
      // optionally patch the outgoing request (return {} to leave it untouched)
      beforeRequest: (request) => ({
        url: request.url.replace("http://", "https://"),
      }),
      // optionally patch the upstream response
      beforeResponse: (request, response) => {
        // response: { id, statusCode, headers, body, ... }
        return { statusCode: 200, body: "patched" };
      },
    },
  ],
};
```

At most one rule may match a given request per phase (`beforeRequest` /
`beforeResponse`); if more than one rule matches, that request fails with a 500
response and the error is logged.

Rules receive [mockttp 4](https://github.com/httptoolkit/mockttp/releases/tag/v4.0.0)
request and response objects. Requests have no `hostname` field; read the host
from `new URL(request.url).hostname` or `request.headers.host`. Bodies are read
asynchronously, for example `await request.body.getText()`. Hooks set the
response status with `statusCode`.

---
_Source: https://npm.io/package/@andrei.fyi/devproxy · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._