litestar-vite-plugin 0.22.2 → 0.23.0

package/dist/js/astro.d.ts

@@ -45,6 +45,12 @@ interface AstroConfigPartial {
             port?: number;
             strictPort?: boolean;
             proxy?: Record<string, unknown>;
+            hmr?: {
+                protocol?: "ws" | "wss";
+                host?: string;
+                clientPort?: number;
+                path?: string;
+            };
         };
     };
 }

package/dist/js/astro.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { readBridgeConfig } from "./shared/bridge-schema.js";
 import { DEBOUNCE_MS } from "./shared/constants.js";
-import { normalizeHost, resolveHotFilePath } from "./shared/network.js";
+import { normalizeHost, resolveHotFilePath, resolveLitestarPort } from "./shared/network.js";
 import { createLitestarTypeGenPlugin } from "./shared/typegen-plugin.js";
 function resolveConfig(config = {}) {
   let hotFile;
@@ -19,6 +19,8 @@ function resolveConfig(config = {}) {
     }
   }
   const runtime = readBridgeConfig();
+  let assetUrl;
+  let litestarPort;
   if (runtime) {
     hasPythonConfig = true;
     const hot = runtime.hotFile;
@@ -26,10 +28,15 @@ function resolveConfig(config = {}) {
     proxyMode = runtime.proxyMode;
     port = runtime.port;
     pythonExecutor = runtime.executor;
+    assetUrl = runtime.assetUrl;
     if (runtime.types) {
       pythonTypesConfig = runtime.types;
     }
   }
+  const resolvedLitestarPort = resolveLitestarPort(runtime?.litestarPort, runtime?.appUrl);
+  if (resolvedLitestarPort !== null) {
+    litestarPort = resolvedLitestarPort;
+  }
   let typesConfig = false;
   const defaultTypesOutput = "src/generated";
   const buildTypeDefaults = (output) => ({
@@ -106,6 +113,8 @@ function resolveConfig(config = {}) {
     hotFile,
     proxyMode,
     port,
+    litestarPort,
+    assetUrl,
     executor: pythonExecutor,
     hasPythonConfig
   };
@@ -114,6 +123,7 @@ function createProxyPlugin(config) {
   return {
     name: "litestar-astro-proxy",
     config() {
+      const hmrPath = `${(config.assetUrl ?? "/static").replace(/\/$/, "")}/vite-hmr`;
       return {
         server: {
           // Force IPv4 binding for consistency with Python proxy configuration
@@ -125,6 +135,15 @@ function createProxyPlugin(config) {
             port: config.port,
             strictPort: true
           } : {},
+          // Route HMR through the Litestar port so DevTools never sees the framework port.
+          ...config.litestarPort !== void 0 ? {
+            hmr: {
+              protocol: "ws",
+              host: "127.0.0.1",
+              clientPort: config.litestarPort,
+              path: hmrPath
+            }
+          } : {},
           proxy: {
             [config.apiPrefix]: {
               target: config.apiProxy,

package/dist/js/nuxt.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import colors from "picocolors";
 import { readBridgeConfig } from "./shared/bridge-schema.js";
 import { DEBOUNCE_MS } from "./shared/constants.js";
-import { normalizeHost, resolveHotFilePath } from "./shared/network.js";
+import { normalizeHost, resolveHotFilePath, resolveLitestarPort } from "./shared/network.js";
 import { createLitestarTypeGenPlugin } from "./shared/typegen-plugin.js";
 function resolveConfig(config = {}) {
   let hotFile;
@@ -19,6 +19,8 @@ function resolveConfig(config = {}) {
     }
   }
   let pythonExecutor;
+  let assetUrl;
+  let litestarPort;
   const runtime = readBridgeConfig();
   if (runtime) {
     hasPythonConfig = true;
@@ -27,10 +29,15 @@ function resolveConfig(config = {}) {
     proxyMode = runtime.proxyMode;
     devPort = runtime.port;
     pythonExecutor = runtime.executor;
+    assetUrl = runtime.assetUrl;
     if (runtime.types) {
       pythonTypesConfig = runtime.types;
     }
   }
+  const resolvedLitestarPort = resolveLitestarPort(runtime?.litestarPort, runtime?.appUrl);
+  if (resolvedLitestarPort !== null) {
+    litestarPort = resolvedLitestarPort;
+  }
   let typesConfig = false;
   const defaultTypesOutput = "generated";
   const buildTypeDefaults = (output) => ({
@@ -107,6 +114,8 @@ function resolveConfig(config = {}) {
     hotFile,
     proxyMode,
     devPort,
+    litestarPort,
+    assetUrl,
     executor: config.executor ?? pythonExecutor,
     hasPythonConfig
   };
@@ -131,6 +140,8 @@ function createProxyPlugin(config) {
     name: "litestar-nuxt-proxy",
     async config() {
       hmrPort = await getPort();
+      const hmrPath = `${(config.assetUrl ?? "/static").replace(/\/$/, "")}/vite-hmr`;
+      const browserHmrPort = config.litestarPort ?? config.devPort;
       return {
         server: {
           // Force IPv4 binding for consistency with Python proxy configuration
@@ -142,11 +153,13 @@ function createProxyPlugin(config) {
             port: config.devPort,
             strictPort: true
           } : {},
-          // Avoid HMR port collisions by letting Vite pick a free port for WS
+          // Vite serves HMR on a separate internal port; browsers reach it through
+          // Litestar's /static/vite-hmr WebSocket handler.
           hmr: {
             port: hmrPort,
             host: "127.0.0.1",
-            clientPort: config.devPort
+            ...browserHmrPort !== void 0 ? { clientPort: browserHmrPort } : {},
+            ...config.litestarPort !== void 0 ? { path: hmrPath, protocol: "ws" } : {}
           }
         }
       };

package/dist/js/shared/bridge-schema.d.ts

@@ -34,6 +34,13 @@ export interface BridgeSchema {
     assetUrl: string;
     deployAssetUrl: string | null;
     appUrl: string | null;
+    /**
+     * Litestar dev server port. Used by framework integrations to set
+     * `vite.server.hmr.clientPort`, ensuring the browser connects to Litestar
+     * (not the framework dev server) for HMR — preserving the single-port
+     * contract.
+     */
+    litestarPort: number | null;
     bundleDir: string;
     resourceDir: string;
     staticDir: string;

package/dist/js/shared/bridge-schema.js

@@ -4,6 +4,7 @@ const allowedTopLevelKeys = /* @__PURE__ */ new Set([
   "assetUrl",
   "deployAssetUrl",
   "appUrl",
+  "litestarPort",
   "bundleDir",
   "resourceDir",
   "staticDir",
@@ -71,6 +72,14 @@ function assertOptionalNullableString(obj, key) {
   }
   return value;
 }
+function assertOptionalNullableInteger(obj, key) {
+  const value = obj[key];
+  if (value === void 0 || value === null) return null;
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    fail(`"${key}" must be a positive integer or null`);
+  }
+  return value;
+}
 function assertOptionalString(obj, key) {
   const value = obj[key];
   if (value === void 0) return void 0;
@@ -159,6 +168,7 @@ function parseBridgeSchema(value) {
   const assetUrl = assertString(obj, "assetUrl");
   const deployAssetUrl = assertNullableString(obj, "deployAssetUrl");
   const appUrl = assertOptionalNullableString(obj, "appUrl");
+  const litestarPort = assertOptionalNullableInteger(obj, "litestarPort");
   const bundleDir = assertString(obj, "bundleDir");
   const resourceDir = assertString(obj, "resourceDir");
   const staticDir = assertString(obj, "staticDir");
@@ -179,6 +189,7 @@ function parseBridgeSchema(value) {
     assetUrl,
     deployAssetUrl,
     appUrl,
+    litestarPort,
     bundleDir,
     resourceDir,
     staticDir,

package/dist/js/shared/network.d.ts

@@ -21,6 +21,21 @@
  * ```
  */
 export declare function normalizeHost(host: string): string;
+/**
+ * Resolve the Litestar dev server port for HMR routing.
+ *
+ * Framework integrations (Astro/Nuxt/SvelteKit) need this port to set
+ * `vite.server.hmr.clientPort` so the browser opens the HMR WebSocket against
+ * Litestar — NOT the framework dev server's port — preserving the
+ * single-port-via-ASGI contract.
+ *
+ * Resolution order:
+ *   1. `bridge.litestarPort` (preferred; written by Python ≥0.23.0).
+ *   2. Parse `bridge.appUrl` (works with older bridges that lack `litestarPort`).
+ *   3. `LITESTAR_PORT` / `PORT` env var.
+ *   4. `null` if no signal.
+ */
+export declare function resolveLitestarPort(bridgeLitestarPort: number | null | undefined, bridgeAppUrl: string | null | undefined, env?: NodeJS.ProcessEnv): number | null;
 /**
  * Resolve the absolute hot file path from bundleDir + hotFile.
  *

package/dist/js/shared/network.js

@@ -8,6 +8,29 @@ function normalizeHost(host) {
   }
   return host;
 }
+function resolveLitestarPort(bridgeLitestarPort, bridgeAppUrl, env = process.env) {
+  if (typeof bridgeLitestarPort === "number" && Number.isInteger(bridgeLitestarPort) && bridgeLitestarPort > 0) {
+    return bridgeLitestarPort;
+  }
+  if (typeof bridgeAppUrl === "string" && bridgeAppUrl.length > 0) {
+    try {
+      const parsed = new URL(bridgeAppUrl);
+      if (parsed.port) {
+        const p = Number.parseInt(parsed.port, 10);
+        if (!Number.isNaN(p) && p > 0) return p;
+      }
+      if (parsed.protocol === "https:") return 443;
+      if (parsed.protocol === "http:") return 80;
+    } catch {
+    }
+  }
+  const raw = env.LITESTAR_PORT ?? env.PORT;
+  if (raw) {
+    const p = Number.parseInt(raw, 10);
+    if (!Number.isNaN(p) && p > 0) return p;
+  }
+  return null;
+}
 function resolveHotFilePath(bundleDir, hotFile, rootDir = process.cwd()) {
   if (path.isAbsolute(hotFile)) {
     return hotFile;
@@ -21,5 +44,6 @@ function resolveHotFilePath(bundleDir, hotFile, rootDir = process.cwd()) {
 }
 export {
   normalizeHost,
-  resolveHotFilePath
+  resolveHotFilePath,
+  resolveLitestarPort
 };

package/dist/js/sveltekit.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import colors from "picocolors";
 import { readBridgeConfig } from "./shared/bridge-schema.js";
 import { DEBOUNCE_MS } from "./shared/constants.js";
-import { normalizeHost, resolveHotFilePath } from "./shared/network.js";
+import { normalizeHost, resolveHotFilePath, resolveLitestarPort } from "./shared/network.js";
 import { createLitestarTypeGenPlugin } from "./shared/typegen-plugin.js";
 function resolveConfig(config = {}) {
   let hotFile;
@@ -19,6 +19,8 @@ function resolveConfig(config = {}) {
     }
   }
   let pythonExecutor;
+  let assetUrl;
+  let litestarPort;
   const runtime = readBridgeConfig();
   if (runtime) {
     hasPythonConfig = true;
@@ -27,10 +29,15 @@ function resolveConfig(config = {}) {
     proxyMode = runtime.proxyMode;
     port = runtime.port;
     pythonExecutor = runtime.executor;
+    assetUrl = runtime.assetUrl;
     if (runtime.types) {
       pythonTypesConfig = runtime.types;
     }
   }
+  const resolvedLitestarPort = resolveLitestarPort(runtime?.litestarPort, runtime?.appUrl);
+  if (resolvedLitestarPort !== null) {
+    litestarPort = resolvedLitestarPort;
+  }
   let typesConfig = false;
   const defaultTypesOutput = "src/lib/generated";
   const buildTypeDefaults = (output) => ({
@@ -107,6 +114,8 @@ function resolveConfig(config = {}) {
     hotFile,
     proxyMode,
     port,
+    litestarPort,
+    assetUrl,
     executor: config.executor ?? pythonExecutor,
     hasPythonConfig
   };
@@ -118,6 +127,7 @@ function litestarSvelteKit(userConfig = {}) {
     name: "litestar-sveltekit",
     enforce: "pre",
     config() {
+      const hmrPath = `${(config.assetUrl ?? "/static").replace(/\/$/, "")}/vite-hmr`;
       return {
         server: {
           // Force IPv4 binding for consistency with Python proxy configuration
@@ -129,6 +139,15 @@ function litestarSvelteKit(userConfig = {}) {
             port: config.port,
             strictPort: true
           } : {},
+          // Route HMR through the Litestar port so DevTools never sees the framework port.
+          ...config.litestarPort !== void 0 ? {
+            hmr: {
+              protocol: "ws",
+              host: "127.0.0.1",
+              clientPort: config.litestarPort,
+              path: hmrPath
+            }
+          } : {},
           proxy: {
             [config.apiPrefix]: {
               target: config.apiProxy,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "litestar-vite-plugin",
-  "version": "0.22.2",
+  "version": "0.23.0",
   "type": "module",
   "description": "Litestar plugin for Vite.",
   "keywords": [