React Mismatch/Setup errors do not inform the user of anything

[Coruscate5]

Target SharePoint environment

SharePoint Online

What SharePoint development model, framework, SDK or API is this about?

💥 SharePoint Framework

Developer environment

Windows

What browser(s) / client(s) have you tested

• 💥 Internet Explorer
• 💥 Microsoft Edge
• 💥 Google Chrome
• 💥 FireFox
• 💥 Safari
• mobile (iOS/iPadOS)
• mobile (Android)
• not applicable
• other (enter in the "Additional environment details" area below)

Additional environment details

• browser version (latest)
• SPFx version (1.19.0)
• Node.js version (18)

Describe the bug / error

React version issues do not create errors in Gulp serve, even with strict linting, and the browser does not alert the user to any issues. The user is simply given the following (generic error):

Uncaught (in promise) Error: Failed to create application customizer 'ClientSideExtension.ApplicationCustomizer.970fe979-1d72-4e98-b295-3a9bf1f36291'. Error information is 'Extension failed to load for componentId "970fe979-1d72-4e98-b295-3a9bf1f36291".'.

The issue was reported here but did not resolve in a way that helps developers in this framework: #7050

Steps to reproduce

Steps to reproduce:

1. Create a new version of a solution using yeoman generator.
2. Run npm i react react-dom
3. Import react in generated .ts file: import * as React from 'react';
4. Create basic react element in generated .ts file for app customizer after alert. Use the following line: const a = React.createElement("div", null, null);
5. Run gulp serve

Expected behavior

Gulp or SP dependency should inform the user that this React version is incompatible with the current plugin, per https://learn.microsoft.com/en-us/sharepoint/dev/spfx/compatibility . No error message or build issue is encountered in the build process, and the browser simply reports that the Customizer couldn't load.

[Ashlesha-MSFT]

Hello @Coruscate5,
Thank you for bringing this issue to our attention. We will look into it and get back to you shortly.

[Ashlesha-MSFT]

@Coruscate5,
The issue you’re facing appears to be due to a React version mismatch between the manually installed react and react-dom packages and the versions supported by your current SPFx version. This mismatch leads to a silent runtime failure, where the browser shows a generic loading error without providing any meaningful information during the build process.

We do understand that this behaviour can be confusing. Ideally, SPFx should provide clearer validation of React version compatibility at build or runtime. As a best practice, we suggest strictly following the SPFx compatibility matrix while selecting the React version to ensure smooth functionality.

[Coruscate5]

Yep, we figured this out eventually - the purpose of this issue is to create better user messages for the mismatch, or, just prevent the build entirely if the React version is incorrect

[Ashlesha-MSFT]

@Coruscate5,
Glad to hear you were able to figure it out! Since it sounds like the issue has been resolved on your end, could you please confirm if we can go ahead and close this issue?

Thanks!

[jvanpiccs]

Fix for anyone looking the answer for spfx 1.21.1 (or match with the correct version according to SPFx compatibility matrix and your version.)

clean node_modules and package-lock.json
rm -rf node_modules package-lock.json

install the specfic version of react
npm i react@17.0.1 react-dom@17.0.1 --save-exact
add --save-exact because npm adds ^17.0.1 and that gives error too

one more step just to be sure you start clean all over
gulp clean

I think this NEEDS to be documentes as a note in the setup dev, or aside of the extensions explanation.
Its been a known issue for while now. I keep forgetting this, and remembering take me always an hour of looking for the solution.

[Coruscate5]

Yes, this issue was created with the intention of having updated documentation (in both online & ideally the CLI) plus corrected docs on which exact versions are needed - AFAICT that hasn't been done yet, and it's not something I can do myself (or I would)