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

⚠️ 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...
}))