Add HMR and React Fast Refresh support (#12060)

* Add HMR and React Fast Refresh support

* Run pre-commit hooks

* Fix 'hmrSetModule' module loading

The incoming module needs to include the URL from which it was loaded,
so that it's possible to enforce only loading modules imported from the same
pathname as the current module.

* Add error handling and improvements

- Add error handling to `useRemotePlugin` and simplify `RemoteComponent`
- Improve HMR to use a registry instead of a single global callback.
  This should now handle two legacy plugin entry points being used at
  the same time via RemoteComponent.

* Update docs

* Update CHANGELOG

* Remove use of LanguageContext from RemoteComponent

LanguageContext should not be necessary here, as it's provided in
ThemeContext, which is used in InvenTree's frontend entry.

* Fix incorrect import.meta.hot access

* Update Playwright test to match UI text changes

---------

Co-authored-by: Oliver <oliver.henry.walters@gmail.com>

docs/docs/plugins/creator.md

@@ -214,10 +214,10 @@ The frontend code for your plugin is located in the `frontend/src` directory. Yo
 
 Refer to the `./frontend/src/Panel.tsx` file as a starting point. This is where the custom panel for the part detail page is implemented. You can modify this file to change the content and behavior of the panel.
 
-While the `npm dev` server is running, any changes you make to the frontend code will be automatically reloaded allowing for rapid development and testing of your plugin's frontend features. This avoids the need to rebuild the frontend code every time you make a change.
+While the `npm dev` server is running, any changes to the frontend are reflected in the browser using React Fast Refresh, allowing for rapid development without rebuilding the frontend with every change.
 
 !!! info "Page Reload"
-    Due to the way the InvenTree frontend is structured, you will need to manually refresh the page in your browser to see changes to the frontend code. The development server will automatically reload the frontend code, but the InvenTree server needs to be aware of the changes.
+    All exports in plugin modules that export React components must start with a capital letter. Otherwise, React Fast Refresh will fall back to a full page reload instead of performing a component-level update. Additionally, any render functions referenced from Python must also be capitalized.
 
 ## Build Plugin
 

docs/docs/plugins/walkthrough.md

@@ -119,7 +119,7 @@ function AttachmentCarouselPanel({context}: {context: InvenTreePluginContext;})
 }
 
 // This is the function which is called by InvenTree to render the actual panel component
-export function renderAttachmentCarouselPanel(context: InvenTreePluginContext) {
+export function RenderAttachmentCarouselPanel(context: InvenTreePluginContext) {
     checkPluginVersion(context);
     return <AttachmentCarouselPanel context={context} />;
 }
@@ -300,7 +300,7 @@ Back to the walkthrough, open `core.py` in the `attachment_carousel` folder and
                     'title': 'Attachment Carousel',
                     'description': 'Custom panel description',
                     'icon': 'ti:carousel-horizontal:outline',
-                    'source': self.plugin_static_file('Panel.js:renderAttachmentCarouselPanel'),
+                    'source': self.plugin_static_file('Panel.js:RenderAttachmentCarouselPanel'),
                     'context': {
                         # Provide additional context data to the panel
                         'settings': self.get_settings_dict(),
@@ -385,7 +385,7 @@ panels.append({
     'description': 'Custom panel description',
 -   'icon': 'ti:mood-smile:outline',
 +   'icon': 'ti:carousel-horizontal:outline',
-    'source': self.plugin_static_file('Panel.js:renderAttachmentCarouselPanel'),
+    'source': self.plugin_static_file('Panel.js:RenderAttachmentCarouselPanel'),
     'context': {
         # Provide additional context data to the panel
         'settings': self.get_settings_dict(),
@@ -519,7 +519,7 @@ panels.append({
     'title': 'Attachment Carousel',
     'description': 'Custom panel description',
     'icon': 'ti:carousel-horizontal:outline',
-    'source': self.plugin_static_file('Panel.js:renderAttachmentCarouselPanel'),
+    'source': self.plugin_static_file('Panel.js:RenderAttachmentCarouselPanel'),
     'context': {
         # Provide additional context data to the panel
         'settings': self.get_settings_dict(),

src/frontend/CHANGELOG.md

@@ -27,6 +27,10 @@ Exposes sub-components related to DetailDrawer rendering:
 - `DetailDrawerComponent`
 - `useLocalLibState`
 
+#### Plugin System
+
+Enable React Fast Refresh support for plugin frontend development. Plugin modules exporting React components must start with a capital letter; otherwise, a full page reload occurs instead of a component-level update.
+
 ### 0.11.3 - April 2026
 
 Exposes additional type definitions related to rendering drawers from tables:

src/frontend/src/components/plugins/RemoteComponent.tsx

@@ -1,17 +1,12 @@
 import { t } from '@lingui/core/macro';
-import { Alert, MantineProvider, Stack, Text } from '@mantine/core';
+import { Alert, Stack, Text } from '@mantine/core';
-import { IconExclamationCircle } from '@tabler/icons-react';
+import { useRef } from 'react';
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
 import { Boundary } from '@lib/components/Boundary';
 import { identifierString } from '@lib/functions/Conversion';
 import type { InvenTreePluginContext } from '@lib/types/Plugins';
-import { type Root, createRoot } from 'react-dom/client';
+import { IconExclamationCircle } from '@tabler/icons-react';
-import { api, queryClient } from '../../App';
+import { useRemotePlugin } from '../../hooks/UseRemotePlugin';
-import { ApiProvider } from '../../contexts/ApiContext';
-import { LanguageContext } from '../../contexts/LanguageContext';
-import { useLocalState } from '../../states/LocalState';
-import { findExternalPluginFunction } from './PluginSource';
 
 /**
  * A remote component which can be used to display plugin content.
@@ -31,125 +26,39 @@ export default function RemoteComponent({
   defaultFunctionName: string;
   context: InvenTreePluginContext;
 }>) {
-  const componentRef = useRef<HTMLDivElement | null>(null);
+  const containerRef = useRef<HTMLDivElement | null>(null);
-  const rootElement = useRef<Root | null>(null);
 
-  useEffect(() => {
+  const { componentFn, errorMsg, exportName, pluginContext, remountKey } =
-    if (componentRef.current && rootElement.current === null) {
+    useRemotePlugin({
-      rootElement.current = createRoot(componentRef.current);
+      context,
-    }
+      source,
-  }, [rootElement]);
+      defaultFunctionName,
+      containerRef
+    });
 
-  const [renderingError, setRenderingError] = useState<string | undefined>(
+  const content = componentFn ? (
-    undefined
+    componentFn(pluginContext)
+  ) : (
+    <div ref={containerRef} />
   );
 
-  const func: string = useMemo(() => {
-    // Attempt to extract the function name from the source
-    const { getHost } = useLocalState.getState();
-    const url = new URL(source, getHost());
-
-    if (url.pathname.includes(':')) {
-      const parts = url.pathname.split(':');
-      return parts[1] || defaultFunctionName; // Use the second part as the function name, or fallback to default
-    } else {
-      return defaultFunctionName;
-    }
-  }, [source, defaultFunctionName]);
-
-  const reloadPluginContent = useCallback(() => {
-    if (!rootElement.current) {
-      return;
-    }
-
-    const ctx: InvenTreePluginContext = {
-      ...context,
-      reloadContent: reloadPluginContent
-    };
-
-    if (source && defaultFunctionName) {
-      findExternalPluginFunction(source, func)
-        .then((func) => {
-          if (!!func) {
-            try {
-              if (func.length > 1) {
-                // Support "legacy" plugin functions which call createRoot() internally
-                // Ref: https://github.com/inventree/InvenTree/pull/9439/
-                func(componentRef.current, ctx);
-              } else {
-                // Render the plugin component into the target element
-                // Note that we have to provide the right context(s) to the component
-                // This approach ensures that the component is rendered in the correct context tree
-                rootElement.current?.render(
-                  <ApiProvider client={queryClient} api={api}>
-                    <MantineProvider
-                      theme={ctx.theme}
-                      defaultColorScheme={ctx.colorScheme}
-                    >
-                      <LanguageContext>{func(ctx)}</LanguageContext>
-                    </MantineProvider>
-                  </ApiProvider>
-                );
-              }
-
-              setRenderingError('');
-            } catch (error) {
-              setRenderingError(`${error}`);
-              console.error(error);
-            }
-          } else {
-            setRenderingError(`${source} / ${func}`);
-          }
-        })
-        .catch((_error) => {
-          console.error(
-            `ERR: Failed to load remote plugin function: ${source} /${func}`
-          );
-        });
-    } else {
-      setRenderingError(
-        `${t`Invalid source or function name`} - ${source} /${func}`
-      );
-    }
-  }, [
-    componentRef.current,
-    rootElement.current,
-    source,
-    defaultFunctionName,
-    context
-  ]);
-
-  // Reload the plugin content dynamically
-  useEffect(() => {
-    reloadPluginContent();
-  }, [
-    func,
-    rootElement.current,
-    context.id,
-    context.model,
-    context.instance,
-    context.user,
-    context.colorScheme,
-    context.locale,
-    context.context
-  ]);
-
   return (
-    <Boundary label={identifierString(`RemoteComponent-${func}`)}>
+    <Stack>
-      <Stack gap='xs'>
+      {errorMsg && (
-        {renderingError && (
+        <Alert
-          <Alert
+          color='red'
-            color='red'
+          title={t`Error Loading Plugin Content`}
-            title={t`Error Loading Content`}
+          icon={<IconExclamationCircle />}
-            icon={<IconExclamationCircle />}
+        >
-          >
+          <Text>{errorMsg}</Text>
-            <Text>
+        </Alert>
-              {t`Error occurred while loading plugin content`}: {renderingError}
+      )}
-            </Text>
+      <Boundary
-          </Alert>
+        key={remountKey}
-        )}
+        label={identifierString(`RemoteComponent-${exportName}`)}
-        {componentRef && <div ref={componentRef as any} />}
+      >
-      </Stack>
+        {content}
-    </Boundary>
+      </Boundary>
+    </Stack>
   );
 }

src/frontend/src/hooks/UseRemotePlugin.tsx

@@ -0,0 +1,157 @@
+import type { InvenTreePluginContext } from '@lib/types/Plugins';
+import { t } from '@lingui/core/macro';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import type { ReactElement } from 'react';
+import { useLocalState } from '../states/LocalState';
+
+type LegacyPluginEntryFn = (
+  container: HTMLDivElement,
+  ctx: InvenTreePluginContext
+) => void;
+
+type PluginEntryFn = (ctx: InvenTreePluginContext) => ReactElement;
+
+type UseRemotePluginOptions = {
+  context: InvenTreePluginContext;
+  source: string;
+  defaultFunctionName: string;
+  containerRef: React.RefObject<HTMLDivElement | null>;
+};
+
+type UsePluginSourceOptions = {
+  source: string;
+  defaultFunctionName?: string;
+};
+
+type UseRemotePluginReturn = {
+  componentFn: PluginEntryFn | null;
+  errorMsg: string | null;
+  exportName: string;
+  pluginContext: InvenTreePluginContext;
+  remountKey: number;
+};
+
+function usePluginSource({
+  source,
+  defaultFunctionName
+}: UsePluginSourceOptions) {
+  const { getHost } = useLocalState.getState();
+
+  const { moduleUrl, exportName } = useMemo(() => {
+    const url = new URL(source, getHost());
+    const parts = url.pathname.split(':');
+
+    return {
+      exportName: parts[1] || defaultFunctionName || 'default',
+      moduleUrl: url.origin + parts[0]
+    };
+  }, [source, defaultFunctionName, getHost]);
+
+  return { moduleUrl, exportName };
+}
+
+function getHmrCallbacks(url: string) {
+  const w = window as any;
+  w.__plugin_hmr_callbacks ??= {};
+  w.__plugin_hmr_callbacks[url] ??= new Set<Function>();
+  return w.__plugin_hmr_callbacks[url];
+}
+
+const hasHmr = import.meta.hot !== undefined;
+
+export function useRemotePlugin({
+  context,
+  source,
+  defaultFunctionName,
+  containerRef
+}: UseRemotePluginOptions): UseRemotePluginReturn {
+  const { moduleUrl, exportName } = usePluginSource({
+    source,
+    defaultFunctionName
+  });
+
+  const [remoteModule, setRemoteModule] = useState<Record<
+    string,
+    unknown
+  > | null>(null);
+  const [reloadVersion, setReloadVersion] = useState(0);
+  const [errorMsg, setErrorMsg] = useState<string | null>(null);
+
+  const reloadContent = useCallback(() => setReloadVersion((v) => v + 1), []);
+
+  const hmrSetModule = useCallback(
+    (newRemoteModule: Record<string, unknown> | null) => {
+      if (!hasHmr) return;
+      setRemoteModule(newRemoteModule);
+    },
+    []
+  );
+
+  useEffect(() => {
+    let cancelled = false;
+
+    setErrorMsg(null);
+
+    const loadModule = async () => {
+      try {
+        const mod = await import(/* @vite-ignore */ moduleUrl);
+        if (!cancelled) setRemoteModule(mod);
+      } catch (err) {
+        if (!cancelled) {
+          console.error(`ERR: Failed to load module: ${moduleUrl}:\n${err}`);
+          setErrorMsg(t`Failed to load module: ${moduleUrl}`);
+        }
+      }
+    };
+
+    loadModule();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [moduleUrl]);
+
+  const [legacyRenderFn, componentFn, error] = useMemo(() => {
+    if (!remoteModule) return [null, null, null];
+
+    let err: string | null = null;
+    const func = remoteModule[exportName];
+
+    if (typeof func === 'function') {
+      if (func.length === 2) {
+        return [func as LegacyPluginEntryFn, null, null];
+      } else if (func.length === 1) {
+        return [null, func as PluginEntryFn, null];
+      } else {
+        err = `Entrypoint ${exportName} in ${moduleUrl} must accept 1-2 arguments`;
+      }
+    } else if (func !== undefined) {
+      err = t`Export ${exportName} in ${moduleUrl} is not a function (found type ${typeof func}).`;
+    } else {
+      err = t`Plugin entrypoint ${exportName} does not exist in ${moduleUrl}.`;
+    }
+
+    return [null, null, err];
+  }, [remoteModule, exportName]);
+
+  useEffect(() => {
+    if (legacyRenderFn && containerRef.current) {
+      containerRef.current.innerHTML = '';
+      legacyRenderFn(containerRef.current, context);
+
+      if (hasHmr) getHmrCallbacks(moduleUrl)?.add(hmrSetModule);
+    }
+
+    return () => {
+      if (hasHmr) getHmrCallbacks(moduleUrl)?.delete(hmrSetModule);
+    };
+  }, [moduleUrl, legacyRenderFn, context, hmrSetModule]);
+
+  return {
+    componentFn: componentFn,
+    errorMsg: error ?? errorMsg,
+    exportName: exportName,
+    pluginContext: { ...context, reloadContent: reloadContent },
+    remountKey: reloadVersion
+  };
+}

src/frontend/tests/pui_plugins.spec.ts

@@ -174,7 +174,7 @@ test('Plugins - Panels', async ({ browser }) => {
 
   // Check out each of the plugin panels
   await loadTab(page, 'Broken Panel');
-  await page.getByText('Error occurred while loading plugin content').waitFor();
+  await page.getByText('Error Loading Plugin Content').waitFor();
   await loadTab(page, 'Dynamic Panel');
   await page.getByText('Instance ID: 69');
   await page