vite-plugin-caddy-multiple-tls

1.8.1 verified Mon Apr 27 auth: no javascript

Vite plugin (v1.8.1) that runs Caddy alongside Vite to provide local HTTPS with automatic per-branch domains like `<repo>.<branch>.localhost`. Supports Vite 3-8, Node >=22. Ships TypeScript types. Key differentiators: multi-instance isolation via ownership tokens, automatic git-derived hostnames, no /etc/hosts editing needed for `.localhost` domains, and exported helpers (`resolveCaddyTlsDomains`, `resolveCaddyTlsUrl`) for external tooling. Actively maintained with frequent releases addressing crash recovery, port conflicts, and cross-process locks.

Common errors

error Error: The plugin 'vite-plugin-caddy-multiple-tls' requires Node.js >=22.0.0 ↓

cause Node version is too old.

fix

Run nvm install 22 or upgrade Node to v22+.

error Error [ERR_REQUIRE_ESM]: require() of ES Module ↓

cause Using CommonJS `require()` instead of ESM `import`.

fix

Change to import caddyTls from 'vite-plugin-caddy-multiple-tls' and ensure your project is ESM.

error Error: Hostname conflict: another live server already owns '<domain>'. Refusing takeover. ↓

cause Another Vite instance with the same derived domain is running (since v1.7.0).

fix

Stop the other server, or set a unique instanceLabel or domain in plugin options.

Warnings

breaking Since v1.7.0, the plugin refuses to take over a hostname already owned by another live Vite server. Previously it silently replaced the other server's route. ↓

fix Use `instanceLabel`, `domain`, or stop the other server first.

breaking Since v1.6.0, route IDs are deterministic and stale route/tls entries are replaced only when matching. This may break setups relying on non-deterministic route ordering. ↓

fix Ensure Caddy is restarted if routes appear missing. Use `instanceLabel` to avoid collisions.

breaking Node >=22.0.0 is required. Older versions will fail with syntax errors due to ESM features. ↓

fix Upgrade Node to v22 or later.

gotcha The plugin defaults `server.host = true` and `server.allowedHosts = true`. If you override these, custom hostnames may not work. ↓

fix Keep these defaults or explicitly set `allowedHosts` to include the resolved domain.

gotcha When using `baseDomain` other than `localhost`, you must configure DNS or /etc/hosts manually. The plugin does not modify system hosts. ↓

fix Add the resolved domain to your hosts file or use a wildcard DNS resolver.

Install

npm install vite-plugin-caddy-multiple-tls

yarn add vite-plugin-caddy-multiple-tls

pnpm add vite-plugin-caddy-multiple-tls

Imports

default (caddyTls)

wrong

const caddyTls = require('vite-plugin-caddy-multiple-tls')

correct

import caddyTls from 'vite-plugin-caddy-multiple-tls'

ESM-only (Node >=22). CommonJS require will throw.

resolveCaddyTlsDomains

wrong

import resolveCaddyTlsDomains from 'vite-plugin-caddy-multiple-tls'

correct

import { resolveCaddyTlsDomains } from 'vite-plugin-caddy-multiple-tls'

Named export, not default. Available since v1.8.0.

resolveCaddyTlsUrl

wrong

import resolveCaddyTlsUrl from 'vite-plugin-caddy-multiple-tls'

correct

import { resolveCaddyTlsUrl } from 'vite-plugin-caddy-multiple-tls'

Named export, not default. Available since v1.8.0.

Quickstart

Minimal Vite config enabling automatic HTTPS via Caddy with git-derived domain.

// vite.config.js
import { defineConfig } from 'vite';
import caddyTls from 'vite-plugin-caddy-multiple-tls';

export default defineConfig({
  plugins: [caddyTls()]
});

// Then run: npx vite
// Terminal output:
// 🔒 Caddy is proxying your traffic on https
// 🌍 https://my-repo.my-branch.localhost