litestar-vite-plugin 0.15.0-rc.1 → 0.15.0-rc.3

package/dist/js/inertia-types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Base types for Inertia.js type generation.
+ *
+ * These types are generated by `litestar assets generate-types` in your
+ * project's `generated/page-props.ts` file. This module provides fallback
+ * types for when the generated file hasn't been created yet.
+ *
+ * To customize types, edit your project's `generated/page-props.user.ts` file.
+ */
+/** User interface - customize in page-props.user.ts */
+export interface User {
+}
+/** Authentication data interface */
+export interface AuthData {
+}
+/** Flash messages interface */
+export interface FlashMessages {
+}
+/** User-defined shared props - customize in page-props.user.ts */
+export interface SharedProps {
+}
+/** Generated shared props (populated by page-props.ts) */
+export interface GeneratedSharedProps {
+}
+/** Full shared props = generated + user-defined */
+export type FullSharedProps = GeneratedSharedProps & SharedProps & {
+    [key: string]: unknown;
+};
+/** Page props mapped by component name (populated by page-props.ts) */
+export interface PageProps {
+}
+/** Component name union type */
+export type ComponentName = keyof PageProps;
+/** Type-safe props for a specific component */
+export type InertiaPageProps<C extends ComponentName> = PageProps[C];
+/** Get props type for a specific page component */
+export type PagePropsFor<C extends ComponentName> = PageProps[C];

package/dist/js/install-hint.d.ts

@@ -1,7 +1,12 @@
+/**
+ * Detect the executor from .litestar.json or environment.
+ * Priority: LITESTAR_VITE_RUNTIME env > .litestar.json executor > lockfile detection > 'node'
+ */
+export declare function detectExecutor(): string;
 export declare function resolveInstallHint(pkg?: string): string;
 /**
  * Resolves the package executor command based on runtime.
- * Priority: explicit executor > LITESTAR_VITE_RUNTIME env > 'node' default
+ * Priority: explicit executor > .litestar.json > LITESTAR_VITE_RUNTIME env > lockfile detection > 'npx'
  *
  * @param pkg - The package command to execute (e.g., "@hey-api/openapi-ts -i schema.json -o src/types")
  * @param executor - Optional explicit executor override

package/dist/js/install-hint.js

@@ -1,5 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+function detectExecutor() {
+  const envRuntime = (process.env.LITESTAR_VITE_RUNTIME ?? "").toLowerCase();
+  if (envRuntime) return envRuntime;
+  const configPath = process.env.LITESTAR_VITE_CONFIG_PATH ?? path.resolve(process.cwd(), ".litestar.json");
+  if (fs.existsSync(configPath)) {
+    try {
+      const raw = fs.readFileSync(configPath, "utf8");
+      const data = JSON.parse(raw);
+      const executor = data?.executor;
+      if (typeof executor === "string" && executor.trim()) {
+        return executor.trim().toLowerCase();
+      }
+    } catch {
+    }
+  }
+  const cwd = process.cwd();
+  if (fs.existsSync(path.join(cwd, "bun.lockb")) || fs.existsSync(path.join(cwd, "bun.lock"))) {
+    return "bun";
+  }
+  if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) {
+    return "pnpm";
+  }
+  if (fs.existsSync(path.join(cwd, "yarn.lock"))) {
+    return "yarn";
+  }
+  if (fs.existsSync(path.join(cwd, "deno.lock"))) {
+    return "deno";
+  }
+  return "node";
+}
 function resolveInstallHint(pkg = "@hey-api/openapi-ts") {
-  const runtime = (process.env.LITESTAR_VITE_RUNTIME ?? "").toLowerCase();
+  const runtime = detectExecutor();
   switch (runtime) {
     case "bun":
       return `bun add -d ${pkg}`;
@@ -17,7 +49,7 @@ function resolveInstallHint(pkg = "@hey-api/openapi-ts") {
   return `npm install -D ${pkg}`;
 }
 function resolvePackageExecutor(pkg, executor) {
-  const runtime = (executor ?? process.env.LITESTAR_VITE_RUNTIME ?? "").toLowerCase();
+  const runtime = executor || detectExecutor();
   switch (runtime) {
     case "bun":
       return `bunx ${pkg}`;
@@ -32,6 +64,7 @@ function resolvePackageExecutor(pkg, executor) {
   }
 }
 export {
+  detectExecutor,
   resolveInstallHint,
   resolvePackageExecutor
 };

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

@@ -8,7 +8,7 @@
  *
  * @module
  */
-export type BridgeMode = "spa" | "template" | "htmx" | "hybrid" | "inertia" | "ssr" | "ssg" | "external";
+export type BridgeMode = "spa" | "template" | "htmx" | "hybrid" | "inertia" | "framework" | "ssr" | "ssg" | "external";
 export type BridgeProxyMode = "vite" | "direct" | "proxy" | null;
 export type BridgeExecutor = "node" | "bun" | "deno" | "yarn" | "pnpm";
 export interface BridgeTypesConfig {
@@ -23,8 +23,13 @@ export interface BridgeTypesConfig {
     generatePageProps: boolean;
     globalRoute: boolean;
 }
+export interface BridgeSpaConfig {
+    /** Use script element instead of data-page attribute for Inertia page data */
+    useScriptElement: boolean;
+}
 export interface BridgeSchema {
     assetUrl: string;
+    deployAssetUrl: string | null;
     bundleDir: string;
     resourceDir: string;
     staticDir: string;
@@ -34,9 +39,9 @@ export interface BridgeSchema {
     proxyMode: BridgeProxyMode;
     host: string;
     port: number;
-    ssrEnabled: boolean;
     ssrOutDir: string | null;
     types: BridgeTypesConfig | null;
+    spa: BridgeSpaConfig | null;
     executor: BridgeExecutor;
     logging: {
         level: "quiet" | "normal" | "verbose";

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

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 const allowedTopLevelKeys = /* @__PURE__ */ new Set([
   "assetUrl",
+  "deployAssetUrl",
   "bundleDir",
   "resourceDir",
   "staticDir",
@@ -11,14 +12,14 @@ const allowedTopLevelKeys = /* @__PURE__ */ new Set([
   "proxyMode",
   "host",
   "port",
-  "ssrEnabled",
   "ssrOutDir",
   "types",
+  "spa",
   "executor",
   "logging",
   "litestarVersion"
 ]);
-const allowedModes = /* @__PURE__ */ new Set(["spa", "template", "htmx", "hybrid", "inertia", "ssr", "ssg", "external"]);
+const allowedModes = /* @__PURE__ */ new Set(["spa", "template", "htmx", "hybrid", "inertia", "framework", "ssr", "ssg", "external"]);
 const allowedProxyModes = /* @__PURE__ */ new Set(["vite", "direct", "proxy"]);
 const allowedExecutors = /* @__PURE__ */ new Set(["node", "bun", "deno", "yarn", "pnpm"]);
 const allowedLogLevels = /* @__PURE__ */ new Set(["quiet", "normal", "verbose"]);
@@ -106,6 +107,12 @@ function parseLogging(value) {
   const timestamps = assertBoolean(obj, "timestamps");
   return { level, showPathsAbsolute, suppressNpmOutput, suppressViteBanner, timestamps };
 }
+function parseSpaConfig(value) {
+  if (value === null || value === void 0) return null;
+  const obj = assertObject(value, "spa");
+  const useScriptElement = assertBoolean(obj, "useScriptElement");
+  return { useScriptElement };
+}
 function parseBridgeSchema(value) {
   const obj = assertObject(value, "root");
   for (const key of Object.keys(obj)) {
@@ -114,6 +121,7 @@ function parseBridgeSchema(value) {
     }
   }
   const assetUrl = assertString(obj, "assetUrl");
+  const deployAssetUrl = assertNullableString(obj, "deployAssetUrl");
   const bundleDir = assertString(obj, "bundleDir");
   const resourceDir = assertString(obj, "resourceDir");
   const staticDir = assertString(obj, "staticDir");
@@ -123,14 +131,15 @@ function parseBridgeSchema(value) {
   const proxyMode = assertProxyMode(obj.proxyMode);
   const host = assertString(obj, "host");
   const port = assertNumber(obj, "port");
-  const ssrEnabled = assertBoolean(obj, "ssrEnabled");
   const ssrOutDir = assertNullableString(obj, "ssrOutDir");
   const types = parseTypesConfig(obj.types);
+  const spa = parseSpaConfig(obj.spa);
   const executor = assertEnum(obj.executor, "executor", allowedExecutors);
   const logging = parseLogging(obj.logging);
   const litestarVersion = assertString(obj, "litestarVersion");
   return {
     assetUrl,
+    deployAssetUrl,
     bundleDir,
     resourceDir,
     staticDir,
@@ -140,9 +149,9 @@ function parseBridgeSchema(value) {
     proxyMode,
     host,
     port,
-    ssrEnabled,
     ssrOutDir,
     types,
+    spa,
     executor,
     logging,
     litestarVersion

package/dist/js/shared/emit-page-props-types.d.ts

@@ -1,4 +1,6 @@
 /**
  * Generate `page-props.ts` from `inertia-pages.json` metadata.
+ *
+ * @returns true if file was changed, false if unchanged
  */
-export declare function emitPagePropsTypes(pagesPath: string, outputDir: string): Promise<void>;
+export declare function emitPagePropsTypes(pagesPath: string, outputDir: string): Promise<boolean>;

package/dist/js/shared/emit-page-props-types.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { writeIfChanged } from "./write-if-changed.js";
 async function emitPagePropsTypes(pagesPath, outputDir) {
   const contents = await fs.promises.readFile(pagesPath, "utf-8");
   const json = JSON.parse(contents);
@@ -16,18 +17,9 @@ async function emitPagePropsTypes(pagesPath, outputDir) {
   if (includeDefaultAuth) {
     userTypes = `/**
  * Default User interface - minimal baseline for common auth patterns.
- * Users extend this via module augmentation with their full user model.
- *
- * @example
- * declare module 'litestar-vite-plugin/inertia' {
- *   interface User {
- *     avatarUrl?: string | null
- *     roles: Role[]
- *     teams: Team[]
- *   }
- * }
+ * Extend by adding properties to UserExtensions in page-props.user.ts
  */
-export interface User {
+export interface User extends UserExtensions {
   id: string
   email: string
   name?: string | null
@@ -46,23 +38,13 @@ export interface AuthData {
 `;
   } else {
     userTypes = `/**
- * User interface - define via module augmentation.
- * Default auth types are disabled.
- *
- * @example
- * declare module 'litestar-vite-plugin/inertia' {
- *   interface User {
- *     uuid: string
- *     username: string
- *   }
- * }
+ * User interface - add properties to UserExtensions in page-props.user.ts
  */
-export interface User {}
+export interface User extends UserExtensions {}
 
 `;
     authTypes = `/**
- * AuthData interface - define via module augmentation.
- * Default auth types are disabled.
+ * AuthData interface - define your auth structure here or in page-props.user.ts
  */
 export interface AuthData {}
 
@@ -163,7 +145,7 @@ export interface FlashMessages {}
   const availableApiTypes = /* @__PURE__ */ new Set();
   if (fs.existsSync(apiTypesPath)) {
     const content = await fs.promises.readFile(apiTypesPath, "utf-8");
-    for (const match of content.matchAll(/export (?:type|interface|enum|class) (\\w+)/g)) {
+    for (const match of content.matchAll(/export (?:type|interface|enum|class) (\w+)/g)) {
       if (match[1]) {
         availableApiTypes.add(match[1]);
       }
@@ -184,7 +166,13 @@ export interface FlashMessages {}
     }
   }
   if (unresolvedTypes.length > 0) {
-    console.warn(`litestar-vite: unresolved Inertia props types: ${unresolvedTypes.join(", ")}. Add them to TypeGenConfig.type_import_paths or include them in OpenAPI.`);
+    console.warn(
+      `litestar-vite: Unresolved Inertia props types: ${unresolvedTypes.join(", ")}.
+  To fix:
+  1. Add to OpenAPI by including in route return types
+  2. Or configure TypeGenConfig.type_import_paths:
+     types=TypeGenConfig(type_import_paths={"${unresolvedTypes[0]}": "@/types/custom"})`
+    );
   }
   let importStatement = "";
   if (apiImports.length > 0) {
@@ -211,6 +199,9 @@ export interface FlashMessages {}
   const body = `// AUTO-GENERATED by litestar-vite. Do not edit.
 /* eslint-disable */
 
+// Import user-defined type extensions (edit page-props.user.ts to customize)
+import type { UserExtensions, SharedPropsExtensions } from "./page-props.user"
+
 ${importStatement}${userTypes}${authTypes}${flashTypes}/**
  * Generated shared props (always present).
  * Includes built-in props + static config props.
@@ -221,26 +212,13 @@ ${generatedSharedPropLines.join("\n")}
 
 /**
  * User-defined shared props for dynamic share() calls in guards/middleware.
- * Extend this interface via module augmentation.
- *
- * @example
- * declare module 'litestar-vite-plugin/inertia' {
- *   interface User {
- *     avatarUrl?: string | null
- *     roles: Role[]
- *     teams: Team[]
- *   }
- *   interface SharedProps {
- *     locale?: string
- *     currentTeam?: CurrentTeam
- *   }
- * }
+ * Extend by adding properties to SharedPropsExtensions in page-props.user.ts
  */
-export interface SharedProps {
-}
+export type SharedProps = SharedPropsExtensions
 
-/** Full shared props = generated + user-defined */
-export type FullSharedProps = GeneratedSharedProps & SharedProps
+/** Full shared props = generated + user-defined.
+ * Includes index signature for compatibility with Inertia's usePage<T>(). */
+export type FullSharedProps = GeneratedSharedProps & SharedProps & { [key: string]: unknown }
 
 /** Page props mapped by component name */
 export interface PageProps {
@@ -255,13 +233,57 @@ export type InertiaPageProps<C extends ComponentName> = PageProps[C]
 
 /** Get props type for a specific page component */
 export type PagePropsFor<C extends ComponentName> = PageProps[C]
+`;
+  const result = await writeIfChanged(outFile, body, { encoding: "utf-8" });
+  const userStubFile = path.join(outDir, "page-props.user.ts");
+  if (!fs.existsSync(userStubFile)) {
+    const userStub = `/**
+ * User-defined type extensions for Inertia page props.
+ * This file is generated ONCE and never overwritten - edit freely!
+ *
+ * Add properties to these interfaces to extend the generated types.
+ * The main page-props.ts file imports and uses these extensions.
+ */
+
+/**
+ * Extend the User interface with additional properties.
+ *
+ * @example
+ * export interface UserExtensions {
+ *   avatarUrl?: string | null
+ *   roles: string[]
+ *   teams: Team[]
+ * }
+ */
+export interface UserExtensions {
+  // Add your custom User properties here
+}
 
-// Re-export for module augmentation
-declare module "litestar-vite-plugin/inertia" {
-  export { User, AuthData, FlashMessages, SharedProps, GeneratedSharedProps, FullSharedProps, PageProps, ComponentName, InertiaPageProps, PagePropsFor }
+/**
+ * Extend SharedProps with session-based or dynamic properties.
+ *
+ * @example
+ * export interface SharedPropsExtensions {
+ *   locale?: string
+ *   currentTeam?: {
+ *     teamId: string
+ *     teamName: string
+ *   }
+ * }
+ */
+export interface SharedPropsExtensions {
+  // Add your custom shared props here
 }
+
+// Export custom types that can be used in page props
+// export interface CurrentTeam {
+//   teamId: string
+//   teamName: string
+// }
 `;
-  await fs.promises.writeFile(outFile, body, "utf-8");
+    await fs.promises.writeFile(userStubFile, userStub, "utf-8");
+  }
+  return result.changed;
 }
 export {
   emitPagePropsTypes

package/dist/js/shared/typegen-cache.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Check if openapi-ts should run based on input cache.
+ *
+ * @param openapiPath - Path to openapi.json
+ * @param configPath - Path to config file (or null)
+ * @param options - Generator options
+ * @returns true if generation should run, false if cached
+ */
+export declare function shouldRunOpenApiTs(openapiPath: string, configPath: string | null, options: {
+    generateSdk: boolean;
+    generateZod: boolean;
+    plugins: string[];
+}): Promise<boolean>;
+/**
+ * Update cache after successful openapi-ts run.
+ *
+ * @param openapiPath - Path to openapi.json
+ * @param configPath - Path to config file (or null)
+ * @param options - Generator options
+ */
+export declare function updateOpenApiTsCache(openapiPath: string, configPath: string | null, options: {
+    generateSdk: boolean;
+    generateZod: boolean;
+    plugins: string[];
+}): Promise<void>;
+/**
+ * Compute input hash for page props generation.
+ *
+ * @param pagePropsPath - Path to inertia-pages.json
+ * @returns Hash of the input file
+ */
+export declare function computePagePropsHash(pagePropsPath: string): Promise<string>;
+/**
+ * Check if page props types should be regenerated.
+ *
+ * @param pagePropsPath - Path to inertia-pages.json
+ * @returns true if generation should run, false if cached
+ */
+export declare function shouldRegeneratePageProps(pagePropsPath: string): Promise<boolean>;
+/**
+ * Update cache after successful page props generation.
+ *
+ * @param pagePropsPath - Path to inertia-pages.json
+ */
+export declare function updatePagePropsCache(pagePropsPath: string): Promise<void>;

package/dist/js/shared/typegen-cache.js

@@ -0,0 +1,83 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+const CACHE_DIR = "node_modules/.cache/litestar-vite";
+const CACHE_FILE = "typegen-cache.json";
+async function loadCache() {
+  const cacheFilePath = path.join(CACHE_DIR, CACHE_FILE);
+  try {
+    const content = await fs.promises.readFile(cacheFilePath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return {};
+  }
+}
+async function saveCache(cache) {
+  const cacheFilePath = path.join(CACHE_DIR, CACHE_FILE);
+  await fs.promises.mkdir(CACHE_DIR, { recursive: true });
+  await fs.promises.writeFile(cacheFilePath, JSON.stringify(cache, null, 2), "utf-8");
+}
+async function hashFile(filePath) {
+  try {
+    const content = await fs.promises.readFile(filePath);
+    return crypto.createHash("sha256").update(content).digest("hex");
+  } catch {
+    return "";
+  }
+}
+function hashObject(obj) {
+  const sorted = JSON.stringify(obj, Object.keys(obj).sort());
+  return crypto.createHash("sha256").update(sorted).digest("hex");
+}
+async function shouldRunOpenApiTs(openapiPath, configPath, options) {
+  const cache = await loadCache();
+  const inputHash = await hashFile(openapiPath);
+  const configHash = configPath ? await hashFile(configPath) : "";
+  const optionsHash = hashObject(options);
+  const cacheKey = "openapi-ts";
+  const entry = cache[cacheKey];
+  if (entry && entry.inputHash === inputHash && entry.configHash === configHash && entry.optionsHash === optionsHash) {
+    return false;
+  }
+  return true;
+}
+async function updateOpenApiTsCache(openapiPath, configPath, options) {
+  const cache = await loadCache();
+  cache["openapi-ts"] = {
+    inputHash: await hashFile(openapiPath),
+    configHash: configPath ? await hashFile(configPath) : "",
+    optionsHash: hashObject(options),
+    timestamp: Date.now()
+  };
+  await saveCache(cache);
+}
+async function computePagePropsHash(pagePropsPath) {
+  return hashFile(pagePropsPath);
+}
+async function shouldRegeneratePageProps(pagePropsPath) {
+  const cache = await loadCache();
+  const currentHash = await hashFile(pagePropsPath);
+  const cacheKey = "page-props";
+  const entry = cache[cacheKey];
+  if (entry && entry.inputHash === currentHash) {
+    return false;
+  }
+  return true;
+}
+async function updatePagePropsCache(pagePropsPath) {
+  const cache = await loadCache();
+  cache["page-props"] = {
+    inputHash: await hashFile(pagePropsPath),
+    configHash: "",
+    optionsHash: "",
+    timestamp: Date.now()
+  };
+  await saveCache(cache);
+}
+export {
+  computePagePropsHash,
+  shouldRegeneratePageProps,
+  shouldRunOpenApiTs,
+  updateOpenApiTsCache,
+  updatePagePropsCache
+};

package/dist/js/shared/typegen-core.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Configuration for type generation.
+ */
+export interface TypeGenCoreConfig {
+    /** Project root directory */
+    projectRoot: string;
+    /** Path to openapi.json (relative or absolute) */
+    openapiPath: string;
+    /** Output directory for generated files */
+    output: string;
+    /** Path to inertia-pages.json (relative or absolute) */
+    pagePropsPath: string;
+    /** Whether to generate SDK client */
+    generateSdk: boolean;
+    /** Whether to generate Zod schemas */
+    generateZod: boolean;
+    /** Whether to generate page props types */
+    generatePageProps: boolean;
+    /** SDK client plugin (e.g., "@hey-api/client-fetch") */
+    sdkClientPlugin: string;
+    /** JS runtime executor (e.g., "bun", "pnpm") */
+    executor?: string;
+}
+/**
+ * Result of type generation.
+ */
+export interface TypeGenResult {
+    /** Whether any files were generated */
+    generated: boolean;
+    /** Files that were generated/updated */
+    generatedFiles: string[];
+    /** Files that were skipped (unchanged) */
+    skippedFiles: string[];
+    /** Total duration in milliseconds */
+    durationMs: number;
+    /** Any warnings to report */
+    warnings: string[];
+    /** Any errors encountered */
+    errors: string[];
+}
+/**
+ * Logger interface for type generation.
+ * Allows callers to inject their own logging behavior.
+ */
+export interface TypeGenLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+/**
+ * Options for running type generation.
+ */
+export interface RunTypeGenOptions {
+    /** Logger for output (optional - silent if not provided) */
+    logger?: TypeGenLogger;
+}
+/**
+ * Find user's openapi-ts config file.
+ */
+export declare function findOpenApiTsConfig(projectRoot: string): string | null;
+/**
+ * Build the list of plugins for @hey-api/openapi-ts.
+ */
+export declare function buildHeyApiPlugins(config: {
+    generateSdk: boolean;
+    generateZod: boolean;
+    sdkClientPlugin: string;
+}): string[];
+/**
+ * Run @hey-api/openapi-ts to generate TypeScript types from OpenAPI spec.
+ *
+ * @param config - Type generation configuration
+ * @param configPath - Path to user's openapi-ts config (or null for default)
+ * @param plugins - List of plugins to use
+ * @param logger - Optional logger for output
+ * @returns Path to output directory
+ */
+export declare function runHeyApiGeneration(config: TypeGenCoreConfig, configPath: string | null, plugins: string[], logger?: TypeGenLogger): Promise<string>;
+/**
+ * Run the complete type generation pipeline.
+ *
+ * This is the main entry point for type generation, handling:
+ * - OpenAPI type generation via @hey-api/openapi-ts
+ * - Page props type generation
+ *
+ * @param config - Type generation configuration
+ * @param options - Runtime options (logger, etc.)
+ * @returns Result with generated files and timing info
+ */
+export declare function runTypeGeneration(config: TypeGenCoreConfig, options?: RunTypeGenOptions): Promise<TypeGenResult>;