Webinar recording
Summary
Yesterday Microsoft released a new version of the SharePoint Framework (SPFx) generator to version 1.4.1. I took some time picking apart the update and in this post I will show you what these changes have in store for you. Not bad timing… this update is showing some love to developers with some highly anticipated features! Too bad they missed Valentine’s Day by just one day… wait… this a developer update… they were off by one… heeeeeyyyyy… I see what you did there… well played Microsoft!
What’s in this update?
- NEW Microsoft Graph API
- NEW Microsoft Entra ID API
- Updated React TypeScript declarations
- Support for Node.js v8.* (LTS)
- Fix long standing error where SPFx client-side web parts weren’t showing in the toolbox
There is one point I do want to make before I get into this: I strongly recommend you upgrade your generator to this latest version 1.4.1 ASAP. This update includes a fix to a nasty bug that is not run to resolve with older projects. I’m referring to bug #775… keep reading to learn more.
Check if your currently installed generator is outdated:
npm outdated --global
If the generator is listed in the results of that command, then you are outdated.
Grab the latest version by running:
npm install @microsoft/generator-sharepoint --global
Let’s start by looking at what’s new in the update.
Introducing New APIs for the Microsoft Graph and Microsoft Entra ID
This update was a highly anticipated update as it introduced a revamped API for the Microsoft Graph, the MSGraphClient, and the AadHttpClient.
New Microsoft Graph Client Replaces (and Deprecates) the Former Graph Client in Preview
The new MSGraphClient Microsoft Graph client replaces the previous API, GraphHttpClient, which has now been deprecated. This new one wraps the existing Microsoft Graph JavaScript Client Library. The SPFx wrapper simplifies using the one created by the Microsoft Graph team as it handles the authentication aspect for you, allowing you to focus on building your solution. This is a welcomed change from the old client… I’d much prefer the SPFx team not build a Graph client, but instead rely on what the Graph team provides. This also makes the transition easier for those who choose to use the Microsoft Graph JavaScript Client Library outside of SPFx solutions.
This is a new API that is released in preview so all the same rules apply to preview APIs: things may change before a Generally Available (GA) release.
You can learn more using the following links to the official Microsoft documentation:
New Entra ID Client for Calling Entra ID Secured API Endpoints
The AadHttpClient has a more significant impact. This new API enables developers the ability to connect to Entra ID secured endpoints from SPFx solutions. Previously developers could call secured endpoints, but it required everything to happen client side and thus, your users would not have the best experience when your SPFx solution needed to call out to a secured endpoint.
This new approach leverages the Microsoft Graph to effectively make the call to your AzureAD secured endpoint from the server and thus, it’s much easier to lock things down.
This is a new API that is released in preview so all the same rules apply to preview APIs: things may change before a Generally Available (GA) release.
You can learn more using the following links to the official Microsoft documentation:
What Changed in v1.4.1?
After picking through the latest release of the SharePoint Framework Yeoman generator, I’ve uncovered a few changes I can share with you. The changes come in two forms:
- project updates
- build toolchain updates
Let’s first look at the project updates as the build toolchain updates don’t require any changes to your projects, but do resolve two issues we have been dealing with… unfortunately one is quite nasty and requires some extra work on your part…
Upgrading SPFx v1.4.0 Solutions to v1.4.1
Upgrading solutions from v1.4.0 to v1.4.1 is fairly painless. Most of the depednent libraries were simply version bumped meaning they just updated the versions from v1.4.0 to v1.4.1 to keep things in sync. This means you can open the package.json file in your projects any anywhere you see a reference to a SPFx related package, update the version from v1.4.0 to v1.4.1.
This includes the following packages. Some of the following packages may not be in your project depending on the type of component you’ve built, such as a client-side web part with or without React or an extension such as an application customizer, field customizer or command set.
- Dependencies
- @microsoft/decorators
- @microsoft/sp-application-base
- @microsoft/sp-core-library
- @microsoft/sp-dialog
- @microsoft/sp-listview-extensibility
- @microsoft/sp-lodash-subset
- @microsoft/sp-office-ui-fabric-core
- @microsoft/sp-webpart-base
- DevDependencies
- @microsoft/sp-build-web
- @microsoft/sp-module-interfaces
- @microsoft/sp-webpart-workbench
If you find any of these packages in your package.json file, update the version to v1.4.1 & then rerun npm install.
The other option is to use your package manager to update the packages.
If you are using npm, run npm update and it will download all the updated package versions & update the package.json file accordingly.
If you are using Yarn, you can run either yarn upgrade to do the same thing as above, or yarn upgrade-interactive to see exactly what is going to be upgraded and optionally opt-in / opt-out of each upgrade task. Refer to the Yarn docs for more details: yarn upgrade, yarn upgrade-interactive.
New React TypeScript Type Declarations
This update also included an update to the TypeScript type declarations SPFx projects that leverage React rely on. Specifically the @types/react package reference was updated from v16.0.36 to v16.0.38. The new version upgrades the supported TypeScript version of the types from TypeScript v2.3 to v2.6.
This is a relatively minor update as it includes a few new types such as:
- New interface
DialogHTMLAttributes - Updated interface
ImgHTMLAttributes, adding acrossOriginproperty - Updated interface
ReactHTML&IntrinsicElements, changing the type of thedialogproperty- from:
DetailedHTMLFactory<HTMLAttributes<HTMLElement>, HTMLElement> - to:
DetailedHTMLFactory<DialogHTMLAttributes<HTMLDialogElement>, HTMLDialogElement>
- from:
Added Support for Node.js v8.* (LTS)
This is quite the welcomed update… when Node.js v8 was released, it changed the default from using HTTP 1.2 to HTTP 2. This caught a lot of people by surprise as the Node.js guys had to introduce a flag that would later let you disable HTTP2 in Node.js v8.*.
Unfortunately this slipped by the SPFx folks at Microsoft and the local workbench hosting web server wasn’t taking this into account. This was widely referred to as issue #1002.
No more prefacing your commands, or setting the global environment variable NODE_NO_HTTP2=1!
How was it fixed? This bit of code buried deep in the @microsoft/sp-build-core-tasks package that "… is collection of tasks for the SharePoint Framework build system, which is based on gulp. The sp-build-core-tasks package implements various SharePoint-specific operations such as packaging solutions, writing manifests, etc."
Now when you execute the gulp serve task in the SPFx build toolchain, it runs this method which will load the npm package http2 if needed:
_loadGulpConnect() {
// this will raise an exception if it can't find http2,
// which happens if we are on Node6 and 'http2' has not been required yet
let http2CacheKey = 'http2';
try {
http2CacheKey = require.resolve('http2');
}
catch (exception) {
// no-op
}
/* tslint:disable:typedef */
let gulpConnect;
// node 6 and http2 is in cache
if (Object.keys(require.cache).indexOf(http2CacheKey) !== -1) {
// store the old cache value
const http2CacheObject = require.cache[http2CacheKey];
require.cache[http2CacheKey] = { exports: undefined };
gulpConnect = require('gulp-connect');
// restore the old cache value
require.cache[http2CacheKey] = http2CacheObject;
}
else {
// node 8 or http2 is not in cache, insert a module with no exports into cache
require.cache[http2CacheKey] = { exports: undefined };
gulpConnect = require('gulp-connect');
// remove module with no exports from cache
delete require.cache[http2CacheKey];
}
/* tslint:enable:typedef */
return gulpConnect;
}
Fixed Bug Where FeatureIDs Changed Between SPFx Solution Packaging Runs
A bug (issue #775) was reported a while back where people were noticing their SPFx client-side web parts were not appearing in the web part toolbox. Apparently what had been happening was when you packaged your project, the SPFx build tool chain was creating a new GUID for the feature used to provision the web part into the SharePoint site’s Web Part Gallery… every time. This shouldn’t happen… the GUID of a feature should never change once it’s been created.
The root cause of this bug was pretty easy to fix… as you can see from the code below, buried deep in the packageSolution task, when the packaging process created the feature, it was creating a new GUID each time. This code has been fixed to reuse the existing feature’s ID if one exists and if not, only under those conditions should a new GUID be created.
function createFeatureFromComponent(component) {
return {
title: `${component.name} Feature`,
description: `A feature which activates the Client-Side ${component.manifest.componentType} named ` +
`${component.name}`,
// id: uuid.v4(), <<< old, pre v1.4.1 way of generating the Feature ID
id: component.id || uuid.v4(),
// or generate a new uuid if it doesn't (e.g. for client-side assets feature)
components: [component],
assets: {
elementFiles: [],
elementManifests: [],
upgradeActions: []
}
};
}
While the fix is easy, if you were experiencing this bug, you’ll have some work to do to clean it up, as documented in the release notes.