[Vite] Add support for React HMR

Author: Kocal

CHANGELOG.md

@@ -1,5 +1,14 @@
 # CHANGELOG
 
+## 0.4.0
+
+- Support React Fast Refresh (HMR) with Vite by rendering the `@vitejs/plugin-react` preamble in dev
+
+## 0.3.0
+
+- Fix an entry's CSS being silently dropped under Vite when the entry is emitted as a facade chunk (a top-level `await` in an entry also imported by another entry)
+- Prefer `build.rolldownOptions` over the deprecated `build.rollupOptions` (rolldown-vite / Vite 8)
+
 ## 0.2.0
 
 - Update Unplugin from ^2.3.4 to ^3.3.0

assets/package.json

@@ -89,6 +89,7 @@
     "@rspack/core": "~2.1.3",
     "@tsconfig/node22": "^22.0.5",
     "@types/node": "^26.1.0",
+    "@vitejs/plugin-react": "^6.0.3",
     "jsdom": "^29.1.1",
     "nodemon": "^3.1.14",
     "tsdown": "^0.22.3",

assets/src/index.ts

@@ -127,11 +127,21 @@ export const unpluginFactory: UnpluginFactory<Options | undefined> = (options, _
                     });
                     server.config.server.origin = origin; // keep Vite's internal URL rewriting in sync
 
-                    // Vite serves `@vite/client` under `base` (publicPath), not at the origin root.
+                    // Vite serves `@vite/client` (and `@react-refresh`) under `base` (publicPath), not
+                    // at the origin root.
                     const urlPrefix = resolvePublicPath(resolved.publicPath, origin);
+                    // `@vitejs/plugin-react` (and `-react-swc`) register plugins named `vite:react-*`.
+                    // When present, Symfony must emit the Fast Refresh preamble itself (it can't touch the HTML).
+                    const usesReactPlugin = server.config.plugins.some((plugin) =>
+                        plugin.name?.startsWith('vite:react')
+                    );
                     const ctx: BuildContext = {
                         isProd: false,
-                        devServer: { origin, client: joinUrl(urlPrefix, '@vite/client') },
+                        devServer: {
+                            origin,
+                            client: joinUrl(urlPrefix, '@vite/client'),
+                            reactRefresh: usesReactPlugin ? joinUrl(urlPrefix, '@react-refresh') : null,
+                        },
                         publicPath: resolved.publicPath,
                         urlPrefix,
                         manifestKeyPrefix: resolved.manifestKeyPrefix,

assets/src/types.ts

@@ -185,6 +185,13 @@ export interface DevServer {
      * into the entry (Rsbuild) so nothing extra needs to be rendered.
      */
     client: string | null;
+    /**
+     * URL of Vite's React Fast Refresh runtime (`@react-refresh`) to inject as a preamble before
+     * the entry in dev, set when `@vitejs/plugin-react` is used. `@vitejs/plugin-react` cannot inject
+     * this itself when Symfony renders the HTML (backend integration). `null`/absent otherwise, and
+     * always under Rsbuild, which wires React refresh into the bundle itself.
+     */
+    reactRefresh?: string | null;
 }
 
 export interface AssetEntry {

assets/test/integration/vite-dev.test.ts

@@ -1,6 +1,7 @@
 import { mkdtempSync, readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import react from '@vitejs/plugin-react';
 import { createServer } from 'vite';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import Symfony from '../../src/vite';
@@ -36,9 +37,29 @@ describe('vite serve writes a dev entrypoints.json', () => {
         expect(origin).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/);
         // The HMR client is served under `base` (our publicPath), so its URL carries `/build/`.
         expect(entry.devServer.client).toBe(`${origin}/build/@vite/client`);
+        // No React plugin in this fixture, so no Fast Refresh preamble URL.
+        expect(entry.devServer.reactRefresh ?? null).toBe(null);
 
         expect(Object.keys(entry.entryPoints).sort()).toEqual(['admin', 'app']);
         expect(entry.entryPoints.app.js).toEqual([`${origin}/build/app.js`]);
         expect(entry.entryPoints.app.css).toEqual([]);
     });
+
+    it('exposes the React Fast Refresh URL when a React plugin is present', async () => {
+        const reactOut = mkdtempSync(join(tmpdir(), 'ups-dev-react-'));
+        const reactServer = await createServer({
+            root: fixture,
+            logLevel: 'silent',
+            server: { port: 0, host: '127.0.0.1' },
+            build: { rollupOptions: { input: { app: join(fixture, 'app.js') } } },
+            plugins: [react(), Symfony({ outputPath: reactOut, publicPath: '/build/' })],
+        });
+        await reactServer.listen();
+        try {
+            const entry = JSON.parse(readFileSync(join(reactOut, 'entrypoints.json'), 'utf8'));
+            expect(entry.devServer.reactRefresh).toBe(`${entry.devServer.origin}/build/@react-refresh`);
+        } finally {
+            await reactServer.close();
+        }
+    });
 });

pnpm-lock.yaml

@@ -23,6 +23,7 @@ final class DevServer
     public function __construct(
         public readonly string $origin,
         public readonly ?string $client,
+        public readonly ?string $reactRefresh = null,
     ) {
     }
 
@@ -41,6 +42,11 @@ public static function fromArray(array $data): self
             throw new InvalidEntrypointsException('The dev-server "client" must be a string or null.');
         }
 
-        return new self($origin, $client);
+        $reactRefresh = $data['reactRefresh'] ?? null;
+        if (null !== $reactRefresh && !\is_string($reactRefresh)) {
+            throw new InvalidEntrypointsException('The dev-server "reactRefresh" must be a string or null.');
+        }
+
+        return new self($origin, $client, $reactRefresh);
     }
 }

src/Asset/DevServer.php

@@ -53,6 +53,9 @@ public function renderScriptTags(string $entryName, ?string $packageName = null)
         $devServer = $this->lookup->getDevServer();
         if (!$this->clientInjected && null !== $devServer && null !== $devServer->client) {
             $tags[] = \sprintf('<script type="module" src="%s"></script>', htmlspecialchars($devServer->client, \ENT_QUOTES));
+            if (null !== $devServer->reactRefresh) {
+                $tags[] = $this->renderReactRefreshPreamble($devServer->reactRefresh);
+            }
             $this->clientInjected = true;
         }
 
@@ -113,6 +116,27 @@ public function reset(): void
         $this->clientInjected = false;
     }
 
+    /**
+     * Emits Vite's React Fast Refresh preamble. `@vitejs/plugin-react` normally injects this into the
+     * HTML itself, but cannot when Symfony renders the page (backend integration), so we render it here
+     * before the entry. See https://vite.dev/guide/backend-integration.
+     */
+    private function renderReactRefreshPreamble(string $reactRefreshUrl): string
+    {
+        return \sprintf(
+            <<<'HTML'
+                <script type="module">
+                import RefreshRuntime from "%s";
+                RefreshRuntime.injectIntoGlobalHook(window);
+                window.$RefreshReg$ = () => {};
+                window.$RefreshSig$ = () => (type) => type;
+                window.__vite_plugin_react_preamble_installed__ = true;
+                </script>
+                HTML,
+            htmlspecialchars($reactRefreshUrl, \ENT_QUOTES),
+        );
+    }
+
     private function url(string $reference, ?string $packageName): string
     {
         return $this->packages->getUrl($reference, $packageName ?? $this->defaultPackage);

src/Asset/TagRenderer.php

@@ -187,6 +187,41 @@ public function testDoesNotInjectHmrClientInProd()
         $this->assertStringNotContainsString('@vite/client', $html);
     }
 
+    public function testInjectsReactRefreshPreambleAfterTheClientAndBeforeTheEntryInDev()
+    {
+        $renderer = $this->renderer(
+            js: ['http://127.0.0.1:5173/build/app.js'],
+            devServer: new DevServer(
+                'http://127.0.0.1:5173',
+                'http://127.0.0.1:5173/build/@vite/client',
+                'http://127.0.0.1:5173/build/@react-refresh',
+            ),
+        );
+
+        $html = $renderer->renderScriptTags('app');
+
+        $this->assertStringContainsString('import RefreshRuntime from "http://127.0.0.1:5173/build/@react-refresh"', $html);
+        $this->assertStringContainsString('window.__vite_plugin_react_preamble_installed__ = true', $html);
+
+        // Order matters: the HMR client, then the preamble, then the entry that imports the components.
+        $clientPos = strpos($html, '@vite/client');
+        $preamblePos = strpos($html, '@react-refresh');
+        $entryPos = strpos($html, 'build/app.js');
+        $this->assertLessThan($preamblePos, $clientPos);
+        $this->assertLessThan($entryPos, $preamblePos);
+    }
+
+    public function testDoesNotInjectReactRefreshPreambleWhenNotAReactApp()
+    {
+        $html = $this->renderer(
+            js: ['http://127.0.0.1:5173/build/app.js'],
+            devServer: new DevServer('http://127.0.0.1:5173', 'http://127.0.0.1:5173/build/@vite/client'),
+        )->renderScriptTags('app');
+
+        $this->assertStringNotContainsString('@react-refresh', $html);
+        $this->assertStringNotContainsString('__vite_plugin_react_preamble_installed__', $html);
+    }
+
     public function testRendersModulepreloadLinksWithIntegrityBeforeScripts()
     {
         $html = $this->renderer(