v3.0.0

[chimurai]

V3

Version 3 introduced some breaking changes in order to have a better DX, TypeScript support and extensibility with the new plugin system.

Installation

Install the v3 with npm install http-proxy-middleware@latest or yarn add http-proxy-middleware@latest

Migration Guide

Follow MIGRATION.md to transition from v2 to v3.

You can use legacyCreateProxyMiddleware as intermediate step. It will tell you run-time which configurations need to migrated:

const { legacyCreateProxyMiddleware: createProxyMiddleware } = require('http-proxy-middleware');

Notable changes

⚠️ Proxy behaviour change

When the proxy is mounted on a server path (ie. app.use('/basepath', router)); basePath is not included anymore when proxying a request when you configure the target with just protocol + hostname. (#731)

To include the basePath, you'll have to include the basePath in the target. (See example below)
To rewrite the basePath, you can simply change the basePath in the target. (You can still use pathRewrite to change to the req.url)

// proxy '/user' => 'http://www.example.org/user'

- app.use('/user', proxy({ target: 'http://www.example.org' }));
+ app.use('/user', proxy({ target: 'http://www.example.org/user' }));

NOTE: Proxy behaviour hasn't changed when you've mounted the proxy in the root path. ie. app.use(proxy)

🚀 Improved support for different server types

import type { Request, Response } from 'express';

createProxyMiddleware<Request, Response>{
  target: config.env.TARGET_URL,
  changeOrigin: true,
  pathRewrite: (path, req) => req.originalUrl,
}

📝 Improved logger

Configuring a logger has been simplified with improved log output:

createProxyMiddleware({
-  logLevel: 'info',
-  logProvider: (provider) => require('winston'),
+  logger: console,
})

[HPM] GET /users -> http://jsonplaceholder.typicode.com/users/ [200]

🐛 Debugging

Enable debugging to see more the verbose internal logging for troubleshooting:

DEBUG=http-proxy-middleware* node app.js

🔌 Plugins

Access low-level http-proxy and create reusable functionality:

createProxyMiddleware({
  plugins: [(proxyServer) => {
     // low-level access to http-proxy
  }]
})

http-proxy-middleware ships with some default plugins for the most common use cases. Use ejectPlugins to opt-out.

📃 Other improvements

• Next.js and native http server support (refactor: use node http base types [BREAKING CHANGE] #730)
• new plugins configuration for better extensibility (feat(plugins): add support for plugins #732)
• previously hardcoded features are now written as plugins
• http-proxy-middleware ships with some default plugins, use ejectPlugins to opt-out (feat(ejectPlugins): skip registering default plugins #750)
• improved debugging with DEBUG=http-proxy-middleware* (feat(debug): improve troubleshooting #752)
• new logger. Simplified with better logging (refactor: logging [BREAKING CHANGE] #749)
• use legacyCreateProxyMiddleware to help transitioning from v2 to v3 (feat(legacyCreateProxyMiddleware): show migration tips #756)

Change log

• chore(deps): update micromatch to 4.0.5
• chore(package): bump devDependencies
• feat(legacyCreateProxyMiddleware): show migration tips (#756)
• feat(legacyCreateProxyMiddleware): adapter with v2 behavior (#754)
• docs(proxy events): fix new syntax (#753)
• feat(debug): improve troubleshooting (#752)
• test(path-rewriter): improve coverage (#751)
• feat(ejectPlugins): skip registering default plugins (#750)
• refactor: logging [BREAKING CHANGE] (#749)
• refactor(handlers): refactor to plugins [BREAKING CHANGE] (#745)
• feat(plugins): add support for plugins (#732)
• docs: fix v3 documentation
• fix: server mounting [BREAKING CHANGE] (#731)
• test(fixRequestBody): fix broken test
• refactor: use node http base types [BREAKING CHANGE] (#730) (special thanks: @cdaringe & @devanshj)
• feat(option): refactor context to pathFilter option [BREAKING CHANGE] (#722)
• feat: remove shorthand usage [BREAKING CHANGE] (#716)

Full Changelog:

• v2.0.6...v3.0.0-beta.0
• v2.0.6...v3.0.0-beta.1

---

This discussion was created from the release v3.0.0-beta.0.

[anthonyalayo]

Thanks for the beta @chimurai! Is there any expected timeframe for this to become official?

[chimurai]

Currently finalising #720.
Which depends on: DefinitelyTyped/DefinitelyTyped#64314

Hope to ship it soon 🤞

[chimurai]

Not in v3. Can you create feature ticket with context and motivation for this feature?

[caugner]

First of all, thanks for creating and maintaining this useful middleware! 🙌

We have just started using http-proxy-middleware v2 in a Cloud Function that powers https://developer.mozilla.org/ behind the CDN, but we're using the same middleware instance for multiple (base) paths for convenience. So I'm wondering if there is or will be a way in v3 to opt-in to including the basePath in the proxied request? If I understand it correctly, with v3 this would no longer be possible?

Here's an example of what we're doing:

import { createProxyMiddleware, fixRequestBody } from "http-proxy-middleware";
import { Router } from "express";

const proxyApi = createProxyMiddleware({
  target: `https://api.example.com/`,
  changeOrigin: true,
  autoRewrite: true,
  xfwd: true,
  onProxyReq: fixRequestBody,
});

const router = Router();
router.all(["/api/*, "/admin-api/*", "/events/fxa/*", "/users/fxa/*"], proxyApi);

[chimurai]

Thanks @caugner. Nice to hear how it's used at https://developer.mozilla.org. 😊

If I understood you correctly. (Not sure how your router is mounted from your example...)
Assuming your router is mounted on basePath "/mybasepath", ie. app.use("/mybasepath", router);

You can just add the basePath to your target.
Example: target: https://api.example.com/mybasepath,

import { createProxyMiddleware, fixRequestBody } from "http-proxy-middleware";
import { Router } from "express";

const proxyApi = createProxyMiddleware({
  target: `https://api.example.com/mybasepath`,     //  << include basePath in target
  changeOrigin: true,
  autoRewrite: true,
  xfwd: true,
  on: {
    proxyReq: fixRequestBody,                       // v3 change
  }
});

const router = Router();
router.all(["/api/*, "/admin-api/*", "/events/fxa/*", "/users/fxa/*"], proxyApi);

By default the option prependPath is true.

If you include the basePath in your target. All proxied requests will have the basePath prepended in their proxied path.

In the example above /api/* will be proxied to https://api.example.com/mybasepath/api/*
Assuming your router is mounted with: app.use("/mybasepath", router)

This is one of the breaking changes in v3 and hopefully you should get the same behaviour with a slight change in your proxy configuration. 🙏

[caugner]

Oh, thank you so much for enlightening me! This looks like we're not actually affected by the breaking change, because in our configuration the basePath is effectively empty.

The example you used in the "Notable changes" section made me think that the new behavior would cause /api/example and /admin-api/example to be both proxied to https://api.example.com/example, but if I understand you correctly the matching path part (/api/, /admin-api/ etc.) continues to be forwarded to the target unless prependPath is set to false.

To avoid confusion, maybe it's worth refining the changelog to make it more clear that this use case is unaffected?

[chimurai]

Thanks for the feedback!

Updated "Notable changes". Hopefully it'll bit more clear now.

[caugner]

Thank you, the section is clear now. 🙌

[Zertz]

For what it's worth, we had issues with express-http-proxy so we replaced it with http-proxy-middleware@3.0.0-beta.1 and it has been flawless out of the box 👌

We proxy requests based on user-specific parameters and the router(req) { /* ... */ } approach gives us exactly the flexibility we needed.

[maxgfr]

Thanks for the release http-proxy-middleware@3.0.0-beta.1, it fixed an issue with latest version of next in dev mode due to HMR. It works perfectly together 🚀

[chimurai]

Not in v3. Probably won't add async onProxyReq, since it is a direct functionality of the underlying http-proxy library

[barryhagan]

I upgraded to v3 in an Express 4.x and Typescript environment. The only feedback I'd give is that is seems odd to have typed the RequestHandler return the way it is with void | Promise<void> instead of just Promise<void> since that is what it actually is.

This is what I'm doing in v3 for Express 4.x which uses (req,res,next) => void handlers:

  const proxyHandler = createProxyMiddleware({
    target: 'https://localhost:4444',
  });

  app.use('/proxy', (req, res, next) => {
    proxyHandler(req, res, next)?.catch(next);
  });

Obviously not a big deal, I'm only adding ? to assert I have a Promise, but it is misleading to suggest it could ever be void.

[chimurai]

Thanks for catching this.

http-proxy-middleware/src/http-proxy-middleware.ts

Line 42 in 5b10650

public middleware: RequestHandler = (async (req, res, next?) => {

Should be indeed just Promise<void>.

Created a PR: #980

[arberosmani]

I just updated to v3. The types Request and Response seems not to be exported anymore:

 import {createProxyMiddleware} from "http-proxy-middleware";
 import http from "http";
-import {Request, Response} from "http-proxy-middleware/dist/types";

 export const lrFrontendConnector = createProxyMiddleware({
   target: 'http://localhost:3001',
   changeOrigin: true,

-  onProxyRes: (proxyRes: http.IncomingMessage, req: Request, res: Response) => {
-    proxyRes.statusCode = 200;
+  on: {
+    proxyRes: (proxyRes: http.IncomingMessage, req: http.IncomingMessage, res: http.ServerResponse) => {
+      proxyRes.statusCode = 200;
+    }
   }
 });

[chimurai]

Request and Response type are removed in v3. (which were basically hardcoded express' Request and Response types)
If you were using a different server, like connect or next.js, it would conflict with the express types.

With generics you can now provide the Request and Response type from your server library :

import type { Request, Response } from 'express';

createProxyMiddleware<Request, Response>{
  target: config.env.TARGET_URL,
  changeOrigin: true,
  pathRewrite: (path, req) => req.originalUrl,
}

I'll update the docs to make this more clear.

[spartanhooah]

I'm trying to migrate a project from v1 to v3. I dropped in legacyCreateProxyMiddleware in place of createProxyMiddleware, but I don't see any runtime logs related to migrating. Is there something I need to set up to get those to show up?

[chimurai]

did you try to configure the logger?

legacyCreateProxyMiddleware({
  logger: console,
});

[spartanhooah]

Ah, that got the logs to show up. I addressed the one thing it mentioned (migrating to the on object), but our proxy is still broken. We'll keep poking at it. Thanks for the quick response.