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 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.ts file 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:

  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. 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.
  • 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.