vitejs · hi-ogawa · Jul 18, 2025 · Jun 25, 2025 · Jul 1, 2025 · Jul 1, 2025
diff --git a/packages/common/refresh-runtime.js b/packages/common/refresh-runtime.js
@@ -545,6 +545,21 @@ function isLikelyComponentType(type) {
   }
 }
 
+function isCompoundComponent(type) {
+  if (!isPlainObject(type)) return false
+  for (const key in type) {
+    if (!isLikelyComponentType(type[key])) return false
+  }
+  return true
+}
+
+function isPlainObject(obj) {
+  return (
+    Object.prototype.toString.call(obj) === '[object Object]' &&
+    (obj.constructor === Object || obj.constructor === undefined)
+  )
+}
+
 /**
  * Plugin utils
  */
@@ -565,6 +580,13 @@ export function registerExportsForReactRefresh(filename, moduleExports) {
       // The register function has an identity check to not register twice the same component,
       // so this is safe to not used the same key here.
       register(exportValue, filename + ' export ' + key)
+    } else if (isCompoundComponent(exportValue)) {
+      for (const subKey in exportValue) {
+        register(
+          exportValue[subKey],
+          filename + ' export ' + key + '$' + subKey,
+        )
+      }
     }
   }
 }
@@ -618,6 +640,7 @@ export function validateRefreshBoundaryAndEnqueueUpdate(
     (key, value) => {
       hasExports = true
       if (isLikelyComponentType(value)) return true
+      if (isCompoundComponent(value)) return true
       return prevExports[key] === nextExports[key]
     },
   )

diff --git a/packages/plugin-react-oxc/CHANGELOG.md b/packages/plugin-react-oxc/CHANGELOG.md
@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+### Add support for compound components ([#518](https://github.com/vitejs/vite-plugin-react/pull/518))
+
+HMR now works for compound components like this:
+
+```tsx
+const Root = () => <div>Accordion Root</div>
+const Item = () => <div>Accordion Item</div>
+
+export const Accordion = { Root, Item }
+```
+
 ### Return `Plugin[]` instead of `PluginOption[]`
 
 ## 0.2.3 (2025-06-16)

diff --git a/packages/plugin-react-swc/CHANGELOG.md b/packages/plugin-react-swc/CHANGELOG.md
@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+### Add support for compound components ([#518](https://github.com/vitejs/vite-plugin-react/pull/518))
+
+HMR now works for compound components like this:
+
+```tsx
+const Root = () => <div>Accordion Root</div>
+const Item = () => <div>Accordion Item</div>
+
+export const Accordion = { Root, Item }
+```
+
 ### Return `Plugin[]` instead of `PluginOption[]`
 
 ## 3.10.2 (2025-06-10)

diff --git a/packages/plugin-react/CHANGELOG.md b/packages/plugin-react/CHANGELOG.md
@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+### Add support for compound components ([#518](https://github.com/vitejs/vite-plugin-react/pull/518))
+
+HMR now works for compound components like this:
+
+```tsx
+const Root = () => <div>Accordion Root</div>
+const Item = () => <div>Accordion Item</div>
+
+export const Accordion = { Root, Item }
+```
+
 ### Return `Plugin[]` instead of `PluginOption[]`
 
 The return type has changed from `react(): PluginOption[]` to more specialized type `react(): Plugin[]`. This allows for type-safe manipulation of plugins, for example:

diff --git a/playground/compound-components/__tests__/compound-components.spec.ts b/playground/compound-components/__tests__/compound-components.spec.ts
@@ -0,0 +1,27 @@
+import { expect, test } from 'vitest'
+import { editFile, isServe, page, untilBrowserLogAfter } from '~utils'
+
+test('should render compound components', async () => {
+  expect(await page.textContent('h1')).toMatch('Compound Components HMR Test')
+  expect(await page.textContent('h3')).toMatch('Accordion Root')
+})
+
+if (isServe) {
+  test('compound components should use HMR instead of full reload', async () => {
+    const logs = await untilBrowserLogAfter(
+      () =>
+        editFile('src/Accordion.tsx', (code) =>
+          code.replace('Accordion Root', 'Accordion Root Updated'),
+        ),
+      /\[vite\]/,
+    )
+
+    expect(logs).toContain('[vite] hot updated: /src/Accordion.tsx')
+    expect(logs).not.toContain('[vite] invalidate')
+
+    // revert changes
+    editFile('src/Accordion.tsx', (code) =>
+      code.replace('Accordion Root Updated', 'Accordion Root'),
+    )
+  })
+}
diff --git a/playground/compound-components/index.html b/playground/compound-components/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Compound Components Test</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
diff --git a/playground/compound-components/package.json b/playground/compound-components/package.json
@@ -0,0 +1,21 @@
+{
+  "name": "@vitejs/test-compound-components",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "serve": "vite preview"
+  },
+  "dependencies": {
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "@vitejs/plugin-react": "workspace:*",
+    "typescript": "^5.8.3"
+  }
+}
diff --git a/playground/compound-components/public/vite.svg b/playground/compound-components/public/vite.svg
diff --git a/playground/compound-components/src/Accordion.tsx b/playground/compound-components/src/Accordion.tsx
@@ -0,0 +1,36 @@
+import React from 'react'
+
+const Root: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  return (
+    <div
+      style={{
+        border: '1px solid #ccc',
+        borderRadius: '4px',
+        margin: '16px 0',
+      }}
+    >
+      <h3 style={{ padding: '12px', margin: '0', backgroundColor: '#f5f5f5' }}>
+        Accordion Root
+      </h3>
+      <div style={{ padding: '12px' }}>{children}</div>
+    </div>
+  )
+}
+
+const Item: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  return (
+    <div
+      style={{
+        padding: '8px 12px',
+        border: '1px solid #e0e0e0',
+        margin: '4px 0',
+        borderRadius: '2px',
+        backgroundColor: '#fafafa',
+      }}
+    >
+      {children}
+    </div>
+  )
+}
+
+export const Accordion = { Root, Item }
diff --git a/playground/compound-components/src/main.tsx b/playground/compound-components/src/main.tsx
@@ -0,0 +1,21 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { Accordion } from './Accordion'
+
+const root = ReactDOM.createRoot(document.getElementById('root')!)
+
+root.render(
+  <React.StrictMode>
+    <div>
+      <h1>Compound Components HMR Test</h1>
+      <p>
+        This demonstrates the compound component pattern that causes full reload
+        instead of HMR.
+      </p>
+      <Accordion.Root>
+        <Accordion.Item>First Item</Accordion.Item>
+        <Accordion.Item>Second Item</Accordion.Item>
+      </Accordion.Root>
+    </div>
+  </React.StrictMode>,
+)
diff --git a/playground/compound-components/tsconfig.json b/playground/compound-components/tsconfig.json
@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "types": ["vite/client"],
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src", "vite.config.ts"]
+}
diff --git a/playground/compound-components/vite.config.ts b/playground/compound-components/vite.config.ts
@@ -0,0 +1,14 @@
+import react from '@vitejs/plugin-react'
+import type { UserConfig } from 'vite'
+
+const config: UserConfig = {
+  server: { port: 8907 /* Should be unique */ },
+  mode: 'development',
+  plugins: [react()],
+  build: {
+    // to make tests faster
+    minify: false,
+  },
+}
+
+export default config
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml