In my last post, I announced Microsoft released a new version (v1.12) of the SharePoint Framework on March 16, 2021. Unfortunately, this release contained some regressions including some that were so significant, it triggered Microsoft to pull the release just five (5) days after releasing it & recommend people not install it!
Before I dig into what’s going on, let’s jump to the most important topics:
What does this mean for you?
If you haven’t installed SPFx v1.12 and you’re still using SPFx v1.11, it has no impact on you. Don’t upgrade your SPFx generator and stay with SPFx v1.11 for the time being.
How do you go back?
If you have upgraded to SPFx v1.12, you should roll back your installed generator. This release also introduced support for Node.js v12. If you elected to use Node.js v12 with SPFx v1.12, you also had to upgrade your globally installed version of Gulp to v4. This is explained in the SPFx v1.12 release notes.
So… first and foremost, make sure you have Node.js v10 installed as that’s the supported version to use with SPFx v1.11.
Are you using the Node.js installers from the nodejs.org website? Have you considered using a Node Version Manager (NVM)? It makes it possible to have multiple versions of Node installed on your developer environment and easily switch between them.
If you are using the installers from the Node.js website & you installed Node.js v12, you’ll have to uninstall it first before installing Node.js v10.
Learn more from my post here: Better Node.js Install Management with Node Version Manager
Next, make sure you have Gulp v3 installed globally:
npm install gulp@3 --global
@3 at the end of gulp in that statement? That’s how you force npm to install a specific version.And finally, use the same technique to ensure you install SPFx v1.11:
npm install @microsoft/[email protected] --global
That takes care of your development environment.
What if I upgraded my project to v1.12?
But what if you already upgraded a project to v1.12? You should roll this update back & if you were following generally accepted good development practices, you had your project in source control so rolling back should be straight forward.
But what if you don’t have a version you can roll back to? In that case, you have some work to do. The following steps should clean things up, but you depending on your project, you may have to address additional issues after you apply them:
- Open the project’s package.json file.
- Change the version of all SPFx related packages set to 1.12.0 to be 1.11.0.
- Change the version of Gulp to ~3.9.1.
- I doubt you upgraded TypeScript, but if you did, you might need to roll that back as well. The version used in SPFx v1.11 used the @microsoft/rush-stack-compiler-3.3 version 0.3.5.
- Delete the package-lock.json file from the project. This file locks the package versions downloaded. If you left this file, changing the package.json won’t have too much of an effect.
- Delete the node_modules folder if it exists. When you run npm install, it downloads and installs all dependencies listed in the package.json file. Some of these dependences may do different things depending on the current version of Node.js, or from other dependencies. To keep things clean, you should start with a fresh set of dependencies by deleting this folder.
- Run npm install to recreate the node_modules folder.
That should be it! As best I can tell, the code & manifest files didn’t change from SPFx v1.11 to v1.12, so you should be good to go.
What if I created my new project with v1.12?
But what if you created a brand new project with SPFx v1.12? My first recommendation would be to start over with a new project using SPFx v1.11 and copy your code files over.
But if you’ve done a lot of work, or already deployed something, follow the same instructions for rolling back an upgraded project. Your success will be entirely dependent on how much work you’ve done.
Why was SPFx v1.12 pulled?
OK… let’s get back to what’s going on and why Microsoft pulled SPFx v1.12.
Bug #1: Gulp bundle fails when externals referenced in config.json
The biggest reason it was pulled is due to the significant regression where excluding & externalizing packages to CDNs broke with v1.12. This is documented in SharePoint/sp-dev-docs#6833.
Basically, if you used a 3rd party library, like jQuery, and you didn’t want it sucked into your bundle, you can exclude it in the bundling process.
This is critical as it can cause the generated bundles to be huge without this process. But if you used v1.12, you had no option because if you were externalizing packages, the bundling process would fail.
Ultimately this is the bug that caused Microsoft to pull the release back.
But it wasn’t all…
Bug #2: Regens new hashed filename on every build
Many people bypass using the workbenches for development and debugging, rather they work with real SharePoint pages. In fact, this is the only way you can test extensions.
The problem with this bug, documented in SharePoint/sp-dev-docs#6838, is that every time you change your code, the gulp serve process rebuilds & rebundles everything, but it generates new hashed filenames. But the manifests loaded in the SharePoint, which don’t change on a rebuild or rebundle, were not being picked up like all previous versions of SPFx.
Bug #3: Local testing for localization broken
Do you localize your SPFx projects? You know you can test those localizations and force the locale using the gulp serve –locale=nl-nl argument?
Well that only worked until v1.12 came out, as documented in SharePoint/sp-dev-docs#6837.
Bug #4: Gulp bundle doesn’t copy files (breaks deploy-azure-storage task)
The title of the issue isn’t exactly what’s going on. As documented in SharePoint/sp-dev-docs#6847, the gulp bundle –ship task stopped copying files to the temp/deploy location.
That location is used by the gulp deploy-azure-storage task to copy files to an Azure blob storage account that’s usually exposed by an Azure CDN.
Bug #5: Gulp package-solution no longer includes referenced icons
This is similar to bug #4 above. As documented in SharePoint/sp-dev-docs#6847, before v1.12 you could specify the icon image file SharePoint used when displaying your app when showing a list of available options.
But in v1.12, the image wasn’t getting included in the package and therefore, SharePoint was throwing an error when it tried to find the reference the image that was added to the package was malformed which triggered SharePoint to throw an error when it referenced it.
Bug #6: Microsoft pinned tslib to v2
This one is complicated to explain in detail, so I’m going to keep it topical for now. If you want to get into the details, check the issues SharePoint/sp-dev-docs#6856 or /pnp/pnpjs#1654.
In SPFx v1.12, Microsoft pinned the version of tslib, a runtime library for TypeScript that contains helper functions, was pinned to version 2.
The problem with this approach is that when you pin a library version, no other dependency can use a different version. So while this was fine for SPFx, it wasn’t for packages that you wanted to use in your project that used a different version of tslib… like the popular pnpjs project.
What next?
As I said at the start of this post, Microsoft has pulled SPFx v1.12 and told people to use SPFx v1.11 for now.
They are working to address the regressions introduced above & release a new version, SPFx v1.12.1. The promise is that release is coming within days and that it will fix all six of the issues listed above.
In addition, they’re apparently also going to add support for Node.js v14 so SPFx v1.12.1 will be supported in Node.js v10.x, v12.x, and v14.x. That’ll be good to see…
Recommendation
However, with all that being said, I recommend NOT installing & upgrading your production projects to the latest SPFx release for two weeks after Microsoft releases it. This is the second time we’ve see an SPFx version get pulled nor a version that’s had to get a few quick patch releases to address bugs.
Watch the SharePoint dev issues list to see if there are any hot button issues that come up over a week or two after release before you upgrade your own projects.
That’s what I’m doing with my Mastering the SharePoint Framework course. When v1.12.1 comes out, I’ll install and test it, but not make changes to production stuff right away. And when I do, I’ll be sure everything is committed and pushed and I’m working on a new branch first.
From my perspective, there’s nothing in SPFx v1.12 ro v1.12.1 that warrants rushing to install & upgrade to the latest projects. Sure, support for Node.js v12 or v14 will be nice, but it’s not like Node.js v10 spreads a new COVID-19 variant.
