A http(s) proxy event handler for h3, using proxyRequest.
MIT License
A proxy event handler for h3, using proxyRequest
.
# 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: `http://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 `http://127.0.0.1:${port}`
const proxyEventHandler1 = createProxyEventHandler({
target: `http://127.0.0.1:${port}`, // http://127.0.0.1:3000
pathRewrite: {
'^/api': '',
},
pathFilter: ['/api/**'],
})
// proxy to other target
const proxyEventHandler2 = createProxyEventHandler({
target: `http://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)
proxyEventHandler1
, The result of proxy request is as follows:/api/test
-> http://127.0.0.1:3000/test
proxyEventHandler2
, The result of proxy request is as follows:/other-api/some/path
-> http://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 when pathFilter
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: 'http://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 {}
}
})
h3-proxy
directly in Nuxt.Add a server middleware.
// ~/server/middleware/proxy.ts
import { createProxyEventHandler } from 'h3-proxy'
export default defineEventHandler(createProxyEventHandler({
// options...
}))