SharePoint Framework - Project Upgrade

Every product goes under the upgrade cycle and SharePoint Framework is no exception to it. SPFx gets updated on a regular basis. With each update the SPFx provides more functionalities and bug fixes. SharePoint Framework client web parts and extensions are developed using JavaScript packages from various authors. The packages are available on npm site (https://www.npmjs.com/). These packages are also gets frequent updates. In order to use the latest offerings the need arises to upgrade our existing SPFx solutions to the newer versions.

Overview

Every product goes under the upgrade cycle and SharePoint Framework is no exception to it. SPFx gets updated on a regular basis. With each update, the SPFx provides more functionalities and bug fixes. SharePoint Framework client web parts and extensions are developed using JavaScript packages from various authors. The packages are available on npm site (https://www.npmjs.com/). These packages also get frequent updates. In order to use the latest offerings, the need arises to upgrade our existing SPFx solutions to the newer versions.
 
In this article, we will explore how to upgrade to newer versions of JavaScript packages.
 
The Upgrade Confusion
 
The first question that comes to mind is if there is a real need of upgrading an existing solution which is tested and is working fine for a while. 
 
The second thought is if you want to take advantage of the latest and the greatest of SharePoint Framework, then this upgrade is necessary.
 
It is an individual choice or a team decision to decide on the upgrade. However, to be in sync with the SPFx happenings, it is better to upgrade.
 
Is Upgrading Simple?
 
The answer is "not always". Upgrading SPFx project is not always easy. You may often run into build errors.
 
The simple steps to upgrade
 
In this article, we will reuse CRUD Operations using No Framework implemented (from the previous article). Download the source code from the previous article to get started with upgrading the project.
 
At the time of writing the previous article, SPFx version available was 1.5.1.
  1. Open the command prompt.
  2. Navigate to the SPFx project folder.
  3. Type the below command to open the project in the code editor.

    code .  

  4. Open package.json.

    SharePoint Framework - Project Upgrade

  5. SharePoint Framework packages are denoted by prefix @microsoft/sp-.
  6. The version here is 1.5.1.
The upgrade process
 
The upgrade process will help us to upgrade our solution to the latest SPFx version (1.6 at the time of writing this article).
  1. Open the command prompt.
  2. Navigate to the SPFx project folder.
  3. Type the below command to get the list of outdated packages.

    npm outdated  
 
The list has the below information.
  • Current: Current version of a package used in the solution.
  • Wanted: Version needed by the project (mentioned in package.json).
  • Latest: the latest available version of the package.
Upgrade the packages
 
We need to upgrade each package reported as outdated.
 
To upgrade the package to a specific version, use the below command.
  1. npm install [package]@[version] --save  
To upgrade the package to the latest version, use the below command.
  1. npm install [package]@latest --save  
Example
  1. npm install @types/chai@latest --save  
Or use the below command.
  1. npm install [package] --save  
Example
  1. npm install @microsoft/sp-core-library --save  
Verify the updates
 
In the command prompt, type below command to open it in the code editor.
  1. code .  
Open package.json.
 
Verify that the packages are updated.

SharePoint Framework - Project Upgrade 
 
Run the below command to update config.json to the latest version.
  1. gulp --update  
Clean up the earlier packages by running the below command.
  1. gulp clean  
Run the below command to build the project.
  1. gulp build  
Run the project with the below command.
  1. gulp serve  
If this goes well, you have your project upgraded to the new version. If for some reason, the upgrade does not go well, follow the below steps.
 
Install the latest version of Yeoman generator version.
  1. npm update -g @microsoft/generator-sharepoint@latest  
Create another SharePoint Framework solution (let’s call it as Latest-Version-Solution)
 
The Latest-Version-Solution has a reference of all the latest packages.
 
Compare and merge the package.json. I am using “Code Compare” from devart.
 
SharePoint Framework - Project Upgrade
 
Below is the merged package.json.
  1. {  
  2.   "name": "spfx-crud-no-framework",  
  3.   "version": "0.0.1",  
  4.   "private": true,  
  5.   "engines": {  
  6.     "node": ">=0.10.0"  
  7.   },  
  8.   "scripts": {  
  9.     "build": "gulp bundle",  
  10.     "clean": "gulp clean",  
  11.     "test": "gulp test"  
  12.   },  
  13.   "dependencies": {  
  14.     "react": "15.6.2",  
  15.     "react-dom": "15.6.2",  
  16.     "@types/react": "15.6.6",  
  17.     "@types/react-dom": "15.5.6",  
  18.     "@microsoft/sp-core-library": "1.6.0",  
  19.     "@microsoft/sp-webpart-base": "1.6.0",  
  20.     "@microsoft/sp-lodash-subset": "1.6.0",  
  21.     "@microsoft/sp-office-ui-fabric-core": "1.6.0",  
  22.     "@types/webpack-env": "1.13.6",  
  23.     "@types/es6-promise": "3.3.0"  
  24.   },  
  25.   "devDependencies": {  
  26.     "@microsoft/sp-build-web": "1.6.0",  
  27.     "@microsoft/sp-module-interfaces": "1.6.0",  
  28.     "@microsoft/sp-webpart-workbench": "1.6.0",  
  29.     "tslint-microsoft-contrib": "~5.0.0",  
  30.     "@types/chai": "4.1.6",  
  31.     "@types/mocha": "5.2.5",  
  32.     "ajv": "6.5.4",  
  33.     "gulp": "~3.9.1"  
  34.   }  
  35. }  
Also, compare and merge tsconfig.json file.
 
Delete package-lock.json or npm-shrinkwrap.json from the solution.
 
Delete the node_modules folder.
 
Run this command to download the updated npm packages.
  1. npm install  
Delete previous build output by running the below command.
  1. gulp clean  
Lock the package versions by running the below command.
  1. npm shrinkwrap  
Run the SPFx solution.
  1. gulp serve  

Summary

It is not mandatory but advisable to upgrade SPFx projects to get benefits of newer functionalities from latest versions. The upgrade process might not be easy, but can be carefully planned and executed.