Skip to content

Configuring and Using HMR (Hot Module Replacement)

Hot Module Replacement (HMR) is a core feature of MageObsidian powered by Vite, enabling real-time updates to your frontend without refreshing the browser. This drastically improves developer productivity by providing instant feedback during development.

⚠️ Important Notice
The configurations described in this section are strictly for development environments.
Do not apply these configurations to production environments, as they could expose your application to unnecessary risks and degrade performance.

Prerequisites: Nginx Configuration

One of the key advantages of Vite is its ability to handle HMR efficiently. However, to fully leverage this feature in your Magento environment, you need to configure your Nginx server to redirect traffic appropriately to the Vite development server.

1. General Vite Proxy Rules

Add the following block to handle HMR-specific traffic and WebSocket connections, which are essential for HMR:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
location ~* ^/(?:@fs|@id|@vite|node_modules|__vite_ping|\.precompiled) {
    proxy_pass http://phpfpm:5173;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

2. Static Asset Proxy Rules

This block ensures that static assets generated by Vite, such as compiled CSS or JavaScript, are correctly proxied:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
location ~* ^/static/frontend/.+/.+/.+/vite_generated/(.*)$ {
    proxy_pass http://phpfpm:5173/$1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Enable WebSocket for HMR
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

3. Placement of Proxy Rules

Ensure these rules are placed below your existing block for static assets, such as:

1
2
3
location ~ ^/static/version\d*/ {
    rewrite ^/static/version\d*/(.*)$ /static/$1 last;
}

1. Starting the Vite Server

The Vite development server must be running for HMR to work. Use the following command to start it for a specific theme:

1
pnpm --prefix vite run dev:theme Vendor/theme

This command initializes Vite, setting up its built-in HMR server to listen on the specified host and port.

Environment Configuration

  • The Vite server's host and port are configurable through environment variables.
  • On the first run, if these variables are not set, Vite will prompt you to configure them.

2. Configuring Magento for HMR

Ensure the following settings are enabled in your Magento environment:

  1. Developer Mode:
    Magento must be running in developer mode. Activate it with: 

    1
    bin/magento deploy:mode:set developer

  2. MageObsidian HMR Configuration:
    The 'mage-obsidian/hmr/enabled' configuration key must be set to true. This setting is enabled by default when MageObsidian is installed.

3. Using HMR in Your Workflow

Once all configurations are in place:

  1. Start the Vite server for your theme: 

    1
    pnpm --prefix vite run dev:theme Vendor/theme

  2. Open your Magento site in the browser. Any changes made to your frontend code will be reflected immediately without requiring a page reload.

Key Advantages of Vite’s HMR

  1. Real-Time Feedback:
    Instantly see changes to your frontend without refreshing the browser, dramatically improving development speed.

  2. WebSocket-Based Updates:
    Vite’s use of WebSocket connections ensures smooth updates, including live CSS injection and JavaScript changes.

  3. Optimized Asset Handling:
    Vite dynamically serves assets, avoiding full recompilation and reducing the development server’s overhead.

  4. Simplified Configuration:
    With Nginx and environment variables properly set, the workflow is seamless.

Example Workflow

  1. Edit a CSS File:
    Modify a file in view/frontend/web/css/module.extend.css. The browser updates instantly.

  2. Edit a Vue Component:
    Update a component in view/frontend/web/components. HMR dynamically replaces the module, and the change appears immediately.

  3. Observe Results:
    No page reloads. No manual interventions. Just instant updates.

Troubleshooting

  1. HMR Not Working:
  2. Ensure the Vite server is running on the correct host and port.

  3. Verify that Nginx is correctly proxying the traffic to the Vite server.

  4. Static Files Not Updating:

  5. Check that the 'mage-obsidian/hmr/enabled' configuration is true.

  6. Make sure Magento is in developer mode.

  7. Environment Variable Issues:

  8. Ensure the environment variables for Vite’s host and port are correctly set.

With HMR configured, you can fully leverage Vite’s modern tooling and experience a faster, smoother frontend development process with MageObsidian.