vite-plugin-caddy-multiple-tls 1.0.0 → 1.2.0

package/README.md

@@ -1,28 +1,135 @@
 # vite-plugin-caddy-multiple-tls
 
-Vite plugin that runs Caddy to proxy local development traffic over HTTPS with
-derived domains like `<repo>.<branch>.localhost`.
+## What it does
+Runs Caddy alongside Vite to give you HTTPS locally with automatic, per-branch domains like `<repo>.<branch>.localhost`, so you can use real hostnames, cookies, and secure APIs without manual proxy setup.
 
-## Install
+## Usage
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import caddyTls from 'vite-plugin-caddy-multiple-tls';
 
-```sh
-npm install -D vite-plugin-caddy-multiple-tls
+const config = defineConfig({
+  plugins: [
+    caddyTls(),
+  ]
+});
+
+export default config;
 ```
 
-## Usage
+Will give this in the terminal, allow you to connect to your app on HTTPS with a self-signed and trusted cert.
+```
+> vite
+
+
+🔒 Caddy is proxying your traffic on https
+
+🔗 Access your local server
+🌍 https://my-repo.my-branch.localhost
+
+```
+
+By default, the plugin derives `<repo>.<branch>.localhost` from git.
+If repo or branch can't be detected, pass `repo`/`branch` or use `domain`.
+
+If you want a fixed host without repo/branch in the URL, pass a single domain:
 
 ```js
+// vite.config.js
 import { defineConfig } from 'vite';
 import caddyTls from 'vite-plugin-caddy-multiple-tls';
 
-export default defineConfig({
-  plugins: [caddyTls()],
+const config = defineConfig({
+  plugins: [
+    caddyTls({
+      domain: 'app.localhost',
+    })
+  ]
 });
+
+export default config;
 ```
 
-## Options
+To derive a domain like `<repo>.<branch>.<baseDomain>` automatically from git (repo name first, then branch):
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import caddyTls from 'vite-plugin-caddy-multiple-tls';
+
+const config = defineConfig({
+  plugins: [
+    caddyTls({
+      baseDomain: 'local.conekto.eu',
+    })
+  ]
+});
+
+export default config;
+```
+
+You can override auto-detection with `repo` or `branch` if needed.
+
+For a zero-config experience, use `baseDomain: 'localhost'` (the default) so the derived domain works without editing `/etc/hosts`.
+
+`internalTls` defaults to `true` when you pass `baseDomain` or `domain`. You can override it if needed.
+
+For non-`.localhost` domains (like `local.example.test`), keep `internalTls: true` to force Caddy to use its internal CA for certificates.
+
+> [!IMPORTANT]  
+> **Hosts file limitation:** If you use a custom domain, you must **manually** add each generated subdomain to your `/etc/hosts` file (e.g., `127.0.0.1 repo.branch.local.example.test`). System hosts files **do not support wildcards** (e.g., `*.local.example.test`), so you lose the benefit of automatic domain resolution that `localhost` provides.
+
+## Recommended base domain: `.localhost`
+Why `localhost` is the best option for local development:
+- Reserved by RFC 6761 (never on the public internet).
+- Automatic resolution on macOS: `*.localhost` maps to `127.0.0.1` and `::1` without DNS or `/etc/hosts`.
+- Subdomain support: `api.localhost`, `foo.bar.localhost`, etc.
+- Secure context in browsers for HTTPS, service workers, and cookies.
+- Works well with Caddy and other local reverse proxies.
+
+Example usage:
+```
+app.localhost
+api.app.localhost
+```
+
+> [!NOTE]
+> **Linux users:** Unlike macOS, most Linux distributions don't automatically resolve `*.localhost` subdomains. The plugin will detect Linux and show you the exact command to run:
+> ```
+> 🐧 Linux users: if the domain doesn't resolve, run:
+>    echo "127.0.0.1 my-repo.my-branch.localhost" | sudo tee -a /etc/hosts
+> ```
+>
+> If you want to avoid `/etc/hosts` edits on Linux, set `loopbackDomain` to a public loopback domain:
+> ```ts
+> caddyTls({
+>   loopbackDomain: 'localtest.me',
+> })
+> ```
+> Supported values: `localtest.me`, `lvh.me`, `nip.io` (maps to `127.0.0.1.nip.io`). These rely on public DNS, so they can fail offline or on restricted networks.
+>
+> Why these work: they use wildcard DNS so any subdomain resolves to `127.0.0.1`, meaning the request loops back to your machine after DNS.
+> - `localtest.me` and `lvh.me`: static wildcard -> always `127.0.0.1` (great for subdomain testing).
+> - `nip.io`: dynamic parsing of the IP in the hostname (e.g. `app.192.168.1.50.nip.io`) so you can target LAN devices.
+> Why use them: subdomains behave like real domains, no `/etc/hosts` edits, and closer parity for cookies/CORS rules.
+>
+> When using loopback domains, ensure your Vite config allows the Host header, e.g. `server: { allowedHosts: true }`.
+>
+> For a permanent fix that handles all `*.localhost` domains automatically, install dnsmasq:
+> ```bash
+> sudo apt install dnsmasq
+> echo "address=/.localhost/127.0.0.1" | sudo tee /etc/dnsmasq.d/localhost.conf
+> sudo systemctl restart dnsmasq
+> ```
+
+## Development
+This repo uses npm workspaces. Install from the root with `npm install`, then run workspace scripts like `npm run build --workspace packages/plugin` or `npm run dev --workspace playground`.
+
+## Contributing
+See [CONTRIBUTING.md](./CONTRIBUTING.md) to see how to get started.
+ 
+## License
 
-- `domain`: explicit domain to proxy without repo/branch derivation
-- `baseDomain`: base domain to build `<repo>.<branch>.<baseDomain>` (defaults to `localhost`)
-- `repo`, `branch`: override repo/branch names used for derived domains
-- `internalTls`: use Caddy internal CA for provided domains
+MIT

package/dist/index.d.ts

@@ -5,6 +5,8 @@ interface ViteCaddyTlsPluginOptions {
     domain?: string;
     /** Base domain to build <repo>.<branch>.<baseDomain> (defaults to localhost) */
     baseDomain?: string;
+    /** Optional loopback domain to avoid /etc/hosts edits */
+    loopbackDomain?: LoopbackDomain;
     /** Override repo name used in derived domains */
     repo?: string;
     /** Override branch name used in derived domains */
@@ -15,6 +17,7 @@ interface ViteCaddyTlsPluginOptions {
     /** Use Caddy's internal CA for the provided domains (defaults to true when baseDomain or domain is set) */
     internalTls?: boolean;
 }
+type LoopbackDomain = 'localtest.me' | 'lvh.me' | 'nip.io';
 /**
  * Vite plugin to run Caddy server to proxy traffic on https for local development
  *
@@ -27,6 +30,6 @@ interface ViteCaddyTlsPluginOptions {
  * ```
  * @returns {Plugin} - a Vite plugin
  */
-declare function viteCaddyTlsPlugin({ domain, baseDomain, repo, branch, cors, serverName, internalTls, }?: ViteCaddyTlsPluginOptions): PluginOption;
+declare function viteCaddyTlsPlugin({ domain, baseDomain, loopbackDomain, repo, branch, cors, serverName, internalTls, }?: ViteCaddyTlsPluginOptions): PluginOption;
 
 export { type ViteCaddyTlsPluginOptions, viteCaddyTlsPlugin as default };

package/dist/index.js

@@ -1,5 +1,4 @@
 // src/index.ts
-import chalk from "chalk";
 import { execSync as execSync2 } from "child_process";
 import path from "path";
 
@@ -175,7 +174,13 @@ async function ensureTlsAutomation() {
     throw new Error(`Failed to initialize Caddy TLS automation: ${text}`);
   }
 }
-async function addRoute(id, domains, port, cors, serverName = DEFAULT_SERVER_NAME) {
+function formatDialAddress(host, port) {
+  if (host.includes(":") && !host.startsWith("[")) {
+    return `[${host}]:${port}`;
+  }
+  return `${host}:${port}`;
+}
+async function addRoute(id, domains, port, cors, serverName = DEFAULT_SERVER_NAME, upstreamHost = "127.0.0.1") {
   const handlers = [];
   if (cors) {
     handlers.push({
@@ -198,7 +203,7 @@ async function addRoute(id, domains, port, cors, serverName = DEFAULT_SERVER_NAM
   }
   handlers.push({
     handler: "reverse_proxy",
-    upstreams: [{ dial: `localhost:${port}` }]
+    upstreams: [{ dial: formatDialAddress(upstreamHost, port) }]
   });
   const route = {
     "@id": id,
@@ -271,6 +276,11 @@ async function removeTlsPolicy(id) {
 }
 
 // src/index.ts
+var LOOPBACK_DOMAINS = {
+  "localtest.me": "localtest.me",
+  "lvh.me": "lvh.me",
+  "nip.io": "127.0.0.1.nip.io"
+};
 function execGit(command) {
   return execSync2(command, { stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
 }
@@ -298,11 +308,29 @@ function getGitRepoInfo() {
 function normalizeBaseDomain(baseDomain) {
   return baseDomain.trim().replace(/^\.+|\.+$/g, "").toLowerCase();
 }
+function resolveBaseDomain(options) {
+  if (options.baseDomain !== void 0) {
+    return normalizeBaseDomain(options.baseDomain);
+  }
+  if (options.loopbackDomain) {
+    return normalizeBaseDomain(LOOPBACK_DOMAINS[options.loopbackDomain]);
+  }
+  return "localhost";
+}
+function resolveUpstreamHost(host) {
+  if (typeof host === "string") {
+    const trimmed = host.trim();
+    if (trimmed && trimmed !== "0.0.0.0" && trimmed !== "::") {
+      return trimmed;
+    }
+  }
+  return "127.0.0.1";
+}
 function sanitizeDomainLabel(value) {
   return value.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
 }
 function buildDerivedDomain(options) {
-  const baseDomain = normalizeBaseDomain(options.baseDomain ?? "localhost");
+  const baseDomain = resolveBaseDomain(options);
   if (!baseDomain) return null;
   let repo = options.repo;
   let branch = options.branch;
@@ -331,6 +359,7 @@ function resolveDomain(options) {
 function viteCaddyTlsPlugin({
   domain,
   baseDomain,
+  loopbackDomain,
   repo,
   branch,
   cors,
@@ -339,30 +368,85 @@ function viteCaddyTlsPlugin({
 } = {}) {
   return {
     name: "vite:caddy-tls",
-    configureServer({ httpServer, config }) {
+    configureServer(server) {
+      const { httpServer, config } = server;
       const fallbackPort = config.server.port || 5173;
-      const resolvedDomain = resolveDomain({ domain, baseDomain, repo, branch });
+      const resolvedDomain = resolveDomain({
+        domain,
+        baseDomain,
+        loopbackDomain,
+        repo,
+        branch
+      });
       const domainArray = resolvedDomain ? [resolvedDomain] : [];
       const routeId = `vite-proxy-${Date.now()}-${Math.floor(Math.random() * 1e3)}`;
-      const shouldUseInternalTls = internalTls ?? (baseDomain !== void 0 || domain !== void 0);
+      const shouldUseInternalTls = internalTls ?? (baseDomain !== void 0 || loopbackDomain !== void 0 || domain !== void 0);
       const tlsPolicyId = shouldUseInternalTls ? `${routeId}-tls` : null;
       let cleanupStarted = false;
+      let resolvedPort = null;
+      let resolvedHost = null;
+      let setupStarted = false;
       if (domainArray.length === 0) {
         console.error(
-          chalk.red(
-            "No domain resolved. Provide domain, or run inside a git repo, or pass repo/branch."
-          )
+          "No domain resolved. Provide domain, or run inside a git repo, or pass repo/branch."
         );
         return;
       }
       let tlsPolicyAdded = false;
-      function getServerPort() {
-        if (!httpServer) return fallbackPort;
-        const address = httpServer.address();
+      function getPortFromAddress(address) {
         if (address && typeof address === "object" && "port" in address) {
-          return address.port;
+          const port = address.port;
+          if (typeof port === "number") {
+            return port;
+          }
+        }
+        return null;
+      }
+      function updateResolvedTarget() {
+        if (resolvedPort !== null && resolvedHost !== null) return;
+        const resolvedUrl = server.resolvedUrls?.local?.[0];
+        if (resolvedUrl) {
+          try {
+            const url = new URL(resolvedUrl);
+            if (resolvedHost === null && url.hostname) {
+              resolvedHost = url.hostname === "localhost" ? "127.0.0.1" : url.hostname;
+            }
+            const port = Number(url.port);
+            if (resolvedPort === null && !Number.isNaN(port)) {
+              resolvedPort = port;
+            }
+          } catch (e) {
+          }
+        }
+        if (httpServer) {
+          const address = httpServer.address();
+          if (address && typeof address === "object") {
+            const port = getPortFromAddress(address);
+            if (resolvedPort === null && port !== null) {
+              resolvedPort = port;
+            }
+            if (resolvedHost === null && "address" in address) {
+              const host = address.address;
+              if (typeof host === "string" && host !== "0.0.0.0" && host !== "::") {
+                resolvedHost = host;
+              }
+            }
+          }
+        }
+        if (resolvedPort === null && typeof config.server.port === "number") {
+          resolvedPort = config.server.port;
         }
-        return fallbackPort;
+        if (resolvedHost === null) {
+          resolvedHost = resolveUpstreamHost(config.server.host);
+        }
+      }
+      function getServerPort() {
+        updateResolvedTarget();
+        return resolvedPort ?? fallbackPort;
+      }
+      function getUpstreamHost() {
+        updateResolvedTarget();
+        return resolvedHost ?? "127.0.0.1";
       }
       async function cleanupRoute() {
         if (cleanupStarted) return;
@@ -400,64 +484,87 @@ function viteCaddyTlsPlugin({
         if (!running) {
           running = await startCaddy();
           if (!running) {
-            console.error(chalk.red("Failed to start Caddy server."));
+            console.error("Failed to start Caddy server.");
             return;
           }
         }
         try {
           await ensureBaseConfig(serverName);
         } catch (e) {
-          console.error(chalk.red("Failed to configure Caddy base settings."), e);
+          console.error("Failed to configure Caddy base settings.", e);
           return;
         }
         const port = getServerPort();
+        const upstreamHost = getUpstreamHost();
         if (tlsPolicyId) {
           try {
             await addTlsPolicy(tlsPolicyId, domainArray);
             tlsPolicyAdded = true;
           } catch (e) {
-            console.error(chalk.red("Failed to add TLS policy to Caddy."), e);
+            console.error("Failed to add TLS policy to Caddy.", e);
             return;
           }
         }
         try {
-          await addRoute(routeId, domainArray, port, cors, serverName);
+          await addRoute(routeId, domainArray, port, cors, serverName, upstreamHost);
         } catch (e) {
           if (tlsPolicyAdded && tlsPolicyId) {
             await removeTlsPolicy(tlsPolicyId);
           }
-          console.error(chalk.red("Failed to add route to Caddy."), e);
+          console.error("Failed to add route to Caddy.", e);
           return;
         }
         console.log();
-        console.log(chalk.green("\u{1F512} Caddy is proxying your traffic on https"));
+        console.log("\u{1F512} Caddy is proxying your traffic on https");
         console.log();
         console.log(
-          `\u{1F517} Access your local ${domainArray.length > 1 ? "servers" : "server"} `
+          `\u{1F517} Access your local ${domainArray.length > 1 ? "servers" : "server"}!`
         );
         domainArray.forEach((domain2) => {
-          console.log(chalk.blue(`\u{1F30D} https://${domain2}`));
+          console.log(`\u{1F30D} https://${domain2}`);
         });
-        if (process.platform === "linux") {
+        if (process.platform === "linux" && !loopbackDomain) {
           console.log();
-          console.log(chalk.yellow("\u{1F427} Linux users: if the domain doesn't resolve, run:"));
+          console.log("\u{1F427} Linux users: if the domain doesn't resolve, run:");
           domainArray.forEach((domain2) => {
-            console.log(chalk.dim(`   echo "127.0.0.1 ${domain2}" | sudo tee -a /etc/hosts`));
+            console.log(`   echo "127.0.0.1 ${domain2}" | sudo tee -a /etc/hosts`);
           });
         }
         console.log();
         registerProcessCleanup();
         httpServer?.once("close", onServerClose);
       }
-      function onListening() {
+      function runSetupOnce() {
+        if (setupStarted) return;
+        setupStarted = true;
         void setupRoute();
       }
+      function wrapServerListen() {
+        if (typeof server.listen !== "function") return false;
+        const originalListen = server.listen.bind(server);
+        server.listen = async function(port, isRestart) {
+          const result = await originalListen(port, isRestart);
+          if (typeof port === "number") {
+            resolvedPort = port;
+          } else {
+            updateResolvedTarget();
+          }
+          runSetupOnce();
+          return result;
+        };
+        return true;
+      }
+      function onListening() {
+        updateResolvedTarget();
+        runSetupOnce();
+      }
+      const listenWrapped = wrapServerListen();
       if (httpServer?.listening) {
-        void setupRoute();
+        runSetupOnce();
       } else if (httpServer) {
         httpServer.once("listening", onListening);
-      } else {
-        void setupRoute();
+      } else if (!listenWrapped) {
+        runSetupOnce();
       }
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-caddy-multiple-tls",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Vite plugin that uses Caddy to provide local HTTPS with derived domains.",
   "keywords": [
     "vite",
@@ -29,7 +29,8 @@
   },
   "scripts": {
     "dev": "tsup --watch src/**/* src/index.ts --format esm --dts-resolve",
-    "build": "tsup src/index.ts --format esm --dts",
+    "sync-readme": "bash scripts/sync-readme.sh",
+    "build": "npm run sync-readme && tsup src/index.ts --format esm --dts",
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest"
@@ -55,8 +56,5 @@
     "tsup": "^8.5.1",
     "vite": "^7.3.0",
     "vitest": "^4.0.16"
-  },
-  "dependencies": {
-    "chalk": "^5.6.2"
   }
 }