HMR / Live Reload Evaluation & Implementation

[aryanjasala]

Overview

The current development workflow requires a full page reload to see CSS or JS changes. This task evaluates whether Vite can be integrated into the theme-elementary build pipeline to provide Hot Module Replacement (HMR) for CSS/JS, or at minimum a fast whole-page reload on PHP/HTML changes.

This is a dual-track task: evaluation first, then implementation if feasible.

---

Objective

Evaluate and implement at least one of the following:

1. CSS/JS HMR via Vite — changes to SCSS/JS files reflect in the browser without a full reload
2. Full-page reload on PHP/HTML changes — Vite watches PHP template files and triggers a browser reload when they change

If successful, document the approach and assess whether it can be extended to features-plugin-skeleton as well

---

Evaluation Criteria

Before committing to an implementation, answer the following questions:

Question	Notes
Can Vite act as a dev server alongside a local WordPress instance?	Might need proxy/middleware config
Does HMR conflict with Gutenberg's editor iframe?	HMR in editor context is complex
What is the impact on the existing webpack.config.js?	-
Can the Vite setup be scoped to non-block assets only?	CSS/JS outside Gutenberg is simpler

---

Implementation Approach (if feasible)

Option A — Vite for Theme Assets (CSS/JS HMR)

• Add vite as a dev dependency
• Configure vite.config.js
• Map theme entry points (assets/src/css/, assets/src/js/) to Vite
• Use Vite's HMR for SCSS and JS modules
• Keep @wordpress/scripts for Gutenberg block assets (blocks run in the editor iframe)

Option B — BrowserSync / Full-Page Reload Fallback

• If Vite HMR proves too complex w/ Gutenberg, implement BrowserSync via the webpack.config.js devServer?
• Watches PHP, TWIG, CSS, JS files and triggers a browser reload
• Lower DX gain than true HMR but zero risk to block editor compatibility

---

Steps

1. Spike: Set up a throwaway branch; attempt Vite integration against a local WordPress instance. Document what works and what breaks.
2. Decision: Based on the spike, choose Option A or Option B (or a hybrid). Document the decision.
3. Implementation: Implement the chosen approach in theme-elementary. Update package.json scripts (npm run dev should start the HMR/reload server).
4. Verify: Confirm that making a SCSS change reflects in the browser within 1–2 seconds without a manual reload.
5. Document: Write setup instructions in docs/hmr.md covering how to start the dev server alongside local WP instance.

---

Acceptance Criteria

• Evaluation spike completed and findings documented (even if implementation is not feasible)
• At minimum one of the following is working: CSS HMR, JS HMR, or full-page reload on file change
• npm run dev starts the enhanced dev server; npm run build still produces production assets correctly
• No regressions in block editor functionality
• Developer setup documented in the repo
• Feasibility for features-plugin-skeleton assessed and documented

---

Notes

• If neither option is feasible within the time budget, close the task with a documented "not feasible at this time" finding. This is an acceptable outcome — do not over-engineer.
• Consider testing against the Gutenberg editor specifically — HMR inside the editor iframe has known compatibility issues.

[aryanjasala]

@00kaku Check these out as well

• https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/
  • Add support for HMR/React Fast Refresh #603