+
+ 
+
+
+ + Thank you for the React applications use garfish. + This is React19. +
+
+ Edit src/App.js and save to reload.
+
-
+
- setIsActive('home')}>
+
+ Home + +
+ - setIsActive('about')}>
+
+ About + +
+
This is Home Page.
;
+const About = This is About Page.
;
+
+const RootComponent = (appInfo: AppInfo) => {
+ const routes = (
+ content
;
+}
+
+export const provider = reactBridge({
+ el: '#root',
+ rootComponent: App,
+});
+```
+
+## Contributing
+
+- [Contributing Guide](https://github.com/modern-js-dev/garfish/blob/main/CONTRIBUTING.md)
+
+## Credit
+
+- [single-spa](https://github.com/single-spa/single-spa) for community raised a hot wave of micro front-end solutions, and we refer to the implementation of the bridge part in [single-spa](https://github.com/single-spa/single-spa) and we think it is a good design, so we fork the code of the bridge implementation part and make some adjustments for the lifecycles in Garfish.
diff --git a/packages/bridge-react-v19/__tests__/reactBridge.spec.ts b/packages/bridge-react-v19/__tests__/reactBridge.spec.ts
new file mode 100644
index 000000000..7ba0cb750
--- /dev/null
+++ b/packages/bridge-react-v19/__tests__/reactBridge.spec.ts
@@ -0,0 +1,313 @@
+// The logic of vue-bridge-test is referenced from single-spa typography
+// Because the Garfish lifecycle does not agree with that of single-spa part logical coupling in the framework
+// https://github.com/single-spa/single-spa-vue/blob/main/src/single-spa-vue.test.js
+
+import { reactBridge } from '../src/reactBridge';
+import '@testing-library/jest-dom';
+import assert from 'assert';
+
+const domElId = '#sub-app-container';
+const cssSelector = '#app';
+
+describe('react-bridge', () => {
+ let React,
+ createRoot,
+ hydrateRoot,
+ props,
+ appInfo,
+ appContainer,
+ container,
+ rootComponent,
+ loadRootComponent,
+ $el,
+ rootInstanceMock,
+ hydrateRootInstanceMock,
+ $createElement,
+ $render,
+ $unmount,
+ errorBoundary;
+
+ beforeEach(() => {
+ React = {
+ createElement: $createElement,
+ version: '19.1.0',
+ };
+
+ createRoot = jest.fn();
+ rootInstanceMock = jest.fn();
+ rootInstanceMock.render = $render;
+ rootInstanceMock.unmount = $unmount;
+ createRoot.mockReturnValue(rootInstanceMock);
+
+ hydrateRoot = jest.fn();
+ hydrateRootInstanceMock = jest.fn();
+ hydrateRootInstanceMock.render = $render;
+ hydrateRootInstanceMock.unmount = $unmount;
+ hydrateRoot.mockReturnValue(hydrateRootInstanceMock);
+
+ container = document.createElement('div');
+ container.setAttribute('id', domElId.replace('#', ''));
+ document.body.appendChild(container);
+
+ appContainer = document.createElement('div');
+ container.setAttribute('id', cssSelector.replace('#', ''));
+ container.appendChild(appContainer);
+
+ $el = '#app2';
+
+ appInfo = {
+ appName: 'test-app',
+ basename: '/demo',
+ dom: container,
+ };
+ props = {
+ store: { counter: 100 },
+ };
+
+ $createElement = jest.fn();
+ $render = jest.fn();
+ $unmount = jest.fn();
+ rootComponent = jest.fn();
+ loadRootComponent = jest.fn();
+ errorBoundary = jest.fn();
+ });
+
+ afterEach(() => {
+ document.querySelectorAll(cssSelector).forEach((node) => {
+ node.remove();
+ });
+ });
+
+ it('throws an error when required parameters are not provided', () => {
+ expect(() => reactBridge(null as any)).toThrow();
+ expect(() => reactBridge({} as any)).toThrow();
+ expect(() => reactBridge({ el: $el } as any)).toThrow();
+ expect(() => reactBridge({ createRoot } as any)).toThrow();
+ expect(() => reactBridge({ loadRootComponent })).not.toThrow();
+ expect(() => reactBridge({ rootComponent })).not.toThrow();
+ expect(() => reactBridge({ el: $el, rootComponent })).not.toThrow();
+ expect(() => reactBridge({ createRoot, rootComponent })).not.toThrow();
+ expect(() => reactBridge({ hydrateRoot, rootComponent })).not.toThrow();
+
+ expect(() =>
+ reactBridge({
+ createRoot,
+ hydrateRoot,
+ el: $el,
+ rootComponent,
+ }),
+ ).not.toThrow();
+
+ expect(() =>
+ reactBridge({
+ createRoot,
+ hydrateRoot,
+ el: $el,
+ loadRootComponent,
+ errorBoundary,
+ }),
+ ).not.toThrow();
+ });
+
+ it('throws an error when react version is lower then react v18', async () => {
+ expect(() =>
+ reactBridge({
+ React: {
+ ...React,
+ version: '15.2.0',
+ },
+ createRoot,
+ rootComponent,
+ }),
+ ).toThrow();
+ });
+
+ it('throws an error when opts.el is provided and opts.el.dom does not exist in the dom during mount', async () => {
+ const provider = reactBridge({
+ React,
+ createRoot,
+ el: '#invalid_app',
+ rootComponent,
+ });
+
+ const lifeCycles = await provider(appInfo, props);
+ expect(() => lifeCycles.render({ ...appInfo, props })).toThrow();
+ });
+
+ it('throws an error when opts.errorBoundary is provided and the type is not function', async () => {
+ expect(() =>
+ reactBridge({
+ React,
+ createRoot,
+ loadRootComponent,
+ errorBoundary: {} as any,
+ }),
+ ).toThrow();
+ });
+
+ it('function called when mounts and unmounts a React component', async () => {
+ const provider = reactBridge({
+ React,
+ createRoot,
+ rootComponent,
+ });
+
+ const lifeCycles = await provider(appInfo, props);
+ expect(createRoot).not.toHaveBeenCalled();
+
+ lifeCycles.render({ ...appInfo, props });
+ expect(createRoot).toHaveBeenCalled();
+ expect(rootInstanceMock.render).toHaveBeenCalled();
+ expect(rootInstanceMock.unmount).not.toHaveBeenCalled();
+
+ lifeCycles.destroy({ ...appInfo, props });
+ expect(rootInstanceMock.unmount).toHaveBeenCalled();
+ });
+
+ // eslint-disable-next-line quotes
+ it("mounts and unmounts a React component with a 'renderType' of 'hydrate'", async () => {
+ const provider = reactBridge({
+ React,
+ createRoot,
+ hydrateRoot,
+ rootComponent,
+ renderType: 'hydrate',
+ });
+
+ const lifeCycles = await provider(appInfo, props);
+ expect(hydrateRoot).not.toHaveBeenCalled();
+
+ lifeCycles.render({ ...appInfo, props });
+ expect(hydrateRoot).toHaveBeenCalled();
+
+ expect(hydrateRootInstanceMock.render).toHaveBeenCalled();
+ expect(hydrateRootInstanceMock.unmount).not.toHaveBeenCalled();
+
+ lifeCycles.destroy({ ...appInfo, props });
+ expect(hydrateRootInstanceMock.unmount).toHaveBeenCalled();
+ });
+
+ it('implements a render function for you if you provide loadRootComponent', async () => {
+ const opts = {
+ React,
+ createRoot,
+ loadRootComponent,
+ };
+
+ opts.loadRootComponent.mockReturnValue(Promise.resolve({}));
+
+ const provider = reactBridge(opts);
+ const lifeCycles = await provider(appInfo, props);
+ lifeCycles.render({ ...appInfo, props });
+ expect(opts.loadRootComponent).toHaveBeenCalled();
+ });
+
+ it('loadRootComponent function will recieve the props provided at mount', async () => {
+ const opts = {
+ React,
+ createRoot,
+ loadRootComponent,
+ };
+ opts.loadRootComponent.mockReturnValue(Promise.resolve({}));
+
+ const provider = reactBridge({
+ React,
+ createRoot,
+ loadRootComponent,
+ });
+
+ const lifeCycles = await provider(appInfo, props);
+ lifeCycles.render({ ...appInfo, props });
+ expect(loadRootComponent.mock.calls[0][0]).toEqual({ ...appInfo, props });
+ expect(loadRootComponent.mock.calls[0][0].appName).toBe('test-app');
+ expect(loadRootComponent.mock.calls[0][0].props.store.counter).toBe(100);
+
+ lifeCycles.destroy({ ...appInfo, props });
+ });
+
+ describe('opts.el', () => {
+ // eslint-disable-next-line quotes
+ it("mounts into the div you provided in the opts.el if you provide an 'el' in opts", async () => {
+ const opts = {
+ React,
+ createRoot,
+ rootComponent,
+ el: '#test_el',
+ };
+ const $testEl = document.createElement('div');
+ $testEl.setAttribute('id', 'test_el');
+ container.appendChild($testEl);
+
+ const provider = reactBridge(opts);
+ const lifeCycles = await provider(appInfo, props);
+
+ lifeCycles.render({ ...appInfo, props });
+ expect(React.createElement).toHaveBeenCalled();
+ expect(document.getElementById('test_el')).toBeInTheDocument();
+ expect(document.getElementById('test_el')).not.toBeNull;
+
+ assert(document.getElementById('test_el'));
+ expect(document.getElementById('test_el')).not.toBeNull;
+ expect(document.getElementById('test_el')?.children).not.toBeNull;
+ expect(document.getElementById('app')).toBeNull;
+ });
+
+ // eslint-disable-next-line quotes
+ it("mounts into the garfish-react-bridge div if you don't provide an 'el' in opts", async () => {
+ const opts = {
+ React,
+ createRoot,
+ rootComponent,
+ };
+
+ const provider = reactBridge(opts);
+ const lifeCycles = await provider(appInfo, props);
+
+ lifeCycles.render({ ...appInfo, props });
+ expect(React.createElement).toHaveBeenCalled();
+
+ assert(document.getElementById('app'));
+ expect(document.getElementById('app')).not.toBeNull;
+ expect(document.getElementById('app')?.children).not.toBeNull;
+ });
+
+ it('register sync provider', async () => {
+ const opts = {
+ React,
+ createRoot,
+ rootComponent,
+ };
+
+ window.__GARFISH__ = true;
+ window.__GARFISH_EXPORTS__ = {
+ provider: null,
+ } as any;
+
+ reactBridge(opts);
+
+ expect(window.__GARFISH_EXPORTS__.provider).toBeTruthy();
+ });
+
+ it('register async provider', async () => {
+ const opts = {
+ React,
+ createRoot,
+ rootComponent,
+ };
+ let asyncProvider: any;
+
+ window.__GARFISH__ = true;
+ window.__GARFISH_EXPORTS__ = {
+ provider: null,
+ registerProvider(fn: any) {
+ asyncProvider = fn;
+ },
+ } as any;
+
+ reactBridge(opts);
+
+ expect(asyncProvider).toBeTruthy();
+ expect(window.__GARFISH_EXPORTS__.provider).toBe(null);
+ });
+ });
+});
diff --git a/packages/bridge-react-v19/package.json b/packages/bridge-react-v19/package.json
new file mode 100644
index 000000000..1b92478ed
--- /dev/null
+++ b/packages/bridge-react-v19/package.json
@@ -0,0 +1,53 @@
+{
+ "name": "@garfish/bridge-react-v19",
+ "version": "0.0.1",
+ "description": "garfish bridge for react v19",
+ "keywords": [
+ "garfish",
+ "micro frontend"
+ ],
+ "files": [
+ "dist"
+ ],
+ "author": "rain120 <1085131904@qq.com>",
+ "homepage": "https://github.com/bytedance/garfish",
+ "license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/bytedance/garfish.git"
+ },
+ "bugs": {
+ "url": "https://github.com/bytedance/garfish/issues"
+ },
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "import": "./dist/esm/index.js",
+ "require": "./dist/index.js"
+ },
+ "./*": "./*"
+ },
+ "main": "dist/index.js",
+ "module": "dist/esm/index.js",
+ "types": "dist/index.d.ts",
+ "scripts": {
+ "build": "rimraf dist && tsup src/index.ts",
+ "dev": "cross-env WATCH=true tsup src/index.ts"
+ },
+ "dependencies": {
+ "@garfish/utils": "workspace:*"
+ },
+ "devDependencies": {
+ "react": "19.1.0",
+ "react-dom": "19.1.0"
+ },
+ "peerDependencies": {
+ "react": "=19",
+ "react-dom": "=19"
+ },
+ "publishConfig": {
+ "registry": "https://registry.npmjs.org",
+ "access": "public"
+ },
+ "gitHead": "da33dd16bb9e99588f34079f8b961d0cf9f059fc"
+}
diff --git a/packages/bridge-react-v19/src/index.ts b/packages/bridge-react-v19/src/index.ts
new file mode 100644
index 000000000..3fc9ad40f
--- /dev/null
+++ b/packages/bridge-react-v19/src/index.ts
@@ -0,0 +1,2 @@
+export { reactBridge } from './reactBridge';
+export type { AppInfo } from './types';
diff --git a/packages/bridge-react-v19/src/reactBridge.ts b/packages/bridge-react-v19/src/reactBridge.ts
new file mode 100644
index 000000000..a06eaa4cb
--- /dev/null
+++ b/packages/bridge-react-v19/src/reactBridge.ts
@@ -0,0 +1,306 @@
+// The logic of reactBridge is referenced from single-spa typography
+// Because the Garfish lifecycle does not agree with that of single-spa part logical coupling in the framework
+// https://github.com/single-spa/single-spa-react/blob/main/src/single-spa-react.js
+
+import * as React from 'react';
+import { createRoot, hydrateRoot, Root } from 'react-dom/client';
+import type { UserOptions, PropsInfo } from './types';
+import { warn } from '@garfish/utils';
+
+type typeReact = typeof React;
+
+type Options = UserOptions<
+ typeof React,
+ typeof createRoot,
+ typeof hydrateRoot,
+ Root,
+ any,
+ React.ReactNode
+>;
+
+const defaultOpts = {
+ // required - one or the other or both
+ rootComponent: undefined,
+ loadRootComponent: undefined,
+
+ // optional opts
+ renderType: undefined,
+ errorBoundary: undefined,
+ el: undefined,
+ canUpdate: true, // by default, allow parcels created with garfish-react-bridge to be updated
+ suppressComponentDidCatchWarning: false,
+ domElements: {},
+ renderResults: {},
+ updateResolves: {},
+};
+
+declare const __GARFISH_EXPORTS__: {
+ provider: Object;
+ registerProvider?: (provider: any) => void;
+};
+
+declare global {
+ interface Window {
+ __GARFISH__: boolean;
+ }
+}
+
+export function reactBridge(this: any, userOpts: Options) {
+ if (typeof userOpts !== 'object') {
+ throw new Error('garfish-react-bridge requires a configuration object');
+ }
+
+ const opts: Options = {
+ ...defaultOpts,
+ ...userOpts,
+ };
+
+ opts.React = opts.React || React;
+ opts.createRoot = opts.createRoot || createRoot;
+ opts.hydrateRoot = opts.hydrateRoot || hydrateRoot;
+
+ if (!opts.rootComponent && !opts.loadRootComponent) {
+ throw new Error(
+ 'garfish-react-bridge must be passed opts.rootComponent or opts.loadRootComponent',
+ );
+ }
+
+ if (opts.errorBoundary && typeof opts.errorBoundary !== 'function') {
+ throw Error(
+ 'The errorBoundary opt for garfish-react-bridge must either be omitted or be a function that returns React elements',
+ );
+ }
+ if (!atLeastReact19(opts.React)) {
+ throw Error(
+ 'Please make sure than the react version is higher than or equal to v19.',
+ );
+ }
+
+ const providerLifeCycle = {
+ render: (appInfo: PropsInfo) => mount.call(this, opts, appInfo),
+ destroy: (appInfo: PropsInfo) => unmount.call(this, opts, appInfo),
+ // update: (appInfo: PropsInfo) =>
+ // opts.canUpdate && update.call(this, opts, appInfo),
+ };
+
+ const provider = async function (this: any, appInfo, props) {
+ await bootstrap.call(this, opts, appInfo, props);
+ return providerLifeCycle;
+ };
+
+ if (
+ window.__GARFISH__ &&
+ typeof __GARFISH_EXPORTS__ === 'object' &&
+ __GARFISH_EXPORTS__
+ ) {
+ if (__GARFISH_EXPORTS__.registerProvider) {
+ __GARFISH_EXPORTS__.registerProvider(provider);
+ } else {
+ __GARFISH_EXPORTS__.provider = provider;
+ }
+ }
+ return provider;
+}
+
+function bootstrap(opts: Options, appInfo, props) {
+ if (opts.loadRootComponent) {
+ // They passed a promise that resolves with the react component. Wait for it to resolve before mounting
+ return opts
+ .loadRootComponent({
+ ...appInfo,
+ props,
+ })
+ .then((resolvedComponent) => {
+ opts.rootComponent = resolvedComponent;
+ });
+ } else {
+ // This is a class or stateless function component
+ return Promise.resolve();
+ }
+}
+
+function mount(opts: Options, appInfo: PropsInfo) {
+ if (
+ !opts.suppressComponentDidCatchWarning &&
+ atLeastReact18(opts.React) &&
+ !opts.errorBoundary
+ ) {
+ if (!opts.rootComponent.prototype) {
+ warn(
+ `garfish-react-bridge: ${appInfo.appName}'s rootComponent does not implement an error boundary. If using a functional component, consider providing an opts.errorBoundary to reactBridge(opts).`,
+ );
+ } else if (!opts.rootComponent.prototype.componentDidCatch) {
+ warn(
+ `garfish-react-bridge: ${appInfo.appName}'s rootComponent should implement componentDidCatch to avoid accidentally unmounting the entire garfish application.`,
+ );
+ }
+ }
+
+ const elementToRender = getElementToRender(opts, appInfo);
+ const domElement = chooseDomElementGetter(opts, appInfo);
+ const renderResult = callCreateRoot({
+ elementToRender,
+ domElement,
+ opts,
+ });
+
+ if (opts.domElements) {
+ opts.domElements[appInfo.appName] = domElement;
+ }
+ if (opts.renderResults) {
+ opts.renderResults[appInfo.appName] = renderResult;
+ }
+}
+
+function unmount(opts: Options, appInfo: PropsInfo) {
+ if (opts.renderResults) {
+ const root = opts.renderResults[appInfo.appName];
+ root.unmount();
+ opts.domElements && delete opts.domElements[appInfo.appName];
+ delete opts.renderResults[appInfo.appName];
+ }
+}
+
+// function update(opts: Options, appInfo: PropsInfo) {
+// return new Promise((resolve) => {
+// if (!opts.updateResolves[appInfo.appName]) {
+// opts.updateResolves[appInfo.appName] = [];
+// }
+
+// opts.updateResolves[appInfo.appName].push(resolve);
+// const elementToRender = getElementToRender(opts, appInfo);
+// const renderRoot = opts.renderResults[appInfo.appName];
+// renderRoot.render(elementToRender);
+// });
+// }
+
+function atLeastReact18(React?: typeReact) {
+ if (
+ React &&
+ typeof React.version === 'string' &&
+ React.version.indexOf('.') >= 0
+ ) {
+ const majorVersionString = React.version.split('.')[0];
+ try {
+ return Number(majorVersionString) >= 18;
+ } catch (err) {
+ return false;
+ }
+ } else {
+ return false;
+ }
+}
+
+function atLeastReact19(React?: typeReact) {
+ if (
+ React &&
+ typeof React.version === 'string' &&
+ React.version.indexOf('.') >= 0
+ ) {
+ const majorVersionString = React.version.split('.')[0];
+ try {
+ return Number(majorVersionString) >= 19;
+ } catch (err) {
+ return false;
+ }
+ } else {
+ return false;
+ }
+}
+
+function callCreateRoot({ opts, elementToRender, domElement }) {
+ const renderType =
+ typeof opts.renderType === 'function' ? opts.renderType() : opts.renderType;
+
+ let root;
+ if (renderType === 'hydrate') {
+ root = opts.hydrateRoot(elementToRender, domElement);
+ root.render(elementToRender);
+ } else {
+ // default to this if 'renderType' is null or doesn't match the other options
+ root = opts.createRoot(domElement);
+ root.render(elementToRender);
+ }
+
+ return root;
+}
+
+function getElementToRender(opts: Options, appInfo: PropsInfo) {
+ const rootComponentElement = opts.React?.createElement(
+ opts.rootComponent as any,
+ appInfo,
+ );
+
+ let elementToRender = rootComponentElement;
+
+ if (opts.errorBoundary) {
+ elementToRender = opts.React?.createElement(
+ createErrorBoundary(opts) as any,
+ appInfo,
+ elementToRender,
+ );
+ }
+ return elementToRender;
+}
+
+function createErrorBoundary(opts: Options) {
+ // Avoiding babel output for class syntax and super()
+ // to avoid bloat
+ function GarfishSubAppReactErrorBoundary(this: any, appInfo: PropsInfo) {
+ // super
+ opts.React?.Component.apply(this, arguments);
+
+ this.state = {
+ caughtError: null,
+ caughtErrorInfo: null,
+ };
+
+ (
+ GarfishSubAppReactErrorBoundary as any
+ ).displayName = `ReactBridgeReactErrorBoundary(${appInfo.appName})`;
+ }
+
+ GarfishSubAppReactErrorBoundary.prototype =
+ opts.React && Object.create(opts.React.Component.prototype);
+
+ GarfishSubAppReactErrorBoundary.prototype.render = function () {
+ if (this.state.caughtError) {
+ const errorBoundary = opts.errorBoundary;
+
+ return errorBoundary && errorBoundary(this.state.caughtError, this.props);
+ } else {
+ return this.props.children;
+ }
+ };
+
+ GarfishSubAppReactErrorBoundary.prototype.componentDidCatch = function (
+ err,
+ info,
+ ) {
+ this.setState({
+ caughtError: err,
+ caughtErrorInfo: info,
+ });
+ };
+
+ return GarfishSubAppReactErrorBoundary;
+}
+
+function chooseDomElementGetter(opts: Options, appInfo: PropsInfo) {
+ const { dom: container } = appInfo;
+ let el;
+ if (typeof opts.el === 'string') {
+ el = container.querySelector(opts.el);
+ } else {
+ el = container;
+ }
+
+ if (!(el instanceof HTMLElement)) {
+ throw Error(
+ `react bridge's dom-element-getter-helpers: el is an invalid dom element for application'${
+ appInfo.appName
+ }'. Expected HTMLElement, received ${typeof el}`,
+ );
+ }
+ return el;
+}
diff --git a/packages/bridge-react-v19/src/types.d.ts b/packages/bridge-react-v19/src/types.d.ts
new file mode 100644
index 000000000..964c1f55e
--- /dev/null
+++ b/packages/bridge-react-v19/src/types.d.ts
@@ -0,0 +1,51 @@
+export type PropsInfo = {
+ appName: string;
+ dom: Element | ShadowRoot | Document;
+ basename: string;
+ appRenderInfo: Record