Upgrading SharePoint Framework projects to a newer version of the SharePoint Framework isn’t always straight-forward. Luckily, it just became a bit easier.

Evergreen SharePoint Framework

SharePoint Framework is the fastest growing model for extending SharePoint to-date. Many organizations, both using SharePoint Online and on-premises, use the SharePoint Framework to extend SharePoint to their specific needs.

Microsoft is heavily investing in the SharePoint Framework. Since its general availability, we’ve already got 7 releases with changes and additions and even more capabilities have been recently announced for the coming months.

If you are building solutions using the SharePoint Framework for use with SharePoint Online, you can immediately benefit of the latest capabilities in your solutions. But to do so, you first need to upgrade your project to use the latest version of the SharePoint Framework. And here is where things get complicated.

Upgrading SharePoint Framework projects

Each release of the SharePoint Framework contains a different set of updates. To upgrade your project, you will likely need to upgrade the versions of the SharePoint Framework libraries referenced in your project. But should you update the references to React or its typings and if so to which version? Are there any other dependencies that you should add to your project? What about the project files? Has anything changed in there as well? It’s hard to keep track of what’s changed in each version not to mention what to change in your project exactly to upgrade it to that particular version. Until now.

Easily upgrade SharePoint Framework projects with the Office 365 CLI

Office 365 CLI simplifies the process of upgrading SharePoint Framework projects, by giving you a complete overview of what you should change in order to upgrade your project to the specified version of the SharePoint Framework.

What is Office 365 CLI

Office 365 CLI is a cross-platform CLI that allows you to manage various configuration settings of Office 365 no matter which operating system or shell you use. While originally designed to manage configuration of Office 365 tenants, with the latest beta release, the Office 365 CLI allows you to manage SharePoint Framework projects as well.

Upgrade SharePoint Framework project to a newer version of the SharePoint Framework using the Office 365 CLI

Important: Office 365 CLI doesn’t change your project files and you need to apply the necessary changes yourself.

To upgrade your SharePoint Framework project to a newer version of the SharePoint Framework, in the command line:

• install the latest beta of the Office 365 CLI by executing npm i -g @pnp/office365-cli@next (you only need to do this once on your machine)
• change the working directory to where your project is located
• execute the command o365 spfx project upgrade --output md > report.md

Running this command will generate a file named report.md with details about what you need to change in your project to upgrade it to the latest version of the SharePoint Framework supported by the Office 365 CLI (at the moment of writing this article it’s v1.5.0). If you want to upgrade to a specific version, change the command to o365 spfx project upgrade --toVersion 1.4.1 --output md > report.md.

The first part of the upgrade report generated by the Office 365 CLI contains detailed findings of what needs to be changed in your project.

In the second part of the report, you will find a summary showing the commands you should execute and the files you should change.

At the moment of writing this article, Office 365 CLI supports upgrading projects created using SharePoint Framework v1.4.1 to version 1.5.0 but you can expect more versions to be added in the future.

Closing thoughts and a call to action

We’ve been thinking about extending the Office 365 CLI with the ability to manage SharePoint Framework projects for a while now. Helping developers to upgrade their projects to a newer version of the SharePoint Framework seemed like a good place to start. After investigating a few approaches, we came up with a first draft which is available in the latest beta of the Office 365 CLI.

For now we decided not to apply the discovered findings automatically. Changing files, especially when it comes to code, is tricky and we would hate to break your project despite our best intentions. If the discovery and upgrade logic turns out robust enough, we could change our stance in the future and apply the changes for you. For now, we settled on discovering the necessary changes and providing you with a comprehensive report. Next, we want to add more versions of the SharePoint Framework to help developers upgrade their older projects as well.

Try it today!

If you have a SharePoint Framework project created using version 1.4.1, we would highly appreciate it if you tried to upgrade it using the Office 365 CLI. We would love to hear how you like how we report findings, if the upgrade reports is clear, if the summary is useful and actionable and if there is anything else that we could improve.

Install the latest beta of the Office 365 CLI by executing npm i -g @pnp/office365-cli@next and upgrade your SharePoint Framework project!

Big thanks to Andrew Connell for his initial thoughts and input on the upgrade process.