A proxy event handler for h3, using proxyRequest
.
- Powered by built-in proxyRequest of h3.
- Support http(s) proxy via some simple configurations.
- Support logs via consola.
- Support Typescript.
# pnpm
$ pnpm add h3-proxy
# yarn
$ yarn add h3-proxy
# npm
$ npm i h3-proxy
import { createServer } from 'node:http'
import { createApp, eventHandler, toNodeListener } from 'h3'
import { createProxyEventHandler } from 'h3-proxy'
const app = createApp()
const port = process.env.PORT || 3000
// Define proxy event handler
const proxyEventHandler = createProxyEventHandler({
target: `https://127.0.0.1:${port}`,
pathRewrite: {
'^/api': '',
},
pathFilter: ['/api/**'],
// enableLogger: true
})
// Add proxy middlewares
app.use(eventHandler(proxyEventHandler))
// Define api routes
app.use(
'/test',
eventHandler(() => 'Hello world!')
)
createServer(toNodeListener(app)).listen(port)
import { createServer } from 'node:http'
import { createApp, eventHandler, toNodeListener } from 'h3'
import { createProxyEventHandler } from 'h3-proxy'
const app = createApp()
const port = process.env.PORT || 3000
// proxy to `https://127.0.0.1:${port}`
const proxyEventHandler1 = createProxyEventHandler({
target: `https://127.0.0.1:${port}`, // https://127.0.0.1:3000
pathRewrite: {
'^/api': '',
},
pathFilter: ['/api/**'],
})
// proxy to other target
const proxyEventHandler2 = createProxyEventHandler({
target: `https://127.0.0.1:${port}/other-api-module`,
pathRewrite: {
'^/other-api': '',
},
pathFilter: ['/other-api/**'],
})
// Add proxy middlewares
app.use(eventHandler(proxyEventHandler1))
app.use(eventHandler(proxyEventHandler2))
// Define api routes
app.use(
'/test',
eventHandler(() => 'Hello world!')
)
app.use(
'/other-api-module/some/path',
eventHandler(() => 'Hello other API module!')
)
createServer(toNodeListener(app)).listen(port)
- For
proxyEventHandler1
, The result of proxy request is as follows:
/api/test
-> https://127.0.0.1:3000/test
- For
proxyEventHandler2
, The result of proxy request is as follows:
/other-api/some/path
-> https://127.0.0.1:3000/other-api-module/some/path
const proxyEventHandler = createProxyEventHandler([
{
// options
},
{
// other proxy target options
}
])
Create a h3
event handler that can handle proxy requests.
const proxyEventHandler = createProxyEventHandler({
// options
})
Key | Type | Required | Default value | Description |
---|---|---|---|---|
target |
string |
true |
undefined |
Proxy target address, including protocol, host and port. url string to be parsed with the node:url module |
pathFilter | string, string[], glob, glob[], Function |
false |
undefined |
Narrow down which requests should be proxied. |
pathRewrite | object/Function |
false |
undefined |
Rewrite target's url path. Object-keys will be used as RegExp to match paths. |
configureProxyRequest | Function |
false |
undefined |
Configure options of proxyRequest . More details see built-in util proxyRequest of h3 |
proxyRequestMethod (Added in v1.13.0) |
Function |
false |
undefined |
Customize proxyRequest of h3 method. |
enableLogger |
boolean |
false |
true |
Whether to enable logger which is created by consola. |
loggerOptions |
ConsolaOptions |
false |
{} |
Configure the options of consola. |
changeOrigin |
boolean |
false |
false |
Whether to changes the origin of the host header to the target URL |
-
path matching
createProxyEventHandler({...})
- matches any path, all requests will be proxied whenpathFilter
is not configured.createProxyEventHandler({ pathFilter: '/api', ...})
- matches paths starting with/api
-
multiple path matching
createProxyEventHandler({ 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 or glob for more globbing examples.
createProxyEventHandler({ pathFilter: '**', ...})
matches any path, all requests will be proxied.createProxyEventHandler({ pathFilter: '**/*.html', ...})
matches any path which ends with.html
createProxyEventHandler({ pathFilter: '/*.html', ...})
matches paths directly under path-absolutecreateProxyEventHandler({ pathFilter: '/api/**/*.html', ...})
matches requests ending with.html
in the path of/api
createProxyEventHandler({ pathFilter: ['/api/**', '/ajax/**'], ...})
combine multiple patternscreateProxyEventHandler({ pathFilter: ['/api/**', '!**/bad.json'], ...})
exclusion
⚠️ TIPS, In multiple path matching, you cannot use string paths and wildcard paths together.
-
custom matching
For full control you can provide a custom function to determine which requests should be proxied or not.
/** * @return {Boolean} */ const pathFilter = function (path, req) { return path.match(/^\/api/) && req.method === 'GET'; // TIPS: if you are using it in nuxt-proxy-request // Pls use `new RegExp()` instead. // return path.match(new RegExp('^\/api')) && req.method === 'GET'; }; const apiProxy = createProxyEventHandler({ target: 'https://www.example.org', pathFilter: pathFilter, });
Rewrite target's url path. Object-keys will be used as RegExp to match paths.
// rewrite path
pathRewrite: {'^/old/api' : '/new/api'}
// remove path
pathRewrite: {'^/remove/api' : ''}
// add base path
pathRewrite: {'^/' : '/basepath/'}
// 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;
}
For the return value, Please refer to the source code of proxyRequest of h3.
createProxyEventHandler({
// ...
// the param `event` is H3Event
configureProxyRequest(event) {
// return your custom options of proxyRequest
// eg: specify some request headers
// return {
// headers: {}
// }
return {}
}
})
- using nuxt-proxy-request module.
- using
h3-proxy
directly in Nuxt.
Add a server middleware.
// ~/server/middleware/proxy.ts
import { createProxyEventHandler } from 'h3-proxy'
export default defineEventHandler(createProxyEventHandler({
// options...
}))