Microsoft MVP Logo

This post has been cross-posted to the Voitanos blog here: SharePoint Framework Generator Updated from v1.4.0 to v1.4.1: Inspecting the Changes.

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 Azure AD 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

TL;DR? Watch the Summary Video

Not enough time to read through this? Watch the video summary of the SPFx Generator v1.4.1 Release over on the Voitanos blog here:

The good news is that it doesn't appear that there is too much work to upgrade your existing projects from v1.4.0 to v1.4.1. Most of the changes are the introduction of new capabilities and two bug fixes. The potential impacts I've identified are:

  • GraphHttpClient: If you were using the included Microsoft Graph client API that was in preview, you'll need to update your code. This update includes a completely new API and the old one has been deprecated. Now you know why you should consider building with preview APIs... things can change before release!
  • Updated React TypeScript Declarations: The type declarations package was updated to the latest version for those of you who are using React in your SPFx projects.

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 Azure Active Directory

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 Azure AD Client for Calling Azure AD Secured API Endpoints

The AadHttpClient has a more significant impact. This new API enables developers the ability to connect to Azure AD 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 a crossOrigin property
  • Updated interface ReactHTML & IntrinsicElements, changing the type of the dialog property
    • from: DetailedHTMLFactory<HTMLAttributes<HTMLElement>, HTMLElement>
    • to: DetailedHTMLFactory<DialogHTMLAttributes<HTMLDialogElement>, HTMLDialogElement>

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 NODENOHTTP2=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:

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.

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.

Comments powered by Disqus