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:
- HMR Manager: Runs on the server and watches for file changes in your project.
- Client Bridge: A WebSocket-based communication channel that connects your browser to the development server.
- 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
.cssfile changes, Ecopages broadcasts acss-updateevent with the href of that stylesheet. The browser refreshes that one<link>without a full page reload. A component that imports the stylesheet as text, such as a Lit component, gets a module update with the new CSS. - React Fast Refresh: The React integration uses a custom strategy to apply component updates in-place while keeping state.
- Server-Rendered Templates: When an include file (like
head.ts), an explicit view, or a page, layout or component template (Kita, Lit, MDX, HTML Page) that the browser does not load as a module changes, Ecopages refreshes the page in place when the navigation runtime is available, and reloads it otherwise. With@ecopages/browser-router, the refresh keeps every element whose server-rendered markup did not change: custom elements keep their state and stay connected, and classes or attributes added at runtime stay. - Full Reload: If a core configuration file changes, Ecopages triggers a full page reload to ensure consistency.
- Build Errors: When a client-side module that the dev server sends to the browser, such as a
*.script.tsfile or a hydrated component, fails to build, for example after a syntax error, the error appears at the bottom of the page and in the browser console. A page opened while the module still fails shows it too. The next update removes it; press Escape or Dismiss to close it sooner.
Client-Side Scripting
For HMR to work on your custom scripts, make sure they are:
- Defined as
*.script.tsfiles. - 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. Build errors are also shown in the page.
- 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
Under the hood
How a save travels from the watcher to the browser is described in Dev server and Watcher and invalidation.