Connect Proxy Middleware

Common errors

• TypeError: app.use is not a function

  cause The `app` object is not a Connect application instance or is an incompatible framework (e.g., a vanilla Express app without Connect compatibility shims).
  fix Ensure you are using `connect` for your application and correctly initializing it, e.g., `const connect = require('connect'); const app = connect();`. If using Express, you should use an Express-compatible proxy middleware like `http-proxy-middleware`.

• ReferenceError: require is not defined

  cause Attempting to use `require()` in a JavaScript file that is being treated as an ES Module (e.g., within a project with `"type": "module"` in `package.json`).
  fix This package is CommonJS-only. If your project is ESM, you need to either use a modern, ESM-compatible proxy middleware or configure your build system/Node.js environment to treat the file as CommonJS.

• Requests not being proxied, or incorrect target URL/path.

  cause Incorrect configuration of the `url.parse()` options or the `route` property, leading to the proxy targeting the wrong host/path or not activating for the desired incoming requests.
  fix Carefully check the `url.parse()` options, ensuring the `protocol`, `hostname`, and `pathname` are correctly specified for your target. Also, verify that the middleware's mount path in `app.use('/api', proxy(...))` matches the intended proxy route prefix for incoming requests.

Warnings

• breaking This package is effectively abandoned and has not been updated since 2016. It is built for older versions of Connect and Node.js and is not compatible with modern web frameworks or current Node.js versions (e.g., Express 4+, Node.js >=10).
  Fix: Migrate to actively maintained proxy solutions such as `http-proxy-middleware` for Express/Connect or `node-http-proxy` for lower-level control, which support modern Node.js and frameworks.
• gotcha As an abandoned package, `proxy-middleware` does not receive security updates. Using it in production environments is a significant security risk, potentially exposing applications to known vulnerabilities in Node.js core, HTTP/HTTPS modules, or its dependency chain.
  Fix: Replace with a currently maintained and regularly updated proxy library. Regularly audit your dependencies for security vulnerabilities.
• gotcha The `url.parse()` method, used extensively in the examples, is deprecated in recent Node.js versions. While still functional, it signals an outdated API approach which may lead to issues or removal in future Node.js releases.
  Fix: In modern Node.js, `new URL()` is the recommended alternative for URL parsing. However, direct replacement within this package's API is not straightforward; migration to a modern proxy library is the best long-term solution.
• breaking This package is CommonJS-only and does not provide native ES Module support. Attempting to `import` it in an ESM context will result in runtime errors like `ReferenceError: require is not defined`.
  Fix: Must be used with `require()` in a CommonJS module. For projects using ES Modules, it is highly recommended to use a modern, ESM-compatible proxy middleware instead.

Install

• npm install proxy-middleware npm
• yarn add proxy-middleware yarn
• pnpm add proxy-middleware pnpm

Imports

• proxy
  wrong:

  import proxy from 'proxy-middleware';

  correct:

  const proxy = require('proxy-middleware');

  This package is CommonJS-only. Attempting to import it using ES module syntax will lead to runtime errors.
• proxyMiddleware(options)
  wrong:

  import { proxyMiddleware } from 'proxy-middleware';

  correct:

  const proxy = require('proxy-middleware');
  // ... then use proxy(options)

  The main functionality is exposed as the default CommonJS export (a function). There are no named exports.

Quickstart

Demonstrates setting up a Connect server with `proxy-middleware` to forward requests from `/api` to a local target server running on port 9000.

const connect = require('connect');
const url = require('url');
const proxy = require('proxy-middleware');
const http = require('http');

// Create a simple target server for the proxy to forward requests to
const targetServer = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end(`Hello from target server! Path: ${req.url}\n`);
});

targetServer.listen(9000, () => {
  console.log('Target server listening on http://localhost:9000');

  const app = connect();

  // Configure the proxy route: requests to /api will go to http://localhost:9000/target-prefix
  const proxyOptions = url.parse('http://localhost:9000/target-prefix');
  app.use('/api', proxy(proxyOptions));

  // Add a simple route to the main app to show it's working
  app.use('/', (req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('Main app. Try /api/hello to see the proxy in action.\n');
  });

  const port = 3000;
  http.createServer(app).listen(port, () => {
    console.log(`Connect server running on http://localhost:${port}`);
    console.log('Test with:');
    console.log(`  curl http://localhost:${port}/`);
    console.log(`  curl http://localhost:${port}/api/some/path`);
    console.log(`Expected output for /api/some/path: "Hello from target server! Path: /target-prefix/some/path"`);
  });
});