unplugin-https-reverse-proxy

A plugin for https reverse proxy, support vite、webpack and rspack.

Install

Support set caddy file path by environment variable UHRP_CADDY_PATH, default is system cache folder.

#.env.local
UHRP_CADDY_PATH=~/tmp/.uhrp

npm i unplugin-https-reverse-proxy --save-dev

interface Options {
  /** default: true */
  enable?: boolean
  /** target hostname */
  target: string
  /** default: false */
  showCaddyLog?: boolean
  /** default: false */
  https?: boolean
}

Vite

// vite.config.ts
import HttpsReverseProxy from 'unplugin-https-reverse-proxy/vite'

export default defineConfig({
  plugins: [
    HttpsReverseProxy({ /* options */ }),
  ],
})

Example: playground/

Webpack 5

// webpack.config.js

/** @type {Parameters<import('unplugin-https-reverse-proxy/webpack')['default']>[0]} */
const reverseProxyOptions = {
  enable: false,
  target: 'xxx',
  https: false,
}

module.exports = {
  /* ... */
  devServer: {
    client: {
      // ↓ for HMR
      webSocketURL: {
        ...(reverseProxyOptions.enable
          ? {
              hostname: reverseProxyOptions.target,
            }
          : {}),
        ...(reverseProxyOptions.enable && reverseProxyOptions.https
          ? {
              protocol: 'wss',
              port: 443,
            }
          : {})
      }
    },
    setupExitSignals: true,
    allowedHosts: 'all',
  },
  plugins: [
    require('unplugin-https-reverse-proxy/webpack')(reverseProxyOptions)
  ]
}

Webpack 4

// webpack.config.js

/** @type {Parameters<import('unplugin-https-reverse-proxy/webpack')['default']>[0]} */
const reverseProxyOptions = {
  enable: false,
  target: 'xxx',
  // https: false, // not support yet
}

module.exports = {
  /* ... */
  devServer: {
    host: '0.0.0.0',
    disableHostCheck: true,
  },
  plugins: [
    require('unplugin-https-reverse-proxy/webpack')(reverseProxyOptions)
  ]
}

Rspack

// rspack.config.js

/** @type {Parameters<import('unplugin-https-reverse-proxy/webpack')['default']>[0]} */
const reverseProxyOptions = {
  enable: false,
  target: 'xxx',
  https: false,
}

module.exports = {
  /* ... */
  devServer: {
    client: {
      // ↓ for HMR
      webSocketURL: {
        ...(reverseProxyOptions.enable
          ? {
              hostname: reverseProxyOptions.target,
            }
          : {}),
        ...(reverseProxyOptions.enable && reverseProxyOptions.https
          ? {
              protocol: 'wss',
              port: 443,
            }
          : {})
      }
    },
  },
  plugins: [
    require('unplugin-https-reverse-proxy/rspack')(reverseProxyOptions)
  ]
}

Rsbuild

// rsbuild.config.js

/** @type {Parameters<import('unplugin-https-reverse-proxy/webpack')['default']>[0]} */
const reverseProxyOptions = {
  enable: false,
  target: 'xxx',
  https: false,
  healthCheck: true,
}

module.exports = {
  /* ... */
  dev: {
    client: {
      // ↓ for HMR
      ...(reverseProxyOptions.enable
        ? {
            host: reverseProxyOptions.target,
          }
        : {}),
      ...(reverseProxyOptions.enable && reverseProxyOptions.https
        ? {
            protocol: 'wss',
            port: '443',
          }
        : {})
    },
  },
  tools: {
    rspack: {
      plugins: [
        require('unplugin-https-reverse-proxy/rspack')(reverseProxyOptions)
      ]
    },
  },
}

Nuxt

// nuxt.config.js
export default defineNuxtConfig({
  modules: [
    ['unplugin-https-reverse-proxy/nuxt', {
      /* options */
      healthCheck: false, // important for nuxt
    }],
  ],
})

!important: You need to update the nuxt dev script by adding --fork=false to enable host restoration.

// package.json

{
  "scripts": {
    "dev": "nuxt dev --fork=false"
  }
}

Vue CLI 5

// vue.config.js

/** @type {Parameters<import('unplugin-https-reverse-proxy/webpack')['default']>[0]} */
const reverseProxyOptions = {
  enable: false,
  target: 'xxx',
  https: false,
}

module.exports = {
  devServer: {
    client: {
      // ↓ for HMR
      webSocketURL: {
        ...(reverseProxyOptions.enable
          ? {
              hostname: reverseProxyOptions.target,
            }
          : {}),
        ...(reverseProxyOptions.enable && reverseProxyOptions.https
          ? {
              protocol: 'wss',
              port: 443,
            }
          : {})
      }
    },
    setupExitSignals: true,
    allowedHosts: 'all',
  },
  configureWebpack: {
    plugins: [
      require('unplugin-https-reverse-proxy/webpack')(reverseProxyOptions),
    ],
  },
}

Vue CLI 4

// vue.config.js

/** @type {Parameters<import('unplugin-https-reverse-proxy/webpack')['default']>[0]} */
const reverseProxyOptions = {
  enable: false,
  target: 'xxx',
  // https: false, // not support yet
}

module.exports = {
  devServer: {
    host: '0.0.0.0',
    disableHostCheck: true,
  },
  configureWebpack: {
    plugins: [
      require('unplugin-https-reverse-proxy/webpack')(reverseProxyOptions),
    ],
  },
}

NOTICE!

You need delete caddy executable file after you updated to ^2.0.0. The default path is $TMPDIR/caddy, and if you set UHRP_CADDY_PATH, it will be in the path you set.

Please check caddy path.

Usage

# macOS / Linux / Windows
npm run dev # your dev script

Run it as your normal user. The plugin starts a small privileged helper that runs as administrator, and only that helper touches /etc/hosts and ports 80/443. Your dev server, its caches and node_modules stay owned by you.

On macOS and Linux the plugin asks for your password once when the dev server starts, then reuses the sudo credential for the rest of the session. If you already ran sudo -v in the same terminal, no prompt is shown.

The helper restores the hosts entries by itself when the dev server exits, including when it is killed or crashes.

Granting the permission once (optional)

To skip the password prompt entirely, allow the plugin's helper in /etc/sudoers.d/ (edit with sudo visudo -f /etc/sudoers.d/uhrp):

yourname ALL=(root) NOPASSWD: /usr/bin/killall -HUP mDNSResponder
yourname ALL=(root) NOPASSWD: /usr/bin/install -m 644 -o root -g wheel /tmp/uhrp-hosts.* /etc/hosts

The second rule only matters when the helper rewrites /etc/hosts through install; adjust the paths to your platform.

Windows

Run npm run dev normally. Windows raises a UAC prompt once, when the helper is started through Start-Process -Verb RunAs.

If your broswer shows a not trusted certificate warning, please check the keychain.

More info, you can check caddy about CA Root.