vite-plugin-caddy-multiple-tls 0.0.1 → 1.1.0

package/README.md

@@ -1,28 +1,132 @@
 # vite-plugin-caddy-multiple-tls
 
-Vite plugin that runs Caddy to proxy local development traffic over HTTPS with
-derived domains like `<repo>.<branch>.localhost`.
+## Usage
 
-## Install
+```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';
+
+const config = defineConfig({
+  plugins: [
+    caddyTls({
+      domain: 'app.localhost',
+    })
+  ]
+});
+
+export default config;
+```
+
+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';
 
-export default defineConfig({
-  plugins: [caddyTls()],
+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
 ```
 
-## Options
+> [!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";
 
@@ -271,6 +270,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 +302,20 @@ 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 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 +344,7 @@ function resolveDomain(options) {
 function viteCaddyTlsPlugin({
   domain,
   baseDomain,
+  loopbackDomain,
   repo,
   branch,
   cors,
@@ -341,17 +355,21 @@ function viteCaddyTlsPlugin({
     name: "vite:caddy-tls",
     configureServer({ httpServer, config }) {
       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;
       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;
       }
@@ -400,14 +418,14 @@ 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();
@@ -416,7 +434,7 @@ function viteCaddyTlsPlugin({
             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;
           }
         }
@@ -426,18 +444,25 @@ function viteCaddyTlsPlugin({
           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"} `
         );
         domainArray.forEach((domain2) => {
-          console.log(chalk.blue(`\u{1F30D} https://${domain2}`));
+          console.log(`\u{1F30D} https://${domain2}`);
         });
+        if (process.platform === "linux" && !loopbackDomain) {
+          console.log();
+          console.log("\u{1F427} Linux users: if the domain doesn't resolve, run:");
+          domainArray.forEach((domain2) => {
+            console.log(`   echo "127.0.0.1 ${domain2}" | sudo tee -a /etc/hosts`);
+          });
+        }
         console.log();
         registerProcessCleanup();
         httpServer?.once("close", onServerClose);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-caddy-multiple-tls",
-  "version": "0.0.1",
+  "version": "1.1.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"
   }
 }