@stacksjs/stx
Version:
A performant UI Framework. Powered by Bun.
120 lines • 4.29 kB
TypeScript
/**
* Generate the HMR client script for browser
*/
export declare function generateHMRClientScript(wsPort: number): string;
/**
* Generate component wrapper code for HMR support
*/
export declare function wrapComponentForHMR(componentId: string, componentName: string, html: string, script: string): string;
/**
* Get or create global HMR handler
*/
export declare function getHMRHandler(config?: ComponentHMRConfig): ComponentHMRHandler;
/**
* Reset global HMR handler
*/
export declare function resetHMRHandler(): void;
/**
* Component HMR (Hot Module Replacement)
*
* Provides React Fast Refresh / Vue HMR-style hot reloading for stx components.
* Updates component code without losing component state or unmounting.
*
* ## Features
*
* - State preservation during component updates
* - Selective component re-rendering
* - Error recovery with state restoration
* - Integration with stx reactivity system
* - Support for nested component updates
*
* ## Usage
*
* Component HMR is automatically enabled in development mode. No configuration needed.
*
* @module component-hmr
*/
// =============================================================================
// Types
// =============================================================================
export declare interface ComponentState {
refs: Record<string, unknown>
reactiveObjects: Record<string, unknown>
custom: Record<string, unknown>
timestamp: number
}
export declare interface ComponentInstance {
id: string
name: string
element: HTMLElement | null
state: ComponentState
isMounted: boolean
props: Record<string, unknown>
children: Map<string, ComponentInstance>
setup?: () => void | Promise<void>
render?: () => string
cleanup?: () => void
}
export declare interface HMRUpdate {
file: string
code: string
type: 'full' | 'partial' | 'style'
timestamp: number
}
export declare interface ComponentHMRConfig {
preserveState?: boolean
maxStateAge?: number
errorRecovery?: boolean
verbose?: boolean
serializeState?: (instance: ComponentInstance) => ComponentState
deserializeState?: (state: ComponentState, instance: ComponentInstance) => void
}
/**
* Global registry of component instances for HMR
*/
declare class ComponentRegistry {
private instances: Map<string, ComponentInstance>;
private componentsByFile: Map<string, Set<string>>;
private stateSnapshots: Map<string, ComponentState>;
private config: Required<ComponentHMRConfig>;
constructor(config?: ComponentHMRConfig);
register(instance: ComponentInstance): void;
unregister(instanceId: string): void;
getInstancesByFile(file: string): ComponentInstance[];
getInstance(id: string): ComponentInstance | undefined;
captureState(instanceId: string): void;
restoreState(instanceId: string): boolean;
private defaultSerializeState(instance: ComponentInstance): ComponentState;
private defaultDeserializeState(state: ComponentState, instance: ComponentInstance): void;
getAllInstances(): ComponentInstance[];
clear(): void;
}
/**
* HMR Handler - processes component updates
*/
export declare class ComponentHMRHandler {
private registry: ComponentRegistry;
private config: Required<ComponentHMRConfig>;
private pendingUpdates: Map<string, HMRUpdate>;
private updateQueue: Promise<void>;
constructor(config?: ComponentHMRConfig);
register(instance: ComponentInstance): void;
unregister(instanceId: string): void;
handleUpdate(update: HMRUpdate): Promise<void>;
private processUpdate(update: HMRUpdate): Promise<void>;
private updateInstance(instance: ComponentInstance, update: HMRUpdate): Promise<void>;
private updateComponent(instance: ComponentInstance, update: HMRUpdate): Promise<void>;
private updateStyles(instance: ComponentInstance, update: HMRUpdate): Promise<void>;
private parseComponentCode(code: string): { html: string; script: string; style: string };
private executeScript(script: string, instance: ComponentInstance): Promise<void>;
private reinitializeInteractivity(instance: ComponentInstance): void;
getRegistry(): ComponentRegistry;
refresh(componentName: string): Promise<void>;
}
export default {
ComponentHMRHandler,
getHMRHandler,
resetHMRHandler,
generateHMRClientScript,
wrapComponentForHMR,
};