SPFx Devs: Beware of the SharePoint SE 23H2 Feature Update

I have a scary story for you, even though Halloween is still a few weeks away. This story is for those who are involved with the SharePoint Server Subscription Edition and the most recent update: SharePoint Server Subscription Edition (SP SE) 23H2.

This update, released in September 2023, is the second update for SP SE this year. Within this update, there were mentions of updates to the SharePoint Framework (SPFx) and adding support for newer versions of React & the Office UI Fabric React components.

However, it was not clear what exactly they meant by these updates. From what I’ve gathered, the updates actually downgraded the version of the SPFx included in 23H2 compared to the previous update released earlier this year, 23H1!

The other thing in the release notes is they said they added support for React v16 and Office UI Fabric React v7, but to accomplish this, you had to do some scary stuff to your project… like create a Frankenstein SPFx project.

Before I explain the impacts on our projects, let’s first understand what this update does.

Updated support for React & Office UI Fabric React versions

Experienced SPFx developers will be interested to hear that React and Office UI Fabric React have been updated to newer versions than what the SP SE GA & 23H1 update included support for.

The SP SE shipped with SPFx v1.4.1 (just like SharePoint Server 2019). Earlier this year, with the SP SE 23H1 update, Microsoft surprised us by upgrading the SPFx. This broke from the previous position of not upgrading the SPFx in on-premises SharePoint Server deployments. The SP SE 23H1 update upgraded the version of the SPFx from v1.4.1 to v1.5.1.

When I saw this update, I was hoping it was the start of a big jump for SPFx with the 2nd-half update later this year. But, as I mentioned previously, it didn’t go in the direction that we expected.

In the article announcing the SP SE 23H2 feature update, Microsoft mentioned:

However, they didn’t specify which version of SPFx this feature update included. In the same paragraph, though, they said this update:

So those two statements give us some clues as to the version of SPFx:

• SPFx v1.7.0 (released January 2019) added support for React v16 (from React v15)
• SPFx v1.12.1 (released April 2021) added support for Office UI Fabric React v7 (from OUIFR v6)

So, initially, it appeared that they updated the SPFx to v1.12.1. This update would have included the platform dependency updates for React and OfficeUI Fabric React. It made sense since it was the last version of the SPFx generator that supported creating on-prem projects when starting a new project. This version was SPFx v1.12.1.

What version SPFx is in SharePoint Server Subscription Edition?

But because they didn’t explicitly say which version of SPFx was in 23H2, I wasn’t sure of it, so I asked some people at Microsoft about this. Eventually I noticed a new pull request #9215 in the repo for the SharePoint developer docs repo that confirmed it: the version of the SPFx included in 23H2 was v1.5.0.

I’ll come back to that pull request revisit that in a minute because there’s a LOT more to it that raises more questions than answers, but let’s stay on the topic of the SPFx version.

You read that right… that’s a downgrade of the SPFx from the 23H1 update (SPFx v1.5.1) to the 23H2 update (SPFx v1.5.0).

What does this mean? If anyone upgraded their projects or created new projects for SP SE targeting SPFx v1.5.1, they’ll likely have problems because once you install the SP SE 23H2 update, SPFx v1.5.1 is no longer on the server. So when your SPFx v1.5.1 project tells the SPFx runtime to it needs specific versions of the SPFx runtime to load, wouldn’t it fail because it’s requesting things that are no longer there? 😳

But that’s just the tip of the iceberg. Wait to hear the rest of this story that’s really scary about this. 😱

How do use React v16 & Office UI Fabric React v7 in SPFx v1.5.0 projects?

When I delved deeper and reviewed the pull request submitted to update the documentation on how to upgrade projects to the newer versions of React and Office UI Fabric React, I was astonished by what I read.

Manually edit package.json (when you should use npm install)

The instructions advised manually modifying your package.json file to gain support for these newer dependencies by setting the versions of React and React DOM packages to v16.13.1, and adding the @microsoft/office-ui-fabric-react-bundle package v1.15.

It was surprising enough that they recommended making these changes manually in package.json, which is generally not recommended. If you’ve run npm install on the project previously, there will already be a package-lock.json file in the project that captures a snapshot of the versions installed for all dependencies. Simply editing the package.json file won’t update the versions in the lock file.

This assumes that you are starting a new project rather than using an upgraded one. The correct approach is to use the npm install command, which not only updates the package.json file but also updates the package-lock.json file and installs all the necessary dependencies.

Instead of making changes to the package file and then running npm install, you should use npm install to ensure that the changes are applied consistently throughout the project.

But wait… that’s not even the scary part.

Mixing SharePoint Framework versions

The next set of instructions tell you to update the SPFx build dependency packages from v1.4.1 to v1.9.1. However, this assumes that your project has never been upgraded or created using the 23H1 update with SPFx v1.5.1. It assumes that you are starting directly from the default version included in the SP SE.

And then, the PR tells you to update all the other SPFx packages to v1.5.0.

Nope, that’s no typo. Those instructions tell you to mix versions of SPFx in the same project.

Effectively, what this means is that you will be using one version of the SPFx to build and compile your project and run the local web server (v1.9.1), while using a different version (v1.5.0) in your actual project as a dependency. When the SPFx runtime loads the component on the page, it will load a different version than the one used to build the project.

Will that even work? I mean, I guess they tested it, but…

This has never been a supported scenario in the seven years of the SPFx. We have never seen them recommend using two different versions of the SPFx.

Conclusion? More questions than answers…

What does all of this mean? I think it’s clear where things stand, but it’s a little confusing where we go from here.

Microsoft is aware of this and I think they’re currently investigating the situation and determining what recommendations they should provide. This is a bit concerning because the SP SE 23H2 update has already been released, and there may be customers who have already installed it.

This leads me to a couple questions:

1. What happens to anyone who has already upgraded or deployed a project using SharePoint Framework 1.5.1 to SharePoint Server SE with the 23H1 update already installed?

   Is there a downgrade option once they realize this (from 23H2 to 23H1 or GA?)?

   Won’t everything just break?

2. Can you really have two versions of the SPFx in a project? Because, after 7 years, this is the first time we’ve heard this from Microsoft. We have two versions of the SharePoint Framework: one for the toolchain and one for the runtime. We are dealing with different versions of React and the Office UI Fabric/Fluent UI with a version that was never supported in this way.

So I’m not sure where this leaves us because all of these questions remain unanswered.

One thing is certain - that this is mess.

Guidance & Recommendations

This 23H2 update for SP SE is keeping the spirit of Halloween alive - it should scare the heck out of you.

Here’s my my guidance:

1. If you have any custom SPFx v1.5.1 solutions that you’ve already deployed to your SP SE 23H1 environment, don’t install the 23H2 update until Microsoft clears up their docs and issues a statement about this.
2. If you’re going to install the SharePoint server SE 23H2 update right now, do not deploy or upgrade any of your SPFx solutions beyond version SPFx 1.4.1.
   • SPFx v1.5.1 does not exist on the server with 23H2.
   • If you want to use newer versions of React & Office UI Fabric React on SP SE, the only way is to create a Frankenstein SPFx project that uses different versions of React and Office UI Fabric with SPFx v1.5.0.
3. Ignore the guidance that the unmerged PR shows on how to create this bastardized SPFx solution to support different versions of React & Office UI Fabric React.
4. If you do not have any custom SharePoint Framework (SPFx) solutions, including SPFx controls from independent software vendors (ISVs) for any customizations they have applied or included with purchased products, you must ensure that when installing SP SE 23H2, you verify that any ISV solutions or custom solutions are using SPFx v1.4.1 or lower.

I would be surprised if the SPFx engineering team could support this configuration of having a mix of different SPFx versions and requiring manual updates to the package.json file to accommodate varying versions of React and the Office UI Fabric React.

Hopefully I’ll have an update to this post soon when we get some clarifications from Microsoft! 🤷‍♂️