Skip to content

Commit 85f88bf

Browse files
chimuraichimurai
committed
docs: fix v3 documentation
1 parent 040945c commit 85f88bf

12 files changed

+53
-149
lines changed

‎recipes/README.md

Lines changed: 0 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -1,106 +1,3 @@
11
# Recipes
22

33
Common usages of `http-proxy-middleware`.
4-
5-
# Configuration example
6-
7-
Overview of `http-proxy-middleware` specific options.
8-
9-
http-proxy-middleware uses Nodejitsu's [http-proxy](https://github.com/nodejitsu/node-http-proxy) to do the actual proxying. All of its [options](https://github.com/nodejitsu/node-http-proxy#options) are exposed via http-proxy-middleware's configuration object.
10-
11-
```javascript
12-
const { createProxyMiddleware } = require('http-proxy-middleware');
13-
const winston = require('winston');
14-
15-
/**
16-
* Proxy options
17-
*/
18-
const options = {
19-
// decide which path(s) should be proxied. (wildcards supported)
20-
pathFilter: '/api',
21-
22-
// hostname to the target server
23-
target: 'http://localhost:3000',
24-
25-
// set correct host headers for name-based virtual hosted sites
26-
changeOrigin: true,
27-
28-
// enable websocket proxying
29-
ws: true,
30-
31-
// additional request headers
32-
headers: {
33-
'x-powered-by': 'foobar',
34-
},
35-
36-
// rewrite paths
37-
pathRewrite: {
38-
'^/api/old-path': '/api/new-path', // rewrite path
39-
'^/api/remove/path': '/path', // remove base path
40-
},
41-
42-
// re-target based on the request's host header and/or path
43-
router: {
44-
// host[/path] : <new target>
45-
// /path : <new target>
46-
'integration.localhost:8000': 'http://localhost:8001', // host only
47-
'staging.localhost:8000': 'http://localhost:8002', // host only
48-
'localhost:8000/api': 'http://localhost:8003', // host + path
49-
'/rest': 'http://localhost:8004', // path only
50-
},
51-
52-
// control logging
53-
logLevel: 'silent',
54-
55-
// use a different lib for logging;
56-
// i.e., write logs to file or server
57-
logProvider: function (provider) {
58-
return winston;
59-
},
60-
61-
// subscribe to http-proxy's error event
62-
onError: function onError(err, req, res) {
63-
res.writeHead(500, { 'Content-Type': 'text/plain' });
64-
res.end('Something went wrong.');
65-
},
66-
67-
// subscribe to http-proxy's proxyRes event
68-
onProxyRes: function (proxyRes, req, res) {
69-
proxyRes.headers['x-added'] = 'foobar';
70-
delete proxyRes.headers['x-removed'];
71-
},
72-
73-
// subscribe to http-proxy's proxyReq event
74-
onProxyReq: function (proxyReq, req, res) {
75-
// add custom header to request
76-
proxyReq.setHeader('x-powered-by', 'foobar');
77-
},
78-
79-
/**
80-
* The following options are provided by Nodejitsu's http-proxy
81-
*/
82-
83-
// target
84-
// forward
85-
// agent
86-
// ssl
87-
// ws
88-
// xfwd
89-
// secure
90-
// toProxy
91-
// prependPath
92-
// ignorePath
93-
// localAddress
94-
// changeOrigin
95-
// auth
96-
// hostRewrite
97-
// autoRewrite
98-
// protocolRewrite
99-
// headers
100-
};
101-
102-
/**
103-
* Create the proxy middleware, so it can be used in a server.
104-
*/
105-
const apiProxy = createProxyMiddleware(options);
106-
```

‎recipes/context-matching.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# [BREAKING CHANGE]
2+
3+
This functionality is removed in v3.
4+
5+
The old "context matching" function has been moved to the [pathFilter](pathFilter.md) configuration property.
6+
7+
TL;DR
8+
9+
```js
10+
// v2
11+
createProxyMiddleware('/api', {
12+
target: 'http://localhost:3000',
13+
});
14+
15+
// v3
16+
createProxyMiddleware({
17+
target: 'http://localhost:3000',
18+
pathFilter: '/api',
19+
});
20+
```

‎recipes/corporate-proxy.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,5 +16,5 @@ const options = {
1616
agent: new HttpsProxyAgent(proxyServer),
1717
};
1818

19-
const apiProxy = createProxyMiddleware('/api', options);
19+
const apiProxy = createProxyMiddleware(options);
2020
```

‎recipes/https.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ All options are provided by [http-proxy](https://github.com/nodejitsu/node-http-
99
```javascript
1010
const { createProxyMiddleware } = require('http-proxy-middleware');
1111

12-
const apiProxy = createProxyMiddleware('/api', {
12+
const apiProxy = createProxyMiddleware({
1313
target: 'https://example.org',
1414
changeOrigin: true,
1515
});
@@ -21,7 +21,7 @@ const apiProxy = createProxyMiddleware('/api', {
2121
const fs = require('fs');
2222
const { createProxyMiddleware } = require('http-proxy-middleware');
2323

24-
const apiProxy = createProxyMiddleware('/api', {
24+
const apiProxy = createProxyMiddleware({
2525
target: {
2626
protocol: 'https:',
2727
host: 'example.org',

‎recipes/logLevel.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ const options = {
2222
logLevel: 'debug',
2323
};
2424

25-
const apiProxy = createProxyMiddleware('/api', options);
25+
const apiProxy = createProxyMiddleware(options);
2626
```
2727

2828
## Level: silent
@@ -37,5 +37,5 @@ const options = {
3737
logLevel: 'silent',
3838
};
3939

40-
const apiProxy = createProxyMiddleware('/api', options);
40+
const apiProxy = createProxyMiddleware(options);
4141
```

‎recipes/logProvider.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ const options = {
1515
},
1616
};
1717

18-
const apiProxy = createProxyMiddleware('/api', options);
18+
const apiProxy = createProxyMiddleware(options);
1919
```
2020

2121
## Winston
@@ -43,7 +43,7 @@ const options = {
4343
logProvider: logProvider,
4444
};
4545

46-
const apiProxy = createProxyMiddleware('/api', options);
46+
const apiProxy = createProxyMiddleware(options);
4747
```
4848

4949
# Winston Multi Transport
@@ -72,5 +72,5 @@ const options = {
7272
logProvider: logProvider,
7373
};
7474

75-
const apiProxy = createProxyMiddleware('/api', options);
75+
const apiProxy = createProxyMiddleware(options);
7676
```

‎recipes/pathFilter.md

Lines changed: 8 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,9 @@
11
# Path Filter
22

3-
Determine which requests should be proxied.
3+
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.
44

55
`pathFilter` is optional and is useful in cases where you are not able to use the regular [middleware mounting](http://expressjs.com/en/4x/api.html#app.use).
66

7-
The [RFC 3986 `path`](https://tools.ietf.org/html/rfc3986#section-3.3) is used for `pathFilter`.
8-
9-
```text
10-
foo://example.com:8042/over/there?name=ferret#nose
11-
\_/ \______________/\_________/ \_________/ \__/
12-
| | | | |
13-
scheme authority path query fragment
14-
```
15-
167
`http-proxy-middleware` offers several ways to do this:
178

189
- [Path](#path)
@@ -30,8 +21,8 @@ This will match paths starting with `/api`
3021
const { createProxyMiddleware } = require('http-proxy-middleware');
3122

3223
const apiProxy = createProxyMiddleware({
33-
pathFilter: '/api',
3424
target: 'http://localhost:3000',
25+
pathFilter: '/api',
3526
});
3627

3728
// `/api/foo/bar` -> `http://localhost:3000/api/foo/bar`
@@ -45,8 +36,8 @@ This will match paths starting with `/api` or `/rest`
4536
const { createProxyMiddleware } = require('http-proxy-middleware');
4637

4738
const apiProxy = createProxyMiddleware({
48-
pathFilter: ['/api', '/rest'],
4939
target: 'http://localhost:3000',
40+
pathFilter: ['/api', '/rest'],
5041
});
5142

5243
// `/api/foo/bar` -> `http://localhost:3000/api/foo/bar`
@@ -61,8 +52,8 @@ This will match paths starting with `/api/` and should also end with `.json`
6152
const { createProxyMiddleware } = require('http-proxy-middleware');
6253

6354
const apiProxy = createProxyMiddleware({
64-
pathFilter: '/api/**/*.json',
6555
target: 'http://localhost:3000',
56+
pathFilter: '/api/**/*.json',
6657
});
6758
```
6859

@@ -74,8 +65,8 @@ Multiple wildcards can be used.
7465
const { createProxyMiddleware } = require('http-proxy-middleware');
7566

7667
const apiProxy = createProxyMiddleware({
77-
pathFilter: ['/api/**/*.json', '/rest/**'],
7868
target: 'http://localhost:3000',
69+
pathFilter: ['/api/**/*.json', '/rest/**'],
7970
});
8071
```
8172

@@ -87,8 +78,8 @@ This example will create a proxy with globs.
8778
const { createProxyMiddleware } = require('http-proxy-middleware');
8879

8980
const apiProxy = createProxyMiddleware({
90-
pathFilter: ['foo/*.js', '!bar.js'],
9181
target: 'http://localhost:3000',
82+
pathFilter: ['foo/*.js', '!bar.js'],
9283
});
9384
```
9485

@@ -100,12 +91,12 @@ The request `pathname` and `req` object are provided to determine which requests
10091
```javascript
10192
const { createProxyMiddleware } = require('http-proxy-middleware');
10293

103-
const filter = function (pathname, req) {
94+
const pathFilter = function (pathname, req) {
10495
return pathname.match('^/api') && req.method === 'GET';
10596
};
10697

10798
const apiProxy = createProxyMiddleware({
108-
pathFilter: filter,
99+
pathFilter: pathFilter,
109100
target: 'http://localhost:3000',
110101
});
111102
```

‎recipes/pathRewrite.md

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,11 @@
22

33
Modify request paths before requests are send to the target.
44

5-
<!-- MarkdownTOC autolink=true bracket=round -->
6-
75
- [rewrite paths](#rewrite-paths)
86
- [remove paths](#remove-paths)
97
- [add paths](#add-paths)
108
- [custom rewrite function](#custom-rewrite-function)
119

12-
<!-- /MarkdownTOC -->
13-
1410
## rewrite paths
1511

1612
Rewrite paths
@@ -25,7 +21,7 @@ const options = {
2521
},
2622
};
2723

28-
const apiProxy = createProxyMiddleware('/api', options);
24+
const apiProxy = createProxyMiddleware(options);
2925

3026
// `/old/api/foo/bar` -> `http://localhost:3000/new/api/foo/bar`
3127
```
@@ -44,7 +40,7 @@ const options = {
4440
},
4541
};
4642

47-
const apiProxy = createProxyMiddleware('/api', options);
43+
const apiProxy = createProxyMiddleware(options);
4844

4945
// `/api/lorum/ipsum` -> `http://localhost:3000/lorum/ipsum`
5046
```
@@ -63,7 +59,7 @@ const options = {
6359
},
6460
};
6561

66-
const apiProxy = createProxyMiddleware('/api', options);
62+
const apiProxy = createProxyMiddleware(options);
6763

6864
// `/api/lorum/ipsum` -> `http://localhost:3000/extra/api/lorum/ipsum`
6965
```
@@ -86,7 +82,7 @@ const options = {
8682
pathRewrite: rewriteFn,
8783
};
8884

89-
const apiProxy = createProxyMiddleware('/api', options);
85+
const apiProxy = createProxyMiddleware(options);
9086

9187
// `/api/foo/lorum/ipsum` -> `http://localhost:3000/api/bar/lorum/ipsum`
9288
```

‎recipes/proxy-events.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ const onError = function (err, req, res) {
1616

1717
const options = { target: 'http://localhost:3000', onError: onError };
1818

19-
const apiProxy = createProxyMiddleware('/api', options);
19+
const apiProxy = createProxyMiddleware(options);
2020
```
2121

2222
## onProxyReq
@@ -33,7 +33,7 @@ const onProxyReq = function (proxyReq, req, res) {
3333

3434
const options = { target: 'http://localhost:3000', onProxyReq: onProxyReq };
3535

36-
const apiProxy = createProxyMiddleware('/api', options);
36+
const apiProxy = createProxyMiddleware(options);
3737
```
3838

3939
## onProxyReqWs
@@ -50,7 +50,7 @@ const onProxyReqWs = function (proxyReq, req, socket, options, head) {
5050

5151
const options = { target: 'http://localhost:3000', onProxyReqWs: onProxyReqWs };
5252

53-
const apiProxy = createProxyMiddleware('/api', options);
53+
const apiProxy = createProxyMiddleware(options);
5454
```
5555

5656
## onProxyRes
@@ -70,5 +70,5 @@ const onProxyRes = function (proxyRes, req, res) {
7070

7171
const options = { target: 'http://localhost:3000', onProxyRes: onProxyRes };
7272

73-
const apiProxy = createProxyMiddleware('/api', options);
73+
const apiProxy = createProxyMiddleware(options);
7474
```

‎recipes/router.md

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,9 @@
22

33
Allows you to route to a different `target` by using a table of a custom function.
44

5-
<!-- MarkdownTOC autolink=true bracket=round -->
6-
75
- [Custom router function](#custom-router-function)
86
- [Proxy Table](#proxy-table)
9-
10-
<!-- /MarkdownTOC -->
7+
- [Example](#example)
118

129
## Custom router function
1310

@@ -73,7 +70,7 @@ In the example above; all requests will be proxied to `http://localhost:8000`.
7370

7471
When request's `Host HTTP header` and/or `path` match a configuration in the proxyTable, they will be send to matching target.
7572

76-
```
73+
```text
7774
http://localhost:3000/lorum/ipsum -> http://localhost:8000/lorum/ipsum
7875
http://integration.localhost:3000/lorum/ipsum -> http://localhost:8001/lorum/ipsum
7976
http://staging.localhost:3000/rest/foo/bar -> http://localhost:8002/rest/foo/bar

0 commit comments

Comments
 (0)