Upgrading your SharePoint Framework (SPFx) solution ensures access to the latest features, performance improvements, and security patches. The CLI for Microsoft 365, formerly known as Office 365 CLI, offers a streamlined approach to facilitate this upgrade process. This article provides a step-by-step guide on how to upgrade your SPFx solution (to 1.20.0) using the CLI for Microsoft 365.
Prerequisites
efore initiating the upgrade, ensure the following tools are installed on your system:
- Node.js: SPFx v1.20.0 supports Node.js versions 16.13.0 to less than 17.0.0, and versions 18.17.1 to less than 19.0.0. It’s recommended to use Node.js v18.18.0 for compatibility.
- Gulp CLI: The task runner for SPFx projects.
- Yeoman: A scaffolding tool used by SPFx.
- @microsoft/generator-sharepoint: The SPFx Yeoman generator.
- CLI for Microsoft 365: The tool to assist with the upgrade process.
Step 1: Install Node.js
Use Node Version Manager (nvm) to install the recommended Node.js version:
nvm install 18.18.0
Step 2: Install SPFx Toolchain
Install the necessary global packages:
Step 4: Generate Upgrade Report
Navigate to your SPFx project directory and generate the upgrade report:
This command creates a Markdown file (upgrade-report.md) detailing the necessary steps to upgrade your project to version 1.20.0. The CLI analyzes your project and provides a comprehensive list of required modifications.
Step 5: Review and Apply Changes
Open the upgrade-report.md file in a Markdown viewer or code editor to review the recommended changes. The report is divided into sections:
- Findings: Detailed information about each required change.
- Summary: A consolidated list of commands and manual modifications needed.
Manually apply the changes as per the report’s guidance. This typically involves updating package versions in package.json, modifying configuration files, and adjusting code to align with the new SPFx version.
Step 6: Install Updated Packages
After applying the necessary changes, install the updated packages:
npm install
This command ensures all dependencies are aligned with the updated SPFx version.
Step 7: Validate the Upgrade
Once the installation is complete, build and test your project to confirm that the upgrade was successful:
gulp build gulp serve
Address any build errors or warnings that arise, as they may indicate issues that need resolution post-upgrade.
Additional Considerations
Interactive Upgrade Report: For a more guided experience, the CLI for Microsoft 365 can generate an interactive upgrade report compatible with Visual Studio Code’s CodeTour extension:
m365 spfx project upgrade –toVersion 1.20.0 –output tour
This approach provides step-by-step instructions within your code editor, enhancing the upgrade experience.
- Regular Updates: The SPFx evolves continually. Regularly updating your projects ensures compatibility and access to new features. The CLI for Microsoft 365 is frequently updated to support the latest SPFx versions, making it a reliable tool for ongoing project maintenance.
By following these steps and utilizing the CLI for Microsoft 365, you can efficiently upgrade your SPFx solutions, ensuring they remain current and fully functional with the latest enhancements.
Conclusion
Keeping your SharePoint Framework (SPFx) solutions up to date is essential for maintaining security, performance, and compatibility with the latest SharePoint features. By leveraging the CLI for Microsoft 365, you can streamline the upgrade process and reduce the risk of errors.
By following this step-by-step guide, you ensure a smooth transition to SPFx 1.20.0, enabling your solutions to benefit from the latest improvements. Regular updates not only enhance your projects but also help you stay ahead in the evolving Microsoft 365 ecosystem.