SharePoint Framework: Upgrade auf SPFx v1.21.1

Einleitung SPFx Upgrade

Microsoft hat im April 2025 Version 1.21 bzw. 1.21.1 [1] des SharePoint Frameworks (SPFx) veröffentlicht. Die neueste Version des SharePoint Frameworks unterstützt jetzt Node.js Version 22 [2]. Da meine bestehenden SPFx-Projekte auf SPFx v1.20 basieren, unterstützen Sie nur Node.js Version 18, dessen Support Ende März 2025 jedoch auslief. Das Upgrade auf SPFx v1.21.1 kommt also gerade rechtzeitig.

Microsofts Anleitung um bestehende SPFx-Projekte zu aktualisieren ist leider recht kurz und aus meiner Sicht nicht ausreichend!

“In the project's package.json file, identify all SPFx v1.20 packages.”

Woher weiß man, welche Pakete genau zum SharePoint Framework gehören? Das von Microsoft empfohlene Kommando dazu ist nicht wirklich hilfreich!

„npm uninstall @microsoft/{spfx-package-name}@1.20“

Da ich einige Projekte zu aktualisieren hatte, habe ich mir ein PowerShell Skript geschrieben (bzw. generieren lassen), dass mich beim Upgrade der Projekte unterstützt. Dieses Skript habe ich in GitHub veröffentlicht [3].

Microsoft gibt den Tipp, CLI for Microsoft 365 [4] für das Upgrade zu verwenden. Da dafür eine Microsoft Entra app erforderlich ist, habe ich diesen Weg nicht weiterverfolgt.

Bestehendes Projekt auf SPFx v1.21.1 upgraden

Ich habe mir mein Skript an zentraler Stelle auf meinem PC abgespeichert und verweise jeweils aus den Projektverzeichnissen darauf. Im Terminal in VS Code rufe ich dann einfach dieses Kommando auf:

PS c:\...\upgrade_spfx_v1.21.1.ps1

Das Skript stellt zuerst sicher, dass die Anforderungen an SPFx v1.21.1 zutreffen, dass Node.js in Version 22 zur Verfügung steht, sowie die Pakete gulp-cli, yo und SharePoint Framework Generator.

Danach wird, auf Wunsch, ein Backup der bestehenden package.json erstellt, die ja im weiteren Verlauf des Upgrades verändert wird.

Als nächstes werden die lokalen Node Caches, also speziell package-lock.json und node_modules gelöscht. Das ist wichtig, da das Upgrade sonst nicht ordentlich funktioniert.

Dann wird mit den ersten Änderungen an der package.json begonnen. Zuerst wird der korrekte Bereich der Node Engine festgelegt – ">=22.0.0 <23.0.0". Anschließend werden die benötigten SPFx Pakete in der korrekten Version installiert. Im weiteren Verlauf werden die anderen Paket-Abhängigkeiten aus der package.json aufgelöst.

Erfahrung mit dem Upgrade auf SPFx v1.21.1

Meine bisherige Erfahrung mit dem Upgrade-Skript war sehr gut. Ich habe damit erfolgreich 6 Projekte, jeweils vom Typ Adaptive Cards Experience, von SPFx v1.20 auf v1.21.1 gehoben. Zwei Projekte konnten anschließend nicht direkt gebaut werden, was aber nicht am Upgrade-Skript lag, sondern an Paket-Abhängigkeiten zu @fluentui/react-components.

Besonderheiten beim Upgrade auf SPFx v1.21.1

Rush Stack

Neue Projekte mit SPFx v1.21.1 enthalten u.a. folgende Entwicklungs-Abhängigkeit:

"devDependencies": {
  "@microsoft/rush-stack-compiler-5.3": "0.1.0",
  "typescript": "~5.8.3"
}

Beim Upgrade von SPFx v1.20 auf v1.21.1 habe ich es nicht geschafft, den rush-stack-compiler von v4.7 auf v5.3 anzuheben. Im Upgrade-Skript wird deshalb das Paket @microsoft/rush-stack-compiler-4.7 beibehalten. Man erhält also nach dem Upgrade:

"devDependencies": {
  "@microsoft/rush-stack-compiler-4.7": "0.1.0",
  "typescript": "~5.3.3"
}

TypeScript

Meine Tests mit TypeScript 5.8 waren alle erfolgreich, trotzdem habe ich mich im Upgrade-Skript strikt an Microsofts Kompatibilitätsliste [5] gehalten und installiere TypeScript 5.3.

Zukünftige Upgrades

Microsoft hat kürzlich seine Roadmap für das SharePoint Framework aktualisiert [6] und dabei u.a. einen neuen Release-Rhythmus angekündigt. Ich werde meinen Skript-basierten Ansatz fortführen und Ende Oktober das neue Upgrade-Skript upgrade_spfx_v1.22.0.ps1 veröffentlichen.

Links

[1] SharePoint Framework v1.21.1 release notes
[2] Node.js v22 (Jod)
[3] upgrade_spfx_v1.21.1.ps1
[4] CLI for Microsoft 365
[5] SPFx development environment compatibility (unbedingt das englische Original öffnen!)
[6] SharePoint Framework (SPFx) roadmap update – September 2025