single-spa-react is a utility library designed to simplify the integration of React applications and components into a single-spa microfrontend architecture. It provides helper functions that adapt React's rendering and lifecycle methods (bootstrap, mount, unmount) to single-spa's expectations. The current stable version is 6.0.2, with ongoing active development including patch releases and a v7.0.0-beta.0 in progress. Key differentiators include robust support for React 18's `createRoot` API, explicit compatibility options for older React versions, built-in error boundary mechanisms, and a dedicated `<Parcel>` component for managing framework-agnostic micro-frontends within a React application. It focuses on ensuring React applications adhere to single-spa's lifecycle contracts and work seamlessly within a polyglot microfrontend environment.
npm install single-spa-reactVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to wrap a React application for single-spa using `single-spa-react`. It showcases React 18's `ReactDOMClient`, integrates an error boundary, and defines the `domElementGetter` for mounting.
For React 18+, replace `ReactDOM` with `ReactDOMClient` (e.g., `import ReactDOMClient from 'react-dom/client';`) and pass `ReactDOMClient` to `singleSpaReact`. For React 17 or older, you must explicitly set the `renderType` option to `'render'` in your `singleSpaReact` configuration (e.g., `singleSpaReact({ ..., renderType: 'render' })`).Ensure your bundler (e.g., Webpack, Rollup) and TypeScript configuration are up-to-date and using standard module resolution settings. Review your import statements for `single-spa-react` and its subpaths to ensure they align with standard ESM resolution. You might need to adjust `tsconfig.json`'s `moduleResolution` if experiencing import errors.
Provide an `errorBoundary` function or an `errorBoundaryClass` in your `singleSpaReact` options, or ensure your root component itself implements `componentDidCatch`. Setting `suppressComponentDidCatchWarning: true` can silence the warning if you're handling errors externally.
If IE11 support is critical, consider pinning to an older, compatible version of `single-spa-react` and `single-spa` (e.g., `single-spa-react@4.x` and `single-spa@5.x`). Otherwise, plan to migrate users to modern browsers. Always consult the specific `single-spa` and `single-spa-react` changelogs for precise IE11 compatibility statements.
Update your `singleSpaReact` configuration to use `ReactDOMClient` from `react-dom/client` (for React 18+) and remove any explicit `renderType: 'render'` if you are on React 18. If intentionally using React 17 or below, explicitly set `renderType: 'render'`.
Ensure your `domElementGetter` function correctly selects or creates a valid DOM element in the document. Verify the element ID or class name, and ensure the element exists by the time `mount` is called. Remember that `domElementGetter` is not required when creating a single-spa parcel.
Configure your application's bundler (e.g., Webpack `externals`) to treat `react` and `react-dom` as external dependencies. Ensure your `single-spa` root configuration's import map correctly defines the URLs for the shared `react` and `react-dom` libraries.