@vhosty/vite-plugin 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zack Warren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @vhosty/vite-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runs your Vite dev server through [vhosty](https://github.com/vhostyhq/vhosty), with
+HTTPS and hot reload at `https://<port>.<your-domain>`, from any device on your tailnet.
+
+```
+  ➜  Local:   http://127.0.0.1:5173/
+  ➜  vhosty:  https://5173.vhosty.link/
+```
+
+- **Zero config on vhosty machines.** It reads your domain from `~/.vhosty/config`.
+- **Safe for teammates.** Without vhosty, the plugin does nothing and Vite behaves normally.
+- **Runs several projects at once.** Each project gets the next free port and its matching hostname.
+- **Works with Laravel.** `public/hot` gets the `https://` URL, so `@vite` loads assets through vhosty.
+
+## Install
+
+```bash
+npm i -D @vhosty/vite-plugin
+```
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import laravel from 'laravel-vite-plugin';
+import vue from '@vitejs/plugin-vue';
+import vhosty from '@vhosty/vite-plugin';
+
+export default defineConfig({
+    plugins: [
+        vhosty(),
+        laravel({ input: ['resources/css/app.css', 'resources/js/app.js'], refresh: true }),
+        vue(),
+    ],
+});
+```
+
+Run `npm run dev` as usual.
+
+## What it does
+
+When the dev server starts (`vite` / `npm run dev`, but not `build` or `preview`) on a
+machine with a vhosty domain, the plugin:
+
+- **Picks a free port** starting at `server.port` (default 5173). It checks both `127.0.0.1`
+  and `::1`, so it never lands on a port another dev server holds over IPv6.
+- **Points Vite at `https://<port>.<domain>`:** `server.origin`, HMR over a secure
+  WebSocket on port 443, and `allowedHosts` for that hostname.
+- **Binds to `127.0.0.1` only.** vhosty's Caddy is the way in, so the dev server isn't
+  exposed on your network.
+- **Allows CORS from `https://*.<domain>`,** so your app loads the assets whether it's at
+  `escrow.vhosty.link`, a proxied name, or another port.
+- **Deletes a stale `public/fonts-manifest.dev.json`,** which laravel-vite-plugin can
+  leave pointing at an old hostname.
+
+## Options
+
+```js
+vhosty({
+    domain: 'vhosty.link',     // default: VHOSTY_DOMAIN, then ~/.vhosty/config
+    port: 5173,                // first port to try (default: server.port, or 5173)
+    cleanFontsManifest: true,  // delete a stale fonts-manifest.dev.json on start
+    configPath: '/Users/you/.vhosty/config', // default: ~/.vhosty/config
+})
+```
+
+The plugin looks for the domain in this order:
+
+1. the `domain` option
+2. `VHOSTY_DOMAIN` in the project's `.env`
+3. `VITE_HMR_DOMAIN` (the older name, still supported)
+4. `VHOSTY_DOMAIN` in `~/.vhosty/config`
+
+If none is set, the plugin does nothing. To turn it off for one project on a vhosty
+machine, set `VHOSTY=false` in that project's `.env`.
+
+## Laravel
+
+Set the app's URL in `.env`, then run `php artisan config:clear`:
+
+```dotenv
+APP_URL=https://escrow.vhosty.link
+```
+
+When vhosty serves the app through PHP-FPM, Laravel already generates `https://` links.
+See the [vhosty Laravel guide](https://github.com/vhostyhq/vhosty/blob/main/docs/laravel-vite.md)
+for `artisan serve` and Octane.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| No `vhosty:` line on startup | No domain found. Check `~/.vhosty/config`, or set `VHOSTY_DOMAIN`. |
+| Assets load from `http://localhost:5173` | `vhosty()` must come **before** `laravel()` in `plugins`. |
+| 502 on `https://<port>.<domain>` | Vite isn't running, or vhosty's Caddy isn't. Run `vhosty doctor`. |
+| `EOF` in Caddy's log | Vite is serving HTTPS itself (`basicSsl()`, `detectTls`, `server.https`). Remove it; vhosty handles HTTPS. |
+
+## Requirements
+
+Vite 5 or newer, Node 18 or newer, and an ESM `vite.config` (the default for Vite and Laravel).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { type Plugin } from 'vite';
+export interface VhostyOptions {
+    /**
+     * The vhosty domain, e.g. "vhosty.link". Defaults to VHOSTY_DOMAIN in .env,
+     * then ~/.vhosty/config. Without one, the plugin does nothing.
+     */
+    domain?: string;
+    /** First port to try. Defaults to server.port, or 5173. */
+    port?: number;
+    /** Delete a stale public/fonts-manifest.dev.json on start. Default: true. */
+    cleanFontsManifest?: boolean;
+    /** Path to the vhosty config. Default: ~/.vhosty/config */
+    configPath?: string;
+}
+/**
+ * Serves the Vite dev server through vhosty at https://<port>.<domain>, which
+ * vhosty's Caddy proxies to localhost:<port>. Picks a free port, so several
+ * projects can run side by side.
+ *
+ * Runs before laravel() so the hot file picks up the https origin.
+ */
+export default function vhosty(options?: VhostyOptions): Plugin;
+export { vhosty };
+export { corsOrigin, findFreePort, resolveDomain } from './utils.js';

package/dist/index.js

@@ -0,0 +1,61 @@
+import { resolve } from 'node:path';
+import { loadEnv } from 'vite';
+import { corsOrigin, findFreePort, removeStaleFontsManifest, resolveDomain } from './utils.js';
+/**
+ * Serves the Vite dev server through vhosty at https://<port>.<domain>, which
+ * vhosty's Caddy proxies to localhost:<port>. Picks a free port, so several
+ * projects can run side by side.
+ *
+ * Runs before laravel() so the hot file picks up the https origin.
+ */
+export default function vhosty(options = {}) {
+    let url;
+    return {
+        name: 'vhosty',
+        enforce: 'pre',
+        async config(userConfig, { command, mode, isPreview }) {
+            if (command !== 'serve' || isPreview) {
+                return;
+            }
+            const root = userConfig.root ? resolve(userConfig.root) : process.cwd();
+            const envDir = typeof userConfig.envDir === 'string' ? resolve(root, userConfig.envDir) : root;
+            const env = loadEnv(mode, envDir, '');
+            const domain = resolveDomain(env, options.domain, options.configPath);
+            if (!domain) {
+                return;
+            }
+            const port = await findFreePort(options.port ?? userConfig.server?.port ?? 5173);
+            const host = `${port}.${domain}`;
+            url = `https://${host}`;
+            return {
+                server: {
+                    host: '127.0.0.1',
+                    port,
+                    strictPort: true,
+                    origin: url,
+                    allowedHosts: [host],
+                    cors: { origin: corsOrigin(domain) },
+                    hmr: { host, protocol: 'wss', clientPort: 443 },
+                },
+            };
+        },
+        configResolved(config) {
+            if (url && options.cleanFontsManifest !== false) {
+                const publicDir = config.publicDir ? config.publicDir : 'public';
+                removeStaleFontsManifest(config.root, publicDir);
+            }
+        },
+        configureServer(server) {
+            if (!url) {
+                return;
+            }
+            const printUrls = server.printUrls.bind(server);
+            server.printUrls = () => {
+                printUrls();
+                server.config.logger.info(`  \x1b[32m➜\x1b[0m  \x1b[1mvhosty\x1b[0m:  \x1b[36m${url}/\x1b[0m`);
+            };
+        },
+    };
+}
+export { vhosty };
+export { corsOrigin, findFreePort, resolveDomain } from './utils.js';

package/dist/utils.d.ts

@@ -0,0 +1,7 @@
+export declare function isPortFree(port: number, host: string): Promise<boolean>;
+export declare function findFreePort(start: number, attempts?: number): Promise<number>;
+export declare function resolveDomain(env: Record<string, string>, option?: string, configPath?: string): string | undefined;
+export declare function readConfigDomain(configPath: string): string | undefined;
+export declare function normalizeDomain(domain: string): string;
+export declare function corsOrigin(domain: string): RegExp;
+export declare function removeStaleFontsManifest(root: string, publicDirectory?: string): boolean;

package/dist/utils.js

@@ -0,0 +1,81 @@
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+/*
+ * True when nothing is listening on `port` at `host`. A machine without IPv6
+ * can't have anything listening on ::1, so those errors count as free.
+ */
+export function isPortFree(port, host) {
+    return new Promise((done) => {
+        const probe = createServer()
+            .once('error', (err) => {
+            done(err.code === 'EADDRNOTAVAIL' || err.code === 'EAFNOSUPPORT');
+        })
+            .once('listening', () => probe.close(() => done(true)))
+            .listen({ port, host, exclusive: true });
+    });
+}
+/*
+ * First port from `start` that's free on both 127.0.0.1 and ::1. Node 17+
+ * often binds `localhost` to ::1 only, and Caddy dials `localhost`, so a
+ * port in use on either address would route to the wrong app.
+ */
+export async function findFreePort(start, attempts = 100) {
+    for (let port = start; port < start + attempts; port++) {
+        if ((await isPortFree(port, '127.0.0.1')) && (await isPortFree(port, '::1'))) {
+            return port;
+        }
+    }
+    throw new Error(`[vhosty] No free port between ${start} and ${start + attempts - 1}`);
+}
+/*
+ * The vhosty domain, from (in order): the plugin option, VHOSTY_DOMAIN,
+ * the older VITE_HMR_DOMAIN, then ~/.vhosty/config. VHOSTY=false turns
+ * the plugin off for one project.
+ */
+export function resolveDomain(env, option, configPath = join(homedir(), '.vhosty', 'config')) {
+    if (env.VHOSTY === 'false' || env.VHOSTY === '0') {
+        return undefined;
+    }
+    const domain = option || env.VHOSTY_DOMAIN || env.VITE_HMR_DOMAIN || readConfigDomain(configPath);
+    return domain ? normalizeDomain(domain) : undefined;
+}
+export function readConfigDomain(configPath) {
+    try {
+        const config = readFileSync(configPath, 'utf8');
+        return config.match(/^\s*VHOSTY_DOMAIN=["']?([^"'\s]+)["']?\s*$/m)?.[1];
+    }
+    catch {
+        return undefined; // not a vhosty machine
+    }
+}
+export function normalizeDomain(domain) {
+    return domain
+        .trim()
+        .toLowerCase()
+        .replace(/^https?:\/\//, '')
+        .replace(/^\*\./, '')
+        .replace(/\/.*$/, '')
+        .replace(/\.$/, '');
+}
+/*
+ * Matches https://<one label>.<domain>, so every app and port on the vhosty
+ * domain can load the dev server's assets. Only your tailnet can reach these.
+ */
+export function corsOrigin(domain) {
+    const escaped = domain.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`^https://[a-z0-9-]+\\.${escaped}$`);
+}
+/*
+ * laravel-vite-plugin caches font URLs in public/fonts-manifest.dev.json and
+ * doesn't always rewrite it, which leaves fonts pointing at an old host.
+ */
+export function removeStaleFontsManifest(root, publicDirectory = 'public') {
+    const file = resolve(root, publicDirectory, 'fonts-manifest.dev.json');
+    if (!existsSync(file)) {
+        return false;
+    }
+    rmSync(file, { force: true });
+    return true;
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@vhosty/vite-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Serve the Vite dev server through vhosty: HTTPS and hot reload at https://<port>.<your-domain> over your tailnet",
+  "keywords": [
+    "vite",
+    "vite-plugin",
+    "vhosty",
+    "tailscale",
+    "caddy",
+    "laravel",
+    "hmr",
+    "https"
+  ],
+  "license": "MIT",
+  "author": "Zack Warren",
+  "homepage": "https://github.com/vhostyhq/vite-plugin#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vhostyhq/vite-plugin.git"
+  },
+  "bugs": "https://github.com/vhostyhq/vite-plugin/issues",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "laravel-vite-plugin": "^3.2.0",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5"
+  }
+}