\r\n\r\n# h3-proxy\r\n\r\nA **proxy event handler** for [h3](https://github.com/unjs/h3), using `proxyRequest`.\r\n\r\n- ✨ [Release Notes](./CHANGELOG.md)\r\n\r\n# Features\r\n\r\n- Powered by built-in [proxyRequest](https://github.com/unjs/h3/blob/main/src/utils/proxy.ts) of [h3](https://github.com/unjs/h3).\r\n- Support http(s) proxy via some simple [configurations](https://github.com/yisibell/h3-proxy#options).\r\n- Support logs via **consola**.\r\n- Support **Typescript**.\r\n\r\n# Installation\r\n\r\n```bash\r\n# pnpm\r\n$ pnpm add h3-proxy\r\n\r\n# yarn\r\n$ yarn add h3-proxy\r\n\r\n# npm\r\n$ npm i h3-proxy\r\n```\r\n\r\n# Basic usage\r\n\r\n```ts\r\nimport { createServer } from 'node:http'\r\nimport { createApp, eventHandler, toNodeListener } from 'h3'\r\nimport { createProxyEventHandler } from 'h3-proxy'\r\n\r\nconst app = createApp()\r\n\r\nconst port = process.env.PORT || 3000\r\n\r\n// Define proxy event handler\r\nconst proxyEventHandler = createProxyEventHandler({\r\n target: `http://127.0.0.1:${port}`,\r\n pathRewrite: {\r\n '^/api': '',\r\n },\r\n pathFilter: ['/api/**'],\r\n // enableLogger: true\r\n})\r\n\r\n// Add proxy middlewares\r\napp.use(eventHandler(proxyEventHandler))\r\n\r\n// Define api routes\r\napp.use(\r\n '/test',\r\n eventHandler(() => 'Hello world!')\r\n)\r\n\r\ncreateServer(toNodeListener(app)).listen(port)\r\n```\r\n\r\n# Multiple proxy targets usage\r\n\r\n### Create multiple proxy **h3** event handler middleware.\r\n\r\n```ts\r\nimport { createServer } from 'node:http'\r\nimport { createApp, eventHandler, toNodeListener } from 'h3'\r\nimport { createProxyEventHandler } from 'h3-proxy'\r\n\r\nconst app = createApp()\r\n\r\nconst port = process.env.PORT || 3000\r\n\r\n// proxy to `http://127.0.0.1:${port}`\r\nconst proxyEventHandler1 = createProxyEventHandler({\r\n target: `http://127.0.0.1:${port}`, // http://127.0.0.1:3000\r\n pathRewrite: {\r\n '^/api': '',\r\n },\r\n pathFilter: ['/api/**'],\r\n})\r\n\r\n// proxy to other target\r\nconst proxyEventHandler2 = createProxyEventHandler({\r\n target: `http://127.0.0.1:${port}/other-api-module`,\r\n pathRewrite: {\r\n '^/other-api': '',\r\n },\r\n pathFilter: ['/other-api/**'],\r\n})\r\n\r\n// Add proxy middlewares\r\napp.use(eventHandler(proxyEventHandler1))\r\napp.use(eventHandler(proxyEventHandler2))\r\n\r\n// Define api routes\r\napp.use(\r\n '/test',\r\n eventHandler(() => 'Hello world!')\r\n)\r\n\r\napp.use(\r\n '/other-api-module/some/path',\r\n eventHandler(() => 'Hello other API module!')\r\n)\r\n\r\ncreateServer(toNodeListener(app)).listen(port)\r\n```\r\n\r\n- For `proxyEventHandler1`, The result of proxy request is as follows:\r\n\r\n`/api/test` -> `http://127.0.0.1:3000/test`\r\n\r\n\r\n- For `proxyEventHandler2`, The result of proxy request is as follows:\r\n\r\n`/other-api/some/path` -> `http://127.0.0.1:3000/other-api-module/some/path`\r\n\r\n\r\n### Or, using **Array** type options to define multiple proxy targets (added in v1.11.0).\r\n\r\n```ts\r\nconst proxyEventHandler = createProxyEventHandler([\r\n {\r\n // options\r\n },\r\n {\r\n // other proxy target options\r\n }\r\n])\r\n```\r\n\r\n# APIs\r\n\r\n## createProxyEventHandler\r\n\r\nCreate a `h3` event handler that can handle **proxy requests**.\r\n\r\n```ts\r\nconst proxyEventHandler = createProxyEventHandler({\r\n // options\r\n})\r\n```\r\n\r\n# Options\r\n\r\n| Key | Type | Required | Default value | Description |\r\n| :---: | :---: | :---: | :---: | :---: |\r\n| `target` | `string` | `true` | `undefined` | Proxy target address, including **protocol**, **host** and **port**. url string to be parsed with the `node:url` module|\r\n| [pathFilter](https://github.com/yisibell/h3-proxy#pathFilter) | `string, string[], glob, glob[], Function` | `false` | `undefined` |Narrow down which requests should be proxied. |\r\n| [pathRewrite](https://github.com/yisibell/h3-proxy#pathRewrite) | `object/Function` | `false` | `undefined` | Rewrite target's url path. Object-keys will be used as RegExp to match paths. |\r\n| [configureProxyRequest](https://github.com/yisibell/h3-proxy#configureProxyRequest) | `Function` | `false` | `undefined` | Configure options of `proxyRequest`. More details see [built-in util proxyRequest of h3](https://github.com/unjs/h3) |\r\n| `proxyRequestMethod` Added in **v1.13.0** | `Function` | `false` | `undefined` | Customize `proxyRequest` of **h3** method. |\r\n| `enableLogger` | `boolean` | `false` | `true` | Whether to enable logger which is created by **consola**. |\r\n| `loggerOptions` | `ConsolaOptions` | `false` | `{}` | Configure the options of [consola](https://github.com/unjs/consola). |\r\n| `changeOrigin` | `boolean` | `false` | `false` | Whether to changes the origin of the host header to the target URL |\r\n\r\n\r\n## pathFilter\r\n\r\n- **path matching**\r\n\r\n - `createProxyEventHandler({...})` - matches any path, all requests will be proxied when `pathFilter` is not configured.\r\n - `createProxyEventHandler({ pathFilter: '/api', ...})` - matches paths starting with `/api`\r\n\r\n- **multiple path matching**\r\n\r\n - `createProxyEventHandler({ pathFilter: ['/api', '/ajax', '/someotherpath'], ...})`\r\n\r\n- **wildcard path matching**\r\n\r\n 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.\r\n\r\n - `createProxyEventHandler({ pathFilter: '**', ...})` matches any path, all requests will be proxied.\r\n - `createProxyEventHandler({ pathFilter: '**/*.html', ...})` matches any path which ends with `.html`\r\n - `createProxyEventHandler({ pathFilter: '/*.html', ...})` matches paths directly under path-absolute\r\n - `createProxyEventHandler({ pathFilter: '/api/**/*.html', ...})` matches requests ending with `.html` in the path of `/api`\r\n - `createProxyEventHandler({ pathFilter: ['/api/**', '/ajax/**'], ...})` combine multiple patterns\r\n - `createProxyEventHandler({ pathFilter: ['/api/**', '!**/bad.json'], ...})` exclusion\r\n\r\n> :warning: TIPS, In multiple path matching, you cannot use string paths and wildcard paths together.\r\n\r\n- **custom matching**\r\n\r\n For full control you can provide a custom function to determine which requests should be proxied or not.\r\n\r\n ```js\r\n /**\r\n * @return {Boolean}\r\n */\r\n const pathFilter = function (path, req) {\r\n\r\n return path.match(/^\\/api/) && req.method === 'GET';\r\n\r\n // TIPS: if you are using it in nuxt-proxy-request\r\n // Pls use `new RegExp()` instead.\r\n\r\n // return path.match(new RegExp('^\\/api')) && req.method === 'GET';\r\n };\r\n\r\n const apiProxy = createProxyEventHandler({\r\n target: 'http://www.example.org',\r\n pathFilter: pathFilter,\r\n });\r\n ```\r\n\r\n## pathRewrite\r\n\r\nRewrite target's url path. **Object-keys** will be used as **RegExp** to match paths.\r\n\r\n```js\r\n// rewrite path\r\npathRewrite: {'^/old/api' : '/new/api'}\r\n\r\n// remove path\r\npathRewrite: {'^/remove/api' : ''}\r\n\r\n// add base path\r\npathRewrite: {'^/' : '/basepath/'}\r\n\r\n// custom rewriting\r\npathRewrite: function (path, req) { return path.replace('/api', '/base/api') }\r\n\r\n// custom rewriting, returning Promise\r\npathRewrite: async function (path, req) {\r\n const should_add_something = await httpRequestToDecideSomething(path);\r\n if (should_add_something) path += \"something\";\r\n return path;\r\n}\r\n```\r\n\r\n## configureProxyRequest\r\n\r\nFor the return value, Please refer to the source code of [proxyRequest of h3](https://github.com/unjs/h3/blob/main/src/utils/proxy.ts).\r\n\r\n```ts\r\ncreateProxyEventHandler({\r\n // ...\r\n // the param `event` is H3Event\r\n configureProxyRequest(event) {\r\n // return your custom options of proxyRequest\r\n\r\n // eg: specify some request headers\r\n // return {\r\n // headers: {}\r\n // }\r\n\r\n return {}\r\n }\r\n})\r\n```\r\n\r\n# Framework Supports\r\n## Nuxt\r\n\r\n- using [nuxt-proxy-request](https://github.com/yisibell/nuxt-proxy-request) module.\r\n- using `h3-proxy` directly in **Nuxt**.\r\n\r\nAdd a [server middleware](https://nuxt.com/docs/guide/directory-structure/server#server-middleware).\r\n\r\n```ts\r\n// ~/server/middleware/proxy.ts\r\n\r\nimport { createProxyEventHandler } from 'h3-proxy'\r\n\r\nexport default defineEventHandler(createProxyEventHandler({\r\n // options...\r\n}))\r\n```","readmeFilename":"README.md"}
![](\"https://img.shields.io/npm/v/h3-proxy.svg\")
\r\n \r\n \r\n ![](\"https://img.shields.io/npm/dm/h3-proxy.svg\")
\r\n \r\n