In-Depth Analysis and Practical Guide to Resolving 'Cannot find module 'react/jsx-runtime'' Error in React Component Library Development

Problem Background and Error Manifestation

When developing React component libraries, developers often use Rollup as a build tool and test locally in applications via yarn link. However, when consuming applications (e.g., using Webpack) attempt to import the library, they may encounter errors such as Uncaught Error: Cannot find module 'react/jsx-runtime'. In Webpack CLI, this appears as module-not-found errors pointing to react and react/jsx-runtime. From the Q&A data, the error stems from incorrect bundling order in the consuming application, causing dependency modules to load improperly before the library code.

Root Cause Analysis

The core of this issue lies in the interaction between module resolution and symlinks. According to the best answer (Answer 4), the fundamental cause is a glitch in the symlink created by yarn link. When using the Babel preset @babel/preset-react with runtime: "automatic", JSX is transformed to import from react/jsx-runtime, requiring React as an external dependency. In the Rollup configuration, via external: Object.keys(packageJson.peerDependencies || {}) and the peerDepsExternal() plugin, React is excluded from the bundle, expecting the consuming application to provide it. However, if the symlink is corrupted, Webpack may fail to resolve paths for these external dependencies correctly, leading to missing module errors.

Solution: Re-establishing Symlinks

Based on Answer 4, the most direct solution is to reset the symlink. Follow these steps:

1. In the component library directory, run yarn unlink to remove the existing link.
2. Run yarn link to recreate the symlink.
3. In the consuming application directory, run yarn link component-library (assuming the library package name is component-library) to link to the local library.

This ensures consistent module paths, allowing Webpack to resolve react and react/jsx-runtime properly. For example, in the consuming application's Webpack configuration, ensure resolve.modules includes the node_modules path to find linked dependencies.

Configuration Verification and Best Practices

To prevent such errors, verify the following configuration points:

• Babel Configuration: Ensure @babel/preset-react has runtime set to "automatic", which is suitable for React 17+ and avoids manual React imports. Example configuration: module.exports = { presets: [["@babel/preset-env"], ["@babel/preset-react", { runtime: "automatic" }]] }.
• Rollup Configuration: Use the peerDepsExternal plugin and external option to mark React as an external dependency, preventing duplicate bundling. Refer to the configuration in the Q&A, ensuring output formats (e.g., ESM and CJS) are correct.
• Webpack Configuration: In the consuming application, check externals or ensure React is installed. If using yarn link, Webpack should resolve modules via the symlink.

Other Potential Causes and Supplementary Solutions

Referring to other answers, this error can arise from various factors:

• Dependencies Not Installed (Answer 2, score 3.4): Run npm install or yarn install in the consuming application to ensure React and its runtime are installed. For example, use npm install react@latest react-dom@latest to update to the latest versions.
• Cache Issues (Answer 3, score 2.8): Clear node_modules and lock files before reinstalling, e.g., run rm -rf node_modules package-lock.json && npm i. This can resolve stale or corrupted dependency caches.
• Version Mismatch (Answer 1, score 10.0): Ensure the component library and consuming application use compatible React versions. Set peerDependencies in package.json to "react": "^17.0.0" and avoid bundling React in Rollup to prevent multiple version conflicts.

In-Depth Technical Details: Module Resolution and Toolchain Interaction

This error highlights complex interactions in modern JavaScript toolchains. When Babel transforms JSX to import { jsx } from 'react/jsx-runtime', it relies on the consuming application's module system to provide this module. Rollup externalizes React to keep it out of the library code, but Webpack's resolution may fail due to symlink issues. In the Q&A code snippet, Webpack output shows the webpackMissingModule function triggered, indicating path resolution failures. By re-linking, the symlink is refreshed, restoring normal path resolution. Additionally, ensuring all tools (Babel, Rollup, Webpack) use consistent module resolution strategies is key, e.g., via resolve.extensions including .js and .jsx.

Conclusion and Preventive Measures

The key to resolving the Cannot find module 'react/jsx-runtime' error lies in maintaining symlink integrity and configuration consistency. Developers should regularly verify yarn link status and re-link after changes. Following best practices, such as using Babel automatic runtime, externalizing React dependencies, and keeping toolchains updated, can mitigate such issues. By understanding module resolution mechanisms, developers can debug and optimize component library build processes more effectively, ensuring seamless integration with consuming applications.