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

npm install -D vite-plugin-phpsandbox

Usage

import { defineConfig } from "vite";
import phpSandboxPlugin from "vite-plugin-phpsandbox";

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

The plugin only applies when PHPSANDBOX_TYPE is set.

Environment Variables

The plugin reads these environment variables by default:

• SUBDOMAIN
• NOTEBOOK_HOST
• PHPSANDBOX_TYPE

Behavior

• Does nothing unless PHPSANDBOX_TYPE is set.
• Uses 5173 as the stable HMR port.
• Derives the public host as ${SUBDOMAIN}-5173.${NOTEBOOK_HOST} when both values exist.
• Uses 443 as the public HMR client port.
• Defaults server.host to true only when the project has not set server.host.
• Adds .${NOTEBOOK_HOST} and the derived public host to server.allowedHosts unless the project has set server.allowedHosts = true.
• Creates a stable local HMR server on 0.0.0.0:5173 unless PHPSANDBOX_TYPE=laravel.
• Fails startup if the local HMR server cannot bind to 0.0.0.0:5173.
• Advertises HMR over wss://${publicHost}:${publicClientPort} when a public host is available.
• Preserves server.hmr = false if the consuming project disables HMR explicitly.
• Logs the resolved sandbox type, host, HMR endpoint, and allowed hosts after config resolution.

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

import phpSandboxPlugin, { phpSandbox } from "vite-plugin-phpsandbox";