Guide · Open source

How to use http-proxy-middleware: install and proxy /api requests

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

http-proxy-middleware is a Node.js library that you mount inside a web server such as Express or Connect. It forwards incoming requests to another server, such as a backend API, which is a common way to avoid cross-origin problems during development. This guide shows you how to install it, set up a basic proxy, and use the options for path filtering, path rewriting, routing and WebSockets.

http-proxy-middlewarechimurai/http-proxy-middleware · ★ 11.1k · MIT Install options & downloads

Quick start

1Install the package. Run npm install --save-dev http-proxy-middleware in your project.
2Import createProxyMiddleware. Import createProxyMiddleware from http-proxy-middleware in your server file.
3Set the target. Pass the backend address as target, including protocol and host, and set changeOrigin to true for virtual hosted sites.
4Mount the proxy. Call app.use with the path to proxy, such as /api, and the proxy middleware.
5Add filters or rewrites. Use pathFilter to narrow requests and pathRewrite to change the path sent to the backend.
6Start the server and test. Start your server and send a request to the mounted path to confirm it reaches the target.

Install http-proxy-middleware with npm

The package is installed through npm and requires Node.js. The project's README recommends installing it as a dev dependency, since it is typically used while developing a frontend app.

npm install --save-dev http-proxy-middleware

Create a basic proxy in an Express server

Create the proxy with createProxyMiddleware, passing a target. Then mount it on a path with app.use. The target option takes the protocol and host, and changeOrigin should be set to true for name-based virtual hosted sites.

With the example below, a request to http://127.0.0.1:3000/api/foo/bar is forwarded to http://www.example.org/api/foo/bar, keeping the same base path.

target: the target host to proxy to, including protocol and host.
changeOrigin: set to true for virtual hosted sites.

import express from 'express';
import { createProxyMiddleware } from 'http-proxy-middleware';

const app = express();

const apiProxy = createProxyMiddleware({
  target: 'http://www.example.org/api',
  changeOrigin: true,
});

app.use('/api', apiProxy);
app.listen(3000);

Filter which requests get proxied with pathFilter

The app.use path already narrows requests, but pathFilter gives finer control. The path it checks is the request URL pathname, relative to the mount point in Express. If pathFilter is not set, all requests are proxied.

Filters can be a string, an array of strings, a glob pattern, or a custom function. Wildcard matching uses micromatch, and you can exclude paths with a leading !. String paths and wildcard paths cannot be mixed in one multiple-path list.

Single path: pathFilter: '/api' matches paths starting with /api.
Multiple paths: pathFilter: ['/api', '/ajax', '/someotherpath'].
Glob: pathFilter: '/api/**/*.html' matches .html requests under /api.
Exclusion: pathFilter: ['/api/**', '!**/bad.json'].
Custom function: receives path and req and returns a Boolean.

Rewrite paths with pathRewrite

Use pathRewrite when the backend expects a different path from the one the frontend calls. Object keys are used as regular expressions to match paths. You can also pass a function, which may return a Promise.

Rewrite: '^/old/api' to '/new/api' replaces one prefix with another.
Remove: '^/remove/api' to '' strips the prefix.
Add: '^/' to '/basepath/' adds a base path.
Function: receives path, req, res and options. res is undefined in WebSocket upgrade flows.

pathRewrite: {'^/remove/api' : ''}

Route requests to different targets with router

The router option re-targets requests to a different target based on host and/or path. The first match is used, so the order of entries matters.

The README example uses hosts with ports and paths as keys, mapping each to a different local target. Use it when one proxy must send traffic to several backends.

Keys can match a host only, for example integration.localhost:3000.
Keys can match a host and path, for example localhost:3000/api.
Values are the target URLs, for example http://127.0.0.1:8001.

Proxy WebSocket connections

The library supports WebSocket proxying alongside HTTP proxying, which helps when your dev server uses live connections. The README has a dedicated WebSocket section and an External WebSocket upgrade section that cover how upgrade requests are handled. Read those sections for the exact setup, since they go beyond what this guide covers.

Debug and troubleshoot the proxy

The README has a Debugging section and a Node.js 17+ section on an ECONNREFUSED issue with IPv6 and localhost (issue #705). If requests to localhost fail on newer Node.js versions, check that section first.

Options that are not listed in the library's own options can be passed through, since all httpxy options can be used alongside the extra http-proxy-middleware options.

Check that target includes the correct protocol and host.
Set changeOrigin to true when the backend uses name-based virtual hosting.
Check the ECONNREFUSED section if you use Node.js 17 or newer with localhost.

What people use it for

Forward /api requests from an Express or Next.js dev server to a backend API running on another address.
Send different hosts or paths to different local services using the router option.
Rewrite a frontend path prefix so it matches the backend's route structure.
Proxy WebSocket connections alongside HTTP requests in a development setup.

Frequently asked questions

Is http-proxy-middleware free to use?

Yes. The project is licensed under MIT, a permissive open-source licence. Check the LICENSE in the repository if you need the exact terms for your project.

What are the requirements for http-proxy-middleware?

The package is installed with npm and requires Node.js. It is built for the Node.js ecosystem and must be mounted inside a Node.js server.

Does http-proxy-middleware work with Express?

Yes. The README includes an Express example that mounts the proxy with app.use. It also lists connect, next.js, hono and other compatible servers.

What is the difference between http-proxy-middleware and http-proxy?

http-proxy-middleware is powered by httpxy, which the README describes as a maintained version of http-proxy. Other comparable projects include http-proxy-3 and express-http-proxy.

Why does my proxy fail on localhost with Node.js 17 or newer?

The README has a section on an ECONNREFUSED issue with IPv6 and localhost, referenced as issue #705. Read that section for the explanation and the suggested fix.

Can I use http-proxy-middleware without writing Node.js code?

No. The library must be mounted inside a Node.js server. If you need a standalone reverse proxy with no Node.js code, this library is not the right choice.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

http-proxy-middleware suits Node.js developers who run an Express, Connect or Next.js dev server and need to forward API or WebSocket traffic to a backend. It is less suited to teams that want a standalone reverse proxy with no code or that do not use Node.js, so for those cases a different tool is a better fit.

Install options & downloads