vite-plugin-phpsandbox 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# vite-plugin-phpsandbox
+
+`vite-plugin-phpsandbox` makes Vite's dev server and HMR work reliably behind PHP sandbox and notebook proxy environments.
+
+It is a Vite-only plugin because it mutates Vite's `server` config during dev, including `server.hmr`, `server.allowedHosts`, and a stable HMR server binding.
+
+## Install
+
+```sh
+npm install -D vite-plugin-phpsandbox
+```
+
+## Usage
+
+```ts
+import { defineConfig } from "vite";
+import phpSandboxPlugin from "vite-plugin-phpsandbox";
+
+export default defineConfig({
+  plugins: [phpSandboxPlugin()],
+});
+```
+
+The plugin only applies when `PHPSANDBOX_TYPE` is set.
+
+## Options
+
+```ts
+type PhpSandboxOptions = {
+  allowedHosts?: true | string[];
+  enabled?: boolean;
+  hmrPort?: number;
+  publicHost?: string;
+  publicClientPort?: number;
+};
+```
+
+## Environment Variables
+
+The plugin reads these environment variables by default:
+
+- `SUBDOMAIN`
+- `NOTEBOOK_HOST`
+- `PHPSANDBOX_TYPE`
+
+## Behavior
+
+- Does nothing unless `PHPSANDBOX_TYPE` is set.
+- Resolves the HMR port from the `hmrPort` option only.
+- Resolves the public host from `publicHost`, or derives `${SUBDOMAIN}-${hmrPort}.${NOTEBOOK_HOST}`.
+- Resolves the public client port from the `publicClientPort` option only.
+- Defaults `server.host` to `true` only when the project has not set `server.host`.
+- Merges the derived public host into `server.allowedHosts` by default instead of disabling host checks globally.
+- Creates a stable local HMR server on `0.0.0.0:${hmrPort}` unless `PHPSANDBOX_TYPE=laravel`.
+- Advertises HMR over `wss://${publicHost}:${publicClientPort}` when a public host is available.
+- Preserves `server.hmr = false` if the consuming project disables HMR explicitly.
+
+## Laravel Mode
+
+When `PHPSANDBOX_TYPE=laravel`, the plugin does not create a standalone HMR server. It sets `server.port` to the resolved HMR port and configures the advertised HMR endpoint instead.
+
+## API
+
+```ts
+import phpSandboxPlugin, {
+  phpSandbox,
+  type PhpSandboxEnv,
+  type PhpSandboxOptions,
+} from "vite-plugin-phpsandbox";
+```

package/dist/index.cjs

@@ -0,0 +1,174 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default,
+  phpSandbox: () => phpSandbox,
+  phpSandboxPlugin: () => phpSandboxPlugin
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_http = __toESM(require("http"), 1);
+var DEFAULT_HMR_PORT = 5173;
+var DEFAULT_PUBLIC_CLIENT_PORT = 443;
+var GLOBAL_KEY = "__phpSandboxViteState__";
+function getGlobalState() {
+  const g = globalThis;
+  const existing = g[GLOBAL_KEY];
+  const refs = existing?.refs instanceof Map ? existing.refs : /* @__PURE__ */ new Map();
+  const servers = existing?.servers instanceof Map ? existing.servers : /* @__PURE__ */ new Map();
+  const normalized = { refs, servers };
+  g[GLOBAL_KEY] = normalized;
+  return normalized;
+}
+function normalizeSandboxType(value) {
+  const normalized = value?.trim().toLowerCase();
+  return normalized ? normalized : void 0;
+}
+function resolveHmrPort(options) {
+  return options.hmrPort ?? DEFAULT_HMR_PORT;
+}
+function resolvePublicClientPort(options) {
+  return options.publicClientPort ?? DEFAULT_PUBLIC_CLIENT_PORT;
+}
+function resolvePublicHost(options, env, hmrPort) {
+  return options.publicHost ?? (env.SUBDOMAIN && env.NOTEBOOK_HOST ? `${env.SUBDOMAIN}-${hmrPort}.${env.NOTEBOOK_HOST}` : void 0);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function acquireServer(state, port) {
+  const existing = state.servers.get(port);
+  if (existing) {
+    state.refs.set(port, (state.refs.get(port) ?? 0) + 1);
+    return existing;
+  }
+  const server = import_node_http.default.createServer();
+  server.on("error", (error) => {
+    if (error.code === "EADDRINUSE") return;
+    console.error("[vite-plugin-phpsandbox] HMR server error:", error);
+  });
+  server.listen(port, "0.0.0.0");
+  state.servers.set(port, server);
+  state.refs.set(port, 1);
+  return server;
+}
+function releaseServer(state, port, server) {
+  const nextRefs = (state.refs.get(port) ?? 1) - 1;
+  if (nextRefs > 0) {
+    state.refs.set(port, nextRefs);
+    return;
+  }
+  state.refs.delete(port);
+  if (state.servers.get(port) !== server) return;
+  state.servers.delete(port);
+  if (server.listening) {
+    server.close();
+  }
+}
+function resolveAllowedHosts(existingAllowedHosts, optionAllowedHosts, publicHost) {
+  if (optionAllowedHosts === true || existingAllowedHosts === true) {
+    return true;
+  }
+  const merged = new Set(Array.isArray(existingAllowedHosts) ? existingAllowedHosts : []);
+  if (Array.isArray(optionAllowedHosts)) {
+    for (const host of optionAllowedHosts) {
+      merged.add(host);
+    }
+  }
+  if (publicHost) {
+    merged.add(publicHost);
+  }
+  return merged.size > 0 ? Array.from(merged) : existingAllowedHosts;
+}
+function phpSandboxPlugin(options = {}, env = process.env) {
+  let managedHmrPort;
+  let managedHmrServer;
+  return {
+    name: "vite-plugin-phpsandbox",
+    apply: "serve",
+    enforce: "post",
+    config(userConfig) {
+      if (options.enabled === false) return {};
+      const sandboxType = normalizeSandboxType(env.PHPSANDBOX_TYPE);
+      if (!sandboxType) return {};
+      const hmrPort = resolveHmrPort(options);
+      const publicClientPort = resolvePublicClientPort(options);
+      const publicHost = resolvePublicHost(options, env, hmrPort);
+      const isLaravel = sandboxType === "laravel";
+      const existingServer = userConfig.server ?? {};
+      const existingHmr = isRecord(existingServer.hmr) ? existingServer.hmr : void 0;
+      const hmrDisabled = existingServer.hmr === false;
+      const allowedHosts = resolveAllowedHosts(
+        existingServer.allowedHosts,
+        options.allowedHosts,
+        publicHost
+      );
+      const hmrServer = isLaravel || hmrDisabled ? void 0 : acquireServer(getGlobalState(), hmrPort);
+      managedHmrPort = hmrServer ? hmrPort : void 0;
+      managedHmrServer = hmrServer;
+      return {
+        server: {
+          ...existingServer,
+          host: existingServer.host ?? true,
+          ...isLaravel ? { port: hmrPort } : {},
+          ...hmrDisabled ? { hmr: false } : {
+            hmr: {
+              ...existingHmr,
+              port: hmrPort,
+              ...hmrServer ? { server: hmrServer } : {},
+              ...publicHost ? {
+                protocol: "wss",
+                host: publicHost,
+                clientPort: publicClientPort
+              } : {}
+            }
+          },
+          allowedHosts
+        }
+      };
+    },
+    configureServer(server) {
+      if (!managedHmrServer || managedHmrPort === void 0) return;
+      const hmrPort = managedHmrPort;
+      const hmrServer = managedHmrServer;
+      server.httpServer?.once("close", () => {
+        releaseServer(getGlobalState(), hmrPort, hmrServer);
+      });
+    }
+  };
+}
+var phpSandbox = phpSandboxPlugin;
+var index_default = phpSandboxPlugin;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  phpSandbox,
+  phpSandboxPlugin
+});

package/dist/index.d.cts

@@ -0,0 +1,35 @@
+import { Plugin } from 'vite';
+
+type PhpSandboxEnv = {
+    SUBDOMAIN?: string;
+    NOTEBOOK_HOST?: string;
+    PHPSANDBOX_TYPE?: string;
+};
+type PhpSandboxOptions = {
+    /**
+     * Defaults to merging the derived public host into `server.allowedHosts`.
+     * - true: disable host checks entirely
+     * - array: merge with existing allowedHosts
+     */
+    allowedHosts?: true | string[];
+    /**
+     * Explicitly disable the plugin.
+     */
+    enabled?: boolean;
+    /**
+     * Defaults to 5173.
+     */
+    hmrPort?: number;
+    /**
+     * Defaults to `${SUBDOMAIN}-${port}.${NOTEBOOK_HOST}` when env values exist.
+     */
+    publicHost?: string;
+    /**
+     * Defaults to 443.
+     */
+    publicClientPort?: number;
+};
+declare function phpSandboxPlugin(options?: PhpSandboxOptions, env?: PhpSandboxEnv): Plugin;
+declare const phpSandbox: typeof phpSandboxPlugin;
+
+export { type PhpSandboxEnv, type PhpSandboxOptions, phpSandboxPlugin as default, phpSandbox, phpSandboxPlugin };

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { Plugin } from 'vite';
+
+type PhpSandboxEnv = {
+    SUBDOMAIN?: string;
+    NOTEBOOK_HOST?: string;
+    PHPSANDBOX_TYPE?: string;
+};
+type PhpSandboxOptions = {
+    /**
+     * Defaults to merging the derived public host into `server.allowedHosts`.
+     * - true: disable host checks entirely
+     * - array: merge with existing allowedHosts
+     */
+    allowedHosts?: true | string[];
+    /**
+     * Explicitly disable the plugin.
+     */
+    enabled?: boolean;
+    /**
+     * Defaults to 5173.
+     */
+    hmrPort?: number;
+    /**
+     * Defaults to `${SUBDOMAIN}-${port}.${NOTEBOOK_HOST}` when env values exist.
+     */
+    publicHost?: string;
+    /**
+     * Defaults to 443.
+     */
+    publicClientPort?: number;
+};
+declare function phpSandboxPlugin(options?: PhpSandboxOptions, env?: PhpSandboxEnv): Plugin;
+declare const phpSandbox: typeof phpSandboxPlugin;
+
+export { type PhpSandboxEnv, type PhpSandboxOptions, phpSandboxPlugin as default, phpSandbox, phpSandboxPlugin };

package/dist/index.js

@@ -0,0 +1,138 @@
+// src/index.ts
+import http from "http";
+var DEFAULT_HMR_PORT = 5173;
+var DEFAULT_PUBLIC_CLIENT_PORT = 443;
+var GLOBAL_KEY = "__phpSandboxViteState__";
+function getGlobalState() {
+  const g = globalThis;
+  const existing = g[GLOBAL_KEY];
+  const refs = existing?.refs instanceof Map ? existing.refs : /* @__PURE__ */ new Map();
+  const servers = existing?.servers instanceof Map ? existing.servers : /* @__PURE__ */ new Map();
+  const normalized = { refs, servers };
+  g[GLOBAL_KEY] = normalized;
+  return normalized;
+}
+function normalizeSandboxType(value) {
+  const normalized = value?.trim().toLowerCase();
+  return normalized ? normalized : void 0;
+}
+function resolveHmrPort(options) {
+  return options.hmrPort ?? DEFAULT_HMR_PORT;
+}
+function resolvePublicClientPort(options) {
+  return options.publicClientPort ?? DEFAULT_PUBLIC_CLIENT_PORT;
+}
+function resolvePublicHost(options, env, hmrPort) {
+  return options.publicHost ?? (env.SUBDOMAIN && env.NOTEBOOK_HOST ? `${env.SUBDOMAIN}-${hmrPort}.${env.NOTEBOOK_HOST}` : void 0);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function acquireServer(state, port) {
+  const existing = state.servers.get(port);
+  if (existing) {
+    state.refs.set(port, (state.refs.get(port) ?? 0) + 1);
+    return existing;
+  }
+  const server = http.createServer();
+  server.on("error", (error) => {
+    if (error.code === "EADDRINUSE") return;
+    console.error("[vite-plugin-phpsandbox] HMR server error:", error);
+  });
+  server.listen(port, "0.0.0.0");
+  state.servers.set(port, server);
+  state.refs.set(port, 1);
+  return server;
+}
+function releaseServer(state, port, server) {
+  const nextRefs = (state.refs.get(port) ?? 1) - 1;
+  if (nextRefs > 0) {
+    state.refs.set(port, nextRefs);
+    return;
+  }
+  state.refs.delete(port);
+  if (state.servers.get(port) !== server) return;
+  state.servers.delete(port);
+  if (server.listening) {
+    server.close();
+  }
+}
+function resolveAllowedHosts(existingAllowedHosts, optionAllowedHosts, publicHost) {
+  if (optionAllowedHosts === true || existingAllowedHosts === true) {
+    return true;
+  }
+  const merged = new Set(Array.isArray(existingAllowedHosts) ? existingAllowedHosts : []);
+  if (Array.isArray(optionAllowedHosts)) {
+    for (const host of optionAllowedHosts) {
+      merged.add(host);
+    }
+  }
+  if (publicHost) {
+    merged.add(publicHost);
+  }
+  return merged.size > 0 ? Array.from(merged) : existingAllowedHosts;
+}
+function phpSandboxPlugin(options = {}, env = process.env) {
+  let managedHmrPort;
+  let managedHmrServer;
+  return {
+    name: "vite-plugin-phpsandbox",
+    apply: "serve",
+    enforce: "post",
+    config(userConfig) {
+      if (options.enabled === false) return {};
+      const sandboxType = normalizeSandboxType(env.PHPSANDBOX_TYPE);
+      if (!sandboxType) return {};
+      const hmrPort = resolveHmrPort(options);
+      const publicClientPort = resolvePublicClientPort(options);
+      const publicHost = resolvePublicHost(options, env, hmrPort);
+      const isLaravel = sandboxType === "laravel";
+      const existingServer = userConfig.server ?? {};
+      const existingHmr = isRecord(existingServer.hmr) ? existingServer.hmr : void 0;
+      const hmrDisabled = existingServer.hmr === false;
+      const allowedHosts = resolveAllowedHosts(
+        existingServer.allowedHosts,
+        options.allowedHosts,
+        publicHost
+      );
+      const hmrServer = isLaravel || hmrDisabled ? void 0 : acquireServer(getGlobalState(), hmrPort);
+      managedHmrPort = hmrServer ? hmrPort : void 0;
+      managedHmrServer = hmrServer;
+      return {
+        server: {
+          ...existingServer,
+          host: existingServer.host ?? true,
+          ...isLaravel ? { port: hmrPort } : {},
+          ...hmrDisabled ? { hmr: false } : {
+            hmr: {
+              ...existingHmr,
+              port: hmrPort,
+              ...hmrServer ? { server: hmrServer } : {},
+              ...publicHost ? {
+                protocol: "wss",
+                host: publicHost,
+                clientPort: publicClientPort
+              } : {}
+            }
+          },
+          allowedHosts
+        }
+      };
+    },
+    configureServer(server) {
+      if (!managedHmrServer || managedHmrPort === void 0) return;
+      const hmrPort = managedHmrPort;
+      const hmrServer = managedHmrServer;
+      server.httpServer?.once("close", () => {
+        releaseServer(getGlobalState(), hmrPort, hmrServer);
+      });
+    }
+  };
+}
+var phpSandbox = phpSandboxPlugin;
+var index_default = phpSandboxPlugin;
+export {
+  index_default as default,
+  phpSandbox,
+  phpSandboxPlugin
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "vite-plugin-phpsandbox",
+  "version": "0.1.0",
+  "description": "Vite plugin for PHP sandbox environments that need stable HMR over public proxy hosts.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "vite-plugin",
+    "phpsandbox",
+    "hmr",
+    "sandbox"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "check": "tsc --noEmit",
+    "release:check": "npm run check && npm run build && npm pack --dry-run",
+    "release": "npm run release:check && npm publish",
+    "prepublishOnly": "npm run build && npm run check"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vite": "^8.0.0"
+  }
+}