Static Props¶

Static props let you pass arbitrary configuration data from Python to JavaScript at build time.

Application settings such as app name, version, or environment
Feature flags and toggles
API base URLs or similar static configuration
Any data that is JSON-serializable and stable at build time

Python Setup¶

Add static props to your ViteConfig:

from litestar_vite import ViteConfig, VitePlugin

app = Litestar(
    plugins=[
        VitePlugin(
            config=ViteConfig(
                static_props={
                    "appName": "My Application",
                    "version": "1.0.0",
                    "environment": "production",
                    "features": {
                        "darkMode": True,
                        "analytics": False,
                    },
                },
            )
        )
    ]
)

The props are serialized to .litestar.json and made available to JavaScript via a virtual module.

Usage in JavaScript/TypeScript¶

Import static props using the virtual module:

// Default import - all props as an object
import staticProps from 'virtual:litestar-static-props'

console.log(staticProps.appName)  // "My Application"
console.log(staticProps.features.darkMode)  // true

// Named imports for valid JS identifiers
import { appName, version, features } from 'virtual:litestar-static-props'

console.log(appName)  // "My Application"

Type Generation¶

When type generation is enabled, litestar-vite automatically generates typed declarations for your static props. The generated file is placed in your output directory, typically src/generated/static-props.ts:

// AUTO-GENERATED by litestar-vite
export interface Features {
  darkMode: boolean
  analytics: boolean
}

export interface StaticProps {
  appName: string
  version: string
  environment: string
  features: Features
}

export const staticProps: StaticProps = { ... } as const satisfies StaticProps

export const appName = staticProps.appName
export const version = staticProps.version
export const features = staticProps.features

export default staticProps

You can import from either the virtual module or the generated file:

// Virtual module (runtime) - no type info without augmentation
import staticProps from 'virtual:litestar-static-props'

// Generated file (build time) - fully typed
import { appName, features } from './generated/static-props'

Type Augmentation (Optional)¶

For full type safety with the virtual module, you can augment the module declaration:

// src/types/static-props.d.ts
declare module 'virtual:litestar-static-props' {
  interface StaticProps {
    appName: string
    version: string
    environment: string
    features: {
      darkMode: boolean
      analytics: boolean
    }
  }

  const props: StaticProps
  export default props
  export const appName: string
  export const version: string
  export const features: StaticProps['features']
}

Limitations¶

No HMR: Static props are resolved at plugin initialization. Changes to static_props require a Vite restart.
Build-time only: Values are embedded at build time and cannot be changed at runtime.
JSON-serializable: Props must be JSON-serializable. Use ISO strings for dates and avoid functions or complex objects.