http-proxy-middleware 2.0.6 → 3.0.0-beta.1

package/README.md

@@ -1,25 +1,31 @@
 # http-proxy-middleware
 
-[![GitHub Workflow Status (branch)](https://img.shields.io/github/workflow/status/chimurai/http-proxy-middleware/CI/master?style=flat-square)](https://github.com/chimurai/http-proxy-middleware/actions?query=branch%3Amaster)
-[![Coveralls](https://img.shields.io/coveralls/chimurai/http-proxy-middleware.svg?style=flat-square)](https://coveralls.io/r/chimurai/http-proxy-middleware)
-[![dependency Status](https://snyk.io/test/npm/http-proxy-middleware/badge.svg?style=flat-square)](https://snyk.io/test/npm/http-proxy-middleware)
-[![npm](https://img.shields.io/npm/v/http-proxy-middleware?color=%23CC3534&style=flat-square)](https://www.npmjs.com/package/http-proxy-middleware)
+[![GitHub Workflow Status (with branch)](https://img.shields.io/github/actions/workflow/status/chimurai/http-proxy-middleware/ci.yml?branch=master&logo=github-actions&logoColor=white&style=flat-square)](https://github.com/chimurai/http-proxy-middleware/actions/workflows/ci.yml?query=branch%3Amaster)
+[![Coveralls](https://img.shields.io/coveralls/chimurai/http-proxy-middleware.svg?style=flat-square&logo=coveralls)](https://coveralls.io/r/chimurai/http-proxy-middleware)
+[![Snyk Vulnerabilities for GitHub Repo](https://img.shields.io/snyk/vulnerabilities/github/chimurai/http-proxy-middleware?logo=snyk&style=flat-square)](https://security.snyk.io/package/npm/http-proxy-middleware)
+[![npm](https://img.shields.io/npm/v/http-proxy-middleware?color=%23CC3534&style=flat-square&logo=npm)](https://www.npmjs.com/package/http-proxy-middleware)
 
-Node.js proxying made simple. Configure proxy middleware with ease for [connect](https://github.com/senchalabs/connect), [express](https://github.com/strongloop/express), [browser-sync](https://github.com/BrowserSync/browser-sync) and [many more](#compatible-servers).
+Node.js proxying made simple. Configure proxy middleware with ease for [connect](https://github.com/senchalabs/connect), [express](https://github.com/expressjs/express), [next.js](https://github.com/vercel/next.js) and [many more](#compatible-servers).
 
-Powered by the popular Nodejitsu [`http-proxy`](https://github.com/nodejitsu/node-http-proxy). [![GitHub stars](https://img.shields.io/github/stars/nodejitsu/node-http-proxy.svg?style=social&label=Star)](https://github.com/nodejitsu/node-http-proxy)
+Powered by the popular Nodejitsu [`http-proxy`](https://github.com/http-party/node-http-proxy). [![GitHub stars](https://img.shields.io/github/stars/http-party/node-http-proxy.svg?style=social&label=Star)](https://github.com/http-party/node-http-proxy)
 
 ## ⚠️ Note <!-- omit in toc -->
 
-This page is showing documentation for version v2.x.x ([release notes](https://github.com/chimurai/http-proxy-middleware/releases))
+This page is showing documentation for version v3.x.x ([release notes](https://github.com/chimurai/http-proxy-middleware/releases))
 
-If you're looking for v0.x documentation. Go to:
-https://github.com/chimurai/http-proxy-middleware/tree/v0.21.0#readme
+See [MIGRATION.md](https://github.com/chimurai/http-proxy-middleware/blob/master/MIGRATION.md) for details on how to migrate from v2.x.x to v3.x.x
+
+If you're looking for older documentation. Go to:
+
+- <https://github.com/chimurai/http-proxy-middleware/tree/v2.0.4#readme>
+- <https://github.com/chimurai/http-proxy-middleware/tree/v0.21.0#readme>
 
 ## TL;DR <!-- omit in toc -->
 
 Proxy `/api` requests to `http://www.example.org`
 
+:bulb: **Tip:** Set the option `changeOrigin` to `true` for [name-based virtual hosted sites](http://en.wikipedia.org/wiki/Virtual_hosting#Name-based).
+
 ```javascript
 // javascript
 
@@ -28,10 +34,18 @@ const { createProxyMiddleware } = require('http-proxy-middleware');
 
 const app = express();
 
-app.use('/api', createProxyMiddleware({ target: 'http://www.example.org', changeOrigin: true }));
+app.use(
+  '/api',
+  createProxyMiddleware({
+    target: 'http://www.example.org/secret',
+    changeOrigin: true,
+  })
+);
+
 app.listen(3000);
 
-// http://localhost:3000/api/foo/bar -> http://www.example.org/api/foo/bar
+// proxy and change the base path from "/api" to "/secret"
+// http://127.0.0.1:3000/api/foo/bar -> http://www.example.org/secret/foo/bar
 ```
 
 ```typescript
@@ -42,32 +56,45 @@ import { createProxyMiddleware, Filter, Options, RequestHandler } from 'http-pro
 
 const app = express();
 
-app.use('/api', createProxyMiddleware({ target: 'http://www.example.org', changeOrigin: true }));
+app.use(
+  '/api',
+  createProxyMiddleware({
+    target: 'http://www.example.org/api',
+    changeOrigin: true,
+  })
+);
+
 app.listen(3000);
 
-// http://localhost:3000/api/foo/bar -> http://www.example.org/api/foo/bar
+// proxy and keep the same base path "/api"
+// http://127.0.0.1:3000/api/foo/bar -> http://www.example.org/api/foo/bar
 ```
 
 _All_ `http-proxy` [options](https://github.com/nodejitsu/node-http-proxy#options) can be used, along with some extra `http-proxy-middleware` [options](#options).
 
-:bulb: **Tip:** Set the option `changeOrigin` to `true` for [name-based virtual hosted sites](http://en.wikipedia.org/wiki/Virtual_hosting#Name-based).
-
 ## Table of Contents <!-- omit in toc -->
 
+<!-- // spell-checker:disable -->
+
 - [Install](#install)
-- [Core concept](#core-concept)
-- [Example](#example)
-- [Context matching](#context-matching)
-- [Options](#options)
-  - [http-proxy-middleware options](#http-proxy-middleware-options)
-  - [http-proxy events](#http-proxy-events)
-  - [http-proxy options](#http-proxy-options)
-- [Shorthand](#shorthand)
+- [Basic usage](#basic-usage)
+- [Express Server Example](#express-server-example)
   - [app.use(path, proxy)](#appusepath-proxy)
+- [Options](#options)
+  - [`pathFilter` (string, \[\]string, glob, \[\]glob, function)](#pathfilter-string-string-glob-glob-function)
+  - [`pathRewrite` (object/function)](#pathrewrite-objectfunction)
+  - [`router` (object/function)](#router-objectfunction)
+  - [`plugins` (Array)](#plugins-array)
+  - [`ejectPlugins` (boolean) default: `false`](#ejectplugins-boolean-default-false)
+  - [`logger` (Object)](#logger-object)
+- [`http-proxy` events](#http-proxy-events)
+- [`http-proxy` options](#http-proxy-options)
 - [WebSocket](#websocket)
   - [External WebSocket upgrade](#external-websocket-upgrade)
 - [Intercept and manipulate requests](#intercept-and-manipulate-requests)
 - [Intercept and manipulate responses](#intercept-and-manipulate-responses)
+- [Node.js 17+: ECONNREFUSED issue with IPv6 and localhost (#705)](#nodejs-17-econnrefused-issue-with-ipv6-and-localhost-705)
+- [Debugging](#debugging)
 - [Working examples](#working-examples)
 - [Recipes](#recipes)
 - [Compatible servers](#compatible-servers)
@@ -75,45 +102,35 @@ _All_ `http-proxy` [options](https://github.com/nodejitsu/node-http-proxy#option
 - [Changelog](#changelog)
 - [License](#license)
 
+<!-- // spell-checker:enable -->
+
 ## Install
 
-```bash
-$ npm install --save-dev http-proxy-middleware
+```shell
+npm install --save-dev http-proxy-middleware
 ```
 
-## Core concept
-
-Proxy middleware configuration.
+## Basic usage
 
-#### createProxyMiddleware([context,] config)
+Create and configure a proxy middleware with: `createProxyMiddleware(config)`.
 
 ```javascript
 const { createProxyMiddleware } = require('http-proxy-middleware');
 
-const apiProxy = createProxyMiddleware('/api', { target: 'http://www.example.org' });
-//                                    \____/   \_____________________________/
-//                                      |                    |
-//                                    context             options
+const apiProxy = createProxyMiddleware({
+  target: 'http://www.example.org',
+  changeOrigin: true,
+});
 
 // 'apiProxy' is now ready to be used as middleware in a server.
 ```
 
-- **context**: Determine which requests should be proxied to the target host.
-  (more on [context matching](#context-matching))
 - **options.target**: target host to proxy to. _(protocol + host)_
+- **options.changeOrigin**: for virtual hosted sites
 
-(full list of [`http-proxy-middleware` configuration options](#options))
+- see full list of [`http-proxy-middleware` configuration options](#options)
 
-#### createProxyMiddleware(uri [, config])
-
-```javascript
-// shorthand syntax for the example above:
-const apiProxy = createProxyMiddleware('http://www.example.org/api');
-```
-
-More about the [shorthand configuration](#shorthand).
-
-## Example
+## Express Server Example
 
 An example with `express` server.
 
@@ -122,65 +139,68 @@ An example with `express` server.
 const express = require('express');
 const { createProxyMiddleware } = require('http-proxy-middleware');
 
-// proxy middleware options
-/** @type {import('http-proxy-middleware/dist/types').Options} */
-const options = {
-  target: 'http://www.example.org', // target host
-  changeOrigin: true, // needed for virtual hosted sites
-  ws: true, // proxy websockets
-  pathRewrite: {
-    '^/api/old-path': '/api/new-path', // rewrite path
-    '^/api/remove/path': '/path', // remove base path
-  },
-  router: {
-    // when request.headers.host == 'dev.localhost:3000',
-    // override target 'http://www.example.org' to 'http://localhost:8000'
-    'dev.localhost:3000': 'http://localhost:8000',
-  },
-};
+const app = express();
 
-// create the proxy (without context)
-const exampleProxy = createProxyMiddleware(options);
+// create the proxy
+/** @type {import('http-proxy-middleware/dist/types').RequestHandler<express.Request, express.Response>} */
+const exampleProxy = createProxyMiddleware({
+  target: 'http://www.example.org/api', // target host with the same base path
+  changeOrigin: true, // needed for virtual hosted sites
+});
 
 // mount `exampleProxy` in web server
-const app = express();
 app.use('/api', exampleProxy);
 app.listen(3000);
 ```
 
-## Context matching
-
-Providing an alternative way to decide which requests should be proxied; In case you are not able to use the server's [`path` parameter](http://expressjs.com/en/4x/api.html#app.use) to mount the proxy or when you need more flexibility.
+### app.use(path, proxy)
 
-[RFC 3986 `path`](https://tools.ietf.org/html/rfc3986#section-3.3) is used for context matching.
+If you want to use the server's `app.use` `path` parameter to match requests.
+Use `pathFilter` option to further include/exclude requests which you want to proxy.
 
-```ascii
-         foo://example.com:8042/over/there?name=ferret#nose
-         \_/   \______________/\_________/ \_________/ \__/
-          |           |            |            |        |
-       scheme     authority       path        query   fragment
+```javascript
+app.use(
+  createProxyMiddleware({
+    target: 'http://www.example.org/api',
+    changeOrigin: true,
+    pathFilter: '/api/proxy-only-this-path',
+  })
+);
 ```
 
+`app.use` documentation:
+
+- express: <http://expressjs.com/en/4x/api.html#app.use>
+- connect: <https://github.com/senchalabs/connect#mount-middleware>
+- polka: <https://github.com/lukeed/polka#usebase-fn>
+
+## Options
+
+http-proxy-middleware options:
+
+### `pathFilter` (string, []string, glob, []glob, function)
+
+Narrow down which requests should be proxied. The `path` used for filtering is the `request.url` pathname. In Express, this is the `path` relative to the mount-point of the proxy.
+
 - **path matching**
 
-  - `createProxyMiddleware({...})` - matches any path, all requests will be proxied.
-  - `createProxyMiddleware('/', {...})` - matches any path, all requests will be proxied.
-  - `createProxyMiddleware('/api', {...})` - matches paths starting with `/api`
+  - `createProxyMiddleware({...})` - matches any path, all requests will be proxied when `pathFilter` is not configured.
+  - `createProxyMiddleware({ pathFilter: '/api', ...})` - matches paths starting with `/api`
 
 - **multiple path matching**
 
-  - `createProxyMiddleware(['/api', '/ajax', '/someotherpath'], {...})`
+  - `createProxyMiddleware({ pathFilter: ['/api', '/ajax', '/someotherpath'], ...})`
 
 - **wildcard path matching**
 
   For fine-grained control you can use wildcard matching. Glob pattern matching is done by _micromatch_. Visit [micromatch](https://www.npmjs.com/package/micromatch) or [glob](https://www.npmjs.com/package/glob) for more globbing examples.
 
-  - `createProxyMiddleware('**', {...})` matches any path, all requests will be proxied.
-  - `createProxyMiddleware('**/*.html', {...})` matches any path which ends with `.html`
-  - `createProxyMiddleware('/*.html', {...})` matches paths directly under path-absolute
-  - `createProxyMiddleware('/api/**/*.html', {...})` matches requests ending with `.html` in the path of `/api`
-  - `createProxyMiddleware(['/api/**', '/ajax/**'], {...})` combine multiple patterns
-  - `createProxyMiddleware(['/api/**', '!**/bad.json'], {...})` exclusion
+  - `createProxyMiddleware({ pathFilter: '**', ...})` matches any path, all requests will be proxied.
+  - `createProxyMiddleware({ pathFilter: '**/*.html', ...})` matches any path which ends with `.html`
+  - `createProxyMiddleware({ pathFilter: '/*.html', ...})` matches paths directly under path-absolute
+  - `createProxyMiddleware({ pathFilter: '/api/**/*.html', ...})` matches requests ending with `.html` in the path of `/api`
+  - `createProxyMiddleware({ pathFilter: ['/api/**', '/ajax/**'], ...})` combine multiple patterns
+  - `createProxyMiddleware({ pathFilter: ['/api/**', '!**/bad.json'], ...})` exclusion
 
   **Note**: In multiple path matching, you cannot use string paths and wildcard paths together.
 
@@ -192,108 +212,154 @@ Providing an alternative way to decide which requests should be proxied; In case
   /**
    * @return {Boolean}
    */
-  const filter = function (pathname, req) {
-    return pathname.match('^/api') && req.method === 'GET';
+  const pathFilter = function (path, req) {
+    return path.match('^/api') && req.method === 'GET';
   };
 
-  const apiProxy = createProxyMiddleware(filter, {
+  const apiProxy = createProxyMiddleware({
     target: 'http://www.example.org',
+    pathFilter: pathFilter,
   });
   ```
 
-## Options
+### `pathRewrite` (object/function)
 
-### http-proxy-middleware options
+Rewrite target's url path. Object-keys will be used as _RegExp_ to match paths.
 
-- **option.pathRewrite**: object/function, rewrite target's url path. Object-keys will be used as _RegExp_ to match paths.
+```javascript
+// rewrite path
+pathRewrite: {'^/old/api' : '/new/api'}
 
-  ```javascript
-  // rewrite path
-  pathRewrite: {'^/old/api' : '/new/api'}
+// remove path
+pathRewrite: {'^/remove/api' : ''}
 
-  // remove path
-  pathRewrite: {'^/remove/api' : ''}
+// add base path
+pathRewrite: {'^/' : '/basepath/'}
 
-  // add base path
-  pathRewrite: {'^/' : '/basepath/'}
+// custom rewriting
+pathRewrite: function (path, req) { return path.replace('/api', '/base/api') }
 
-  // custom rewriting
-  pathRewrite: function (path, req) { return path.replace('/api', '/base/api') }
+// custom rewriting, returning Promise
+pathRewrite: async function (path, req) {
+  const should_add_something = await httpRequestToDecideSomething(path);
+  if (should_add_something) path += "something";
+  return path;
+}
+```
 
-  // custom rewriting, returning Promise
-  pathRewrite: async function (path, req) {
-    const should_add_something = await httpRequestToDecideSomething(path);
-    if (should_add_something) path += "something";
-    return path;
-  }
-  ```
+### `router` (object/function)
 
-- **option.router**: object/function, re-target `option.target` for specific requests.
+Re-target `option.target` for specific requests.
 
-  ```javascript
-  // Use `host` and/or `path` to match requests. First match will be used.
-  // The order of the configuration matters.
-  router: {
-      'integration.localhost:3000' : 'http://localhost:8001',  // host only
-      'staging.localhost:3000'     : 'http://localhost:8002',  // host only
-      'localhost:3000/api'         : 'http://localhost:8003',  // host + path
-      '/rest'                      : 'http://localhost:8004'   // path only
-  }
+```javascript
+// Use `host` and/or `path` to match requests. First match will be used.
+// The order of the configuration matters.
+router: {
+    'integration.localhost:3000' : 'http://127.0.0.1:8001',  // host only
+    'staging.localhost:3000'     : 'http://127.0.0.1:8002',  // host only
+    'localhost:3000/api'         : 'http://127.0.0.1:8003',  // host + path
+    '/rest'                      : 'http://127.0.0.1:8004'   // path only
+}
+
+// Custom router function (string target)
+router: function(req) {
+    return 'http://127.0.0.1:8004';
+}
+
+// Custom router function (target object)
+router: function(req) {
+    return {
+        protocol: 'https:', // The : is required
+        host: '127.0.0.1',
+        port: 8004
+    };
+}
 
-  // Custom router function (string target)
-  router: function(req) {
-      return 'http://localhost:8004';
-  }
+// Asynchronous router function which returns promise
+router: async function(req) {
+    const url = await doSomeIO();
+    return url;
+}
+```
 
-  // Custom router function (target object)
-  router: function(req) {
-      return {
-          protocol: 'https:', // The : is required
-          host: 'localhost',
-          port: 8004
-      };
-  }
+### `plugins` (Array)
 
-  // Asynchronous router function which returns promise
-  router: async function(req) {
-      const url = await doSomeIO();
-      return url;
-  }
-  ```
+```js
+const simpleRequestLogger = (proxyServer, options) => {
+  proxyServer.on('proxyReq', (proxyReq, req, res) => {
+    console.log(`[HPM] [${req.method}] ${req.url}`); // outputs: [HPM] GET /users
+  });
+},
 
-- **option.logLevel**: string, ['debug', 'info', 'warn', 'error', 'silent']. Default: `'info'`
+const config = {
+  target: `http://example.org`,
+  changeOrigin: true,
+  plugins: [simpleRequestLogger],
+};
+```
 
-- **option.logProvider**: function, modify or replace log provider. Default: `console`.
+### `ejectPlugins` (boolean) default: `false`
 
-  ```javascript
-  // simple replace
-  function logProvider(provider) {
-    // replace the default console log provider.
-    return require('winston');
-  }
-  ```
+If you're not satisfied with the pre-configured plugins, you can eject them by configuring `ejectPlugins: true`.
 
-  ```javascript
-  // verbose replacement
-  function logProvider(provider) {
-    const logger = new (require('winston').Logger)();
-
-    const myCustomProvider = {
-      log: logger.log,
-      debug: logger.debug,
-      info: logger.info,
-      warn: logger.warn,
-      error: logger.error,
-    };
-    return myCustomProvider;
-  }
-  ```
+NOTE: register your own error handlers to prevent server from crashing.
+
+```js
+// eject default plugins and manually add them back
+
+const {
+  debugProxyErrorsPlugin, // subscribe to proxy errors to prevent server from crashing
+  loggerPlugin, // log proxy events to a logger (ie. console)
+  errorResponsePlugin, // return 5xx response on proxy error
+  proxyEventsPlugin, // implements the "on:" option
+} = require('http-proxy-middleware');
+
+createProxyMiddleware({
+  target: `http://example.org`,
+  changeOrigin: true,
+  ejectPlugins: true,
+  plugins: [debugProxyErrorsPlugin, loggerPlugin, errorResponsePlugin, proxyEventsPlugin],
+});
+```
+
+### `logger` (Object)
+
+Configure a logger to output information from http-proxy-middleware: ie. `console`, `winston`, `pino`, `bunyan`, `log4js`, etc...
+
+Only `info`, `warn`, `error` are used internally for compatibility across different loggers.
+
+If you use `winston`, make sure to enable interpolation: <https://github.com/winstonjs/winston#string-interpolation>
+
+See also logger recipes ([recipes/logger.md](https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/logger.md)) for more details.
 
-### http-proxy events
+```javascript
+createProxyMiddleware({
+  logger: console,
+});
+```
 
-Subscribe to [http-proxy events](https://github.com/nodejitsu/node-http-proxy#listening-for-proxy-events):
+## `http-proxy` events
+
+Subscribe to [http-proxy events](https://github.com/nodejitsu/node-http-proxy#listening-for-proxy-events) with the `on` option:
+
+```js
+createProxyMiddleware({
+  target: 'http://www.example.org',
+  on: {
+    proxyReq: (proxyReq, req, res) => {
+      /* handle proxyReq */
+    },
+    proxyRes: (proxyRes, req, res) => {
+      /* handle proxyRes */
+    },
+    error: (err, req, res) => {
+      /* handle error */
+    },
+  },
+});
+```
 
-- **option.onError**: function, subscribe to http-proxy's `error` event for custom error handling.
+- **option.on.error**: function, subscribe to http-proxy's `error` event for custom error handling.
 
   ```javascript
   function onError(err, req, res, target) {
@@ -304,7 +370,7 @@ Subscribe to [http-proxy events](https://github.com/nodejitsu/node-http-proxy#li
   }
   ```
 
-- **option.onProxyRes**: function, subscribe to http-proxy's `proxyRes` event.
+- **option.on.proxyRes**: function, subscribe to http-proxy's `proxyRes` event.
 
   ```javascript
   function onProxyRes(proxyRes, req, res) {
@@ -313,7 +379,7 @@ Subscribe to [http-proxy events](https://github.com/nodejitsu/node-http-proxy#li
   }
   ```
 
-- **option.onProxyReq**: function, subscribe to http-proxy's `proxyReq` event.
+- **option.on.proxyReq**: function, subscribe to http-proxy's `proxyReq` event.
 
   ```javascript
   function onProxyReq(proxyReq, req, res) {
@@ -323,7 +389,7 @@ Subscribe to [http-proxy events](https://github.com/nodejitsu/node-http-proxy#li
   }
   ```
 
-- **option.onProxyReqWs**: function, subscribe to http-proxy's `proxyReqWs` event.
+- **option.on.proxyReqWs**: function, subscribe to http-proxy's `proxyReqWs` event.
 
   ```javascript
   function onProxyReqWs(proxyReq, req, socket, options, head) {
@@ -332,7 +398,7 @@ Subscribe to [http-proxy events](https://github.com/nodejitsu/node-http-proxy#li
   }
   ```
 
-- **option.onOpen**: function, subscribe to http-proxy's `open` event.
+- **option.on.open**: function, subscribe to http-proxy's `open` event.
 
   ```javascript
   function onOpen(proxySocket) {
@@ -341,7 +407,7 @@ Subscribe to [http-proxy events](https://github.com/nodejitsu/node-http-proxy#li
   }
   ```
 
-- **option.onClose**: function, subscribe to http-proxy's `close` event.
+- **option.on.close**: function, subscribe to http-proxy's `close` event.
 
   ```javascript
   function onClose(res, socket, head) {
@@ -350,7 +416,7 @@ Subscribe to [http-proxy events](https://github.com/nodejitsu/node-http-proxy#li
   }
   ```
 
-### http-proxy options
+## `http-proxy` options
 
 The following options are provided by the underlying [http-proxy](https://github.com/nodejitsu/node-http-proxy#options) library.
 
@@ -372,10 +438,12 @@ The following options are provided by the underlying [http-proxy](https://github
 - **option.autoRewrite**: rewrites the location host/port on (301/302/307/308) redirects based on requested host/port. Default: false.
 - **option.protocolRewrite**: rewrites the location protocol on (301/302/307/308) redirects to 'http' or 'https'. Default: null.
 - **option.cookieDomainRewrite**: rewrites domain of `set-cookie` headers. Possible values:
+
   - `false` (default): disable cookie rewriting
   - String: new domain, for example `cookieDomainRewrite: "new.domain"`. To remove the domain, use `cookieDomainRewrite: ""`.
   - Object: mapping of domains to new domains, use `"*"` to match all domains.  
     For example keep one domain unchanged, rewrite one domain and remove other domains:
+
     ```json
     cookieDomainRewrite: {
       "unchanged.domain": "unchanged.domain",
@@ -383,11 +451,14 @@ The following options are provided by the underlying [http-proxy](https://github
       "*": ""
     }
     ```
+
 - **option.cookiePathRewrite**: rewrites path of `set-cookie` headers. Possible values:
+
   - `false` (default): disable cookie rewriting
   - String: new path, for example `cookiePathRewrite: "/newPath/"`. To remove the path, use `cookiePathRewrite: ""`. To set path to root use `cookiePathRewrite: "/"`.
   - Object: mapping of paths to new paths, use `"*"` to match all paths.
     For example, to keep one path unchanged, rewrite one path and remove other paths:
+
     ```json
     cookiePathRewrite: {
       "/unchanged.path/": "/unchanged.path/",
@@ -395,6 +466,7 @@ The following options are provided by the underlying [http-proxy](https://github
       "*": ""
     }
     ```
+
 - **option.headers**: object, adds [request headers](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#Request_fields). (Example: `{host:'www.example.org'}`)
 - **option.proxyTimeout**: timeout (in millis) when proxy receives no response from target
 - **option.timeout**: timeout (in millis) for incoming requests
@@ -414,7 +486,7 @@ The following options are provided by the underlying [http-proxy](https://github
       req,
       res,
       {
-        target: 'http://localhost:4003/',
+        target: 'http://127.0.0.1:4003/',
         buffer: streamify(req.rawBody),
       },
       next
@@ -422,47 +494,11 @@ The following options are provided by the underlying [http-proxy](https://github
   };
   ```
 
-## Shorthand
-
-Use the shorthand syntax when verbose configuration is not needed. The `context` and `option.target` will be automatically configured when shorthand is used. Options can still be used if needed.
-
-```javascript
-createProxyMiddleware('http://www.example.org:8000/api');
-// createProxyMiddleware('/api', {target: 'http://www.example.org:8000'});
-
-createProxyMiddleware('http://www.example.org:8000/api/books/*/**.json');
-// createProxyMiddleware('/api/books/*/**.json', {target: 'http://www.example.org:8000'});
-
-createProxyMiddleware('http://www.example.org:8000/api', { changeOrigin: true });
-// createProxyMiddleware('/api', {target: 'http://www.example.org:8000', changeOrigin: true});
-```
-
-### app.use(path, proxy)
-
-If you want to use the server's `app.use` `path` parameter to match requests;
-Create and mount the proxy without the http-proxy-middleware `context` parameter:
-
-```javascript
-app.use('/api', createProxyMiddleware({ target: 'http://www.example.org', changeOrigin: true }));
-```
-
-`app.use` documentation:
-
-- express: http://expressjs.com/en/4x/api.html#app.use
-- connect: https://github.com/senchalabs/connect#mount-middleware
-- polka: https://github.com/lukeed/polka#usebase-fn
-
 ## WebSocket
 
 ```javascript
 // verbose api
-createProxyMiddleware('/', { target: 'http://echo.websocket.org', ws: true });
-
-// shorthand
-createProxyMiddleware('http://echo.websocket.org', { ws: true });
-
-// shorter shorthand
-createProxyMiddleware('ws://echo.websocket.org');
+createProxyMiddleware({ pathFilter: '/', target: 'http://echo.websocket.org', ws: true });
 ```
 
 ### External WebSocket upgrade
@@ -470,7 +506,7 @@ createProxyMiddleware('ws://echo.websocket.org');
 In the previous WebSocket examples, http-proxy-middleware relies on a initial http request in order to listen to the http `upgrade` event. If you need to proxy WebSockets without the initial http request, you can subscribe to the server's http `upgrade` event manually.
 
 ```javascript
-const wsProxy = createProxyMiddleware('ws://echo.websocket.org', { changeOrigin: true });
+const wsProxy = createProxyMiddleware({ target: 'ws://echo.websocket.org', changeOrigin: true });
 
 const app = express();
 app.use(wsProxy);
@@ -494,7 +530,9 @@ const proxy = createProxyMiddleware({
   /**
    * Fix bodyParser
    **/
-  onProxyReq: fixRequestBody,
+  on: {
+    proxyReq: fixRequestBody,
+  },
 });
 ```
 
@@ -522,15 +560,45 @@ const proxy = createProxyMiddleware({
   /**
    * Intercept response and replace 'Hello' with 'Goodbye'
    **/
-  onProxyRes: responseInterceptor(async (responseBuffer, proxyRes, req, res) => {
-    const response = responseBuffer.toString('utf8'); // convert buffer to string
-    return response.replace('Hello', 'Goodbye'); // manipulate response and return the result
-  }),
+  on: {
+    proxyRes: responseInterceptor(async (responseBuffer, proxyRes, req, res) => {
+      const response = responseBuffer.toString('utf8'); // convert buffer to string
+      return response.replace('Hello', 'Goodbye'); // manipulate response and return the result
+    }),
+  },
 });
 ```
 
 Check out [interception recipes](https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/response-interceptor.md#readme) for more examples.
 
+## Node.js 17+: ECONNREFUSED issue with IPv6 and localhost ([#705](https://github.com/chimurai/http-proxy-middleware/issues/705))
+
+Node.js 17+ no longer prefers IPv4 over IPv6 for DNS lookups.
+E.g. It's **not** guaranteed that `localhost` will be resolved to `127.0.0.1` – it might just as well be `::1` (or some other IP address).
+
+If your target server only accepts IPv4 connections, trying to proxy to `localhost` will fail if resolved to `::1` (IPv6).
+
+Ways to solve it:
+
+- Change `target: "http://localhost"` to `target: "http://127.0.0.1"` (IPv4).
+- Change the target server to (also) accept IPv6 connections.
+- Add this flag when running `node`: `node index.js --dns-result-order=ipv4first`. (Not recommended.)
+
+> Note: There’s a thing called [Happy Eyeballs](https://en.wikipedia.org/wiki/Happy_Eyeballs) which means connecting to both IPv4 and IPv6 in parallel, which Node.js doesn’t have, but explains why for example `curl` can connect.
+
+## Debugging
+
+Configure the `DEBUG` environment variable enable debug logging.
+
+See [`debug`](https://github.com/debug-js/debug#readme) project for more options.
+
+```shell
+DEBUG=http-proxy-middleware* node server.js
+
+$ http-proxy-middleware proxy created +0ms
+$ http-proxy-middleware proxying request to target: 'http://www.example.org' +359ms
+```
+
 ## Working examples
 
 View and play around with [working examples](https://github.com/chimurai/http-proxy-middleware/tree/master/examples).
@@ -551,6 +619,7 @@ View the [recipes](https://github.com/chimurai/http-proxy-middleware/tree/master
 
 - [connect](https://www.npmjs.com/package/connect)
 - [express](https://www.npmjs.com/package/express)
+- [next.js](https://www.npmjs.com/package/next)
 - [fastify](https://www.npmjs.com/package/fastify)
 - [browser-sync](https://www.npmjs.com/package/browser-sync)
 - [lite-server](https://www.npmjs.com/package/lite-server)