How to upgrade your SPfx project to the latest version, and how to fix/avoid common issues

By Eli H. Schei on

Recently I had to upgrade an older project to the newest version of SPfx, and even though there are some great tools to help you on your way you typically run into some errors anyway. In my search for solutions all I found was posts about upgrading older versions of SPfx. So I thought I should write a blogpost that covers upgrading to the newest per june 2022, which is SPfx 1.14.0

How to upgrade your project

You could try to just upgrade the SPfx packages that are listed in package.json. But these might have other dependencies that should also be updated and their packages might have dependencies… and so on.

So instead I reccomend that you use Microsoft 365 CLI to generate a report that tells you exactly what to upgrade.

1. Install Microsoft 365 CLI 

npm i -g @pnp/cli-microsoft365

2. Use the project upgrade command to get a upgrade-report for your project

m365 spfx project upgrade --toVersion 1.14.0 --output md > "upgrade-report.md"

The above command will generate a markdown file with the name “upgrade-report”, and this will have a list of all the steps you need to take to upgrade your project.

Common errors and how to fix them (or avoid them)

Even though you follow the report you migh encounter some issues when trying to build your solution afterwards.

1. Check for duplicate dev-dependencies

Even though these are strictly speaking different npm packages you should only have on of them listed as a dependency or they might “get in each others way”. Check the upgrade report for wich version you should use. For me it was "...compiler-3.9": "0.4.47". So I removed the other one.

2. Delete node_modules, and package-lock.json

You can try npm dedupe before deleting node_modules and package-lock. This might solve any issues related to old versions – thanks to Waldek Mastykarz for mentioning this on twitter

To be sure there aren’t any old versions hanging around delete both your node_modules folder and the package-lock.json file and run npm install.

3. Deprecated tslint rules

You might need to remove some tslint rules that are no longer valid. The error message will tell you witch rule you need to remove. For me it was the member-access rule. 

Error - [tslint] The 'member-access' rule threw an error ...

4. JavaScript heap out of memory

In my case, since this had something to do with tslint I think what probably solved it was removing the duplicate dependency as shown in the above section. But through my travels in google searches this showed up in multiple issues over differnt versions of SPfx – so I thought I should mention it.

If you have done the above steps and still gets this error it might be because the task needs more memory to run, so you can try fixing it by setting the --max_old_space_sice to a higher value. 

 gulp bundle --max_old_space_size=8192 --ship

Summary

In short the steps you shuld take to upgrade your solution is

  • Run the M365 CLI project upgrade command
    • Do all the steps from the report that is generated
  • Check packacke.json for duplicate dev-dependencies
  • Try running npm dedupe
  • Delete node_modules and package-lock.json, and then run npm install.
  • If you get an error on deprecated tslint rules – delete the rules from the tslint file
  • If you get an JavaScript heap out of memory error – try adding more memory to the task with
    --max_old_space_size=8192

Have you encountered any other errors that should be mentioned? Let me know in the comments, or send me a tweet.

If you are interested in Microsoft 365 Development you might also like my other blogposts in this category.

Also, if you have any feedback or questions, please let me know in the comments below. 🙂

Thank you for reading, and happy coding!

/Eli

If you want to support my content you can

7 thoughts on “How to upgrade your SPfx project to the latest version, and how to fix/avoid common issues”

  1. Pingback: My top 5 uses for Microsoft 365 CLI - A cup of dev

Leave a Reply