On Thursday, March 14, 2019, Microsoft released v1.8.0 of the SharePoint Framework (SPFx). This release is packed with many features that were previously in developer preview to the Generally Available (GA) milestone. However, there are some subtle updates that developers have been asking for.
In this post, I'll summarize some of what you can find, but also share some details I found after spending some time with the v1.8.0 release, kicking the tires and finding a few resolutions to issues.
A new SharePoint Framework Yeoman generator has been published by OfficeDev: 1.8.0 #SPFx Office365— Voitanos (@voitanos) March 14, 2019
What's in the SPFx v1.8.0 Release?
- Generally available (GA) features
Note: At the current time, dynamic data is limited to using just the page context as a data source when deploying web parts in isolated domains.
- New developer preview feature
- Library components - create shared code deployed in its own *.sppkg file and referenced by other SPFx projects.
- Legacy Office UI Fabric CSS consumption - cleaning up old CSS classes. See the release notes for details if you need to continue to use the previous model.
Getting the Latest SharePoint Framework
There are two things to do to get your developer environment updated for v1.8.0. The first one is to upgrade the version of the SPFx Yeoman generator.
Check if your currently installed generator is outdated:
npm outdated --global
If the @microsoft/generator-sharepoint generator isn't listed as v1.8.0, then you're outdated. Upgrading is simple as you just install the new one on top of the old one:
npm install @microsoft/generator-sharepoint --global
The second step is to upgrade your individual projects to v1.8.0.
Upgrading Existing SPFx projects to v1.8.0
Check the release notes for details on how to upgrade your existing projects to SPFx v1.8.0.
Alternatively, use the Office 365 CLI's spfx project upgrade for assistance in obtaining a list of everything you need to do to update your project.
Are you ready to learn the SharePoint Framework? Check out my on-demand video course with over 30 hours of demos, explanation and downloadable code: Mastering the SharePoint Framework
Changes to project codebase
Microsoft made a lot of updates to support the Microsoft Teams Tabs development with SPFx, but also to support some of the things I'll mention below. When you create a new project, you'll notice a few things.
Web Part Manifest
Within a web part's manifest file, you will find a new property set with a default value:
This is used to specify where this web part can be used. By default, it is set to be a SharePoint web part, but you can also add an additional value of
TeamsTab if it can also be used as a tab in Microsoft Teams. Alternatively, you can even set it to only be a tab in Microsoft Teams and not available as a SharePoint web part.
Teams Tab Manifest
When a Microsoft Teams manifest is present in the project, the default value of the property
configureTabs.canUpdateConfiguration has been switched from
true. You can change it back, but this is the new default behavior.
There are two significant updates to the project file. First, there is a new package in the
devDependencies section for web part & extension project types:
I'll dig into this a bit more in the section Support for TypeScript v2.7, v2.9 & v3.x (from v2.4.2) later in this post.
In addition, a new package has shown up for the first time in web part projects:
Introduced in this release, you will find the
import section within a web part has undergone a bit of refactoring. Microsoft has elected to move all the property pane related code & types to its own package: @microsoft/sp-property-pane.
So, prior to v1.8.0, a default project that used to look like this:
Will now look like this in v1.8.0:
It is important to note that any existing projects upgraded to SPFx v1.8.0 that contain web parts will continue to work with the pre-v1.8.0 code that references property pane objects in the @microsoft/sp-webpart-base. The SPFx v1.8.0 codebase will continue to work and forward the references to the new package.
However, these forwarded references will be removed in the SPFx v1.9 release. There is no published timetable for the v1.9 release, but I'd expect to see it around the Microsoft Build / SharePoint Conference time frame in May 2019. So while you have some time, I'd suggest putting this refactoring on your backlog sooner rather than later.
Update Supported Fabric React version to v6.143.0 (from v5.131.0)
This is a big update that many people have been looking for. There were a lot of things fixed and added to the v6 version of Fabric React that people had been asking for.
The blocker for Microsoft adding support for this in SPFx v1.7.1 was that Fabric React required a more current version of React & TypeScript than what was supported in SPFx at the time. As you'll see in the following two sections, we can now remove those barriers.
If you create a new SPFx project with v1.8.0 and try to use a component from the version of Fabric React that was included in the dependency chain, your build will fail. You will need to minimally upgrade the version of TypeScript your project uses in order to do this.
How do you do that? Continue reading!
Update Supported React Version to v16.7 (from 16.3.2)
As I covered the last time Microsoft released the SharePoint Framework (SharePoint Framework v1.7.0 - What's in the latest update of SPFx?), Microsoft updated the version of React they supported in SPFx and hosted in SharePoint Online to v16.3.2. But almost immediately, people started to ask for an even more current version of React.
While this SPFx v1.8.0 release updates the supported version of React to v16.7, there is one small caveat: Microsoft forgot to update the TypeScript type declarations in the project that contain references to the latest APIs.
I expect they will fix this in a future release, but for now, you have a manual step to perform:
npm install @types/[email protected] --save-dev --save-exact
All done? Don't you wish! These latest type declarations require an updated version of TypeScript… specifically TypeScript v3.2 or higher.
So how do you update your project to use a more current version of TypeScript from the current version it uses (v2.7.x)? Keep reading…
Support for TypeScript v2.7, v2.9 & v3.x (from v2.4.2)
This has been something that SPFx developers have been asking for quite a while. We've been using a fairly old version of TypeScript and been unable to upgrade the project to use the latest version.
In the v1.8.0 SPFx release, Microsoft did a considerable amount of work to decouple the version of TypeScript that you use from the version of the SharePoint Framework. You can now specify the version of TypeScript that you want to use separate from what the build system uses. In fact, you can use any compiler listed here!
Actually you can do any TypeScript versions listed in the following listing https://t.co/QgYou9zpJe, so also 3.x— Vesa Juvonen (@vesajuvonen) March 14, 2019
Previously I made a reference to the package @microsoft/rush-stack-compiler-#.#. This package is tied to a specific version of the TypeScript compiler. So… if you want to use a specific version of TypeScript, you simply need to install the version of TypeScript you want to use as well as the associated @microsoft/rush-stack-compiler package. Notice the version of TypeScript that the package supports is in the package's name… that's the number part in the suffix of the name.
By default, new SPFx v1.8.0 projects use TypeScript v2.7. But if you wanted to use a different version, such as TypeScript v3.3, you would execute the following:
You also will need to go into the TypeScript project file for the project, tsconfig.json (located in the root of the project), and change the package reference for the
extends property. By default, it currently points to the v2.7 version of the package.
I also strongly recommend you delete the node_modules folder & any package manager lock files (package-lock.json / yarn.lock / shrinkwrap.yaml) in your project and reinstall everything with
npm install (or your package manager of choice). Otherwise, you will likely get a mismatch of packages and loads of build errors.
One more thing… the SPFx team has noticed that SPFx has issues with some of the newer versions of their @microsoft/rush-stack-compiler package. I've done some testing with the release notes and can attest that the following versions work:
Hat tip to fellow MVP's Elio Struyf & Marc Anderson for some additional blog posts that cover some of the same topics I covered here:
- Elio Struyf: Using the Full Potential of React in the SharePoint Framework v1.8.0
- Elio Struyf: Define the TypeScript Version you Want to use in the SharePoint Framework
- Marc Anderson: Common Issues in SPFx v1.8.0 with TypeScript v3.3