Hot Module Replacement (HMR)

Ecopages features a custom, integration-aware Hot Module Replacement system designed to provide instant feedback while preserving your application's state where possible.

How it Works

The HMR system consists of three main parts:

1. HMR Manager: Runs on the server and watches for file changes in your project.
2. Client Bridge: A WebSocket-based communication channel that connects your browser to the development server.
3. HMR Strategies: Specific logic for each integration that tells the browser how to handle a specific file change (e.g., update a CSS link or reload a specific JS module).

HMR Strategies

Different file types require different update methods. Ecopages handles this automatically:

• CSS Updates: When a .css file changes, Ecopages broadcasts a css-update event. The browser hot-swaps the dynamic <link> tag without a full page reload.
• React Fast Refresh: The React integration uses a custom strategy to apply component updates in-place while keeping state.
• Full Reload: If a core configuration or an include file (like head.ts) changes, Ecopages triggers a full page reload to ensure consistency.

Client-Side Scripting

For HMR to work on your custom scripts, make sure they are:

1. Defined as *.script.ts files.
2. Registered in your component's config.dependencies.scripts.

Customizing HMR

If you are building a Custom Integration, you can define your own HMR strategy by extending the HmrStrategy class.

class MyCustomStrategy extends HmrStrategy {
    matches(filePath: string) {
        return filePath.endsWith('.myext');
    }
 
    async process(filePath: string): Promise<HmrAction> {
        // Return a broadcast action to the client
        return {
            type: 'broadcast',
            events: [{ type: 'update', path: filePath, timestamp: Date.now() }],
        };
    }
}

Troubleshooting HMR

• WebSocket Connection: Ensure no firewall or proxy is blocking the WebSocket connection (defaults to the same port as the server).
• Console Errors: Check the browser console for HMR logs. Ecopages will report if a hot-update fails and a full reload is required.
• Dependency Map: If a change doesn't trigger an update, verify the file is correctly listed in the component dependencies.

Related

• Dev toolbar — navigation timings and dependency graph