h3-proxy

A proxy event handler for h3, using proxyRequest.

• ✨ Release Notes

Features

• Powered by built-in proxyRequest of h3.
• Support http(s) proxy via some simple configurations.
• Support logs via consola.
• Support Typescript.

Installation

# pnpm
$ pnpm add h3-proxy

# yarn
$ yarn add h3-proxy

# npm
$ npm i h3-proxy

Basic usage

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)

Multiple proxy targets usage

Create multiple proxy h3 event handler middleware.

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)

• For proxyEventHandler1, The result of proxy request is as follows:

/api/test -> http://127.0.0.1:3000/test

• For proxyEventHandler2, The result of proxy request is as follows:

/other-api/some/path -> http://127.0.0.1:3000/other-api-module/some/path

Or, using Array type options to define multiple proxy targets (added in v1.11.0).

const proxyEventHandler = createProxyEventHandler([
  {
    // options
  },
  {
    // other proxy target options
  }
])

APIs

createProxyEventHandler

Create a h3 event handler that can handle proxy requests.

const proxyEventHandler = createProxyEventHandler({
  // options
})

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 |

pathFilter

• 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-absolute
  • createProxyEventHandler({ pathFilter: '/api/**/*.html', ...}) matches requests ending with .html in the path of /api
  • createProxyEventHandler({ pathFilter: ['/api/**', '/ajax/**'], ...}) combine multiple patterns
  • createProxyEventHandler({ pathFilter: ['/api/**', '!**/bad.json'], ...}) exclusion

:warning: 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,
  });

pathRewrite

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;
}

configureProxyRequest

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 {}
  }
})

Framework Supports

Nuxt

• 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...
}))