SPFx 1.22 -- Das größte SharePoint Framework Update seit Jahren

Ich hab gerade mein erstes SPFx 1.22 Projekt gescaffolded. Kein gulpfile.js. Keine npm audit Warnungen. TypeScript 5.8 out of the box. Nach Jahren mit demselben Fundament fühlt sich dieses Release tatsächlich anders an.

SPFx 1.22 ist am 10. Dezember 2025 GA gegangen, und die Toolchain hat ihr erstes ernsthaftes Overhaul seit 2016 bekommen. Die Headline: Gulp ist raus, Heft ist drin. Aber unter der Haube passiert mehr, als nur einen Build Orchestrator gegen einen anderen zu tauschen.

Was sich wirklich geändert hat

Drei Dinge zählen in diesem Release. Alles andere folgt daraus.

1. Gulp wird durch Heft als Build Orchestrator ersetzt. Gulp hat SPFx sechs Jahre lang gute Dienste geleistet, aber der custom gulp-core-build Stack war unmaintained geworden, voll mit veralteten Dependencies und schwer zu erweitern. Heft ist eine Config-gesteuerte Toolchain aus dem Rush Stack Ökosystem, die Microsoft intern schon verwendet. Webpack macht weiterhin das eigentliche Bundling – Heft orchestriert nur den Build-Prozess.

2. TypeScript 5.8 ist der neue Default. Neue Projekte, die mit dem 1.22 Generator gescaffolded werden, verwenden sofort TypeScript v5.8. Kein manuelles TypeScript-Upgrade mehr und Hoffen, dass nichts kaputt geht.

3. Null npm audit Schwachstellen. Das hat mich zum Grinsen gebracht. Führ npm audit auf einem frisch gescaffoldeten 1.22 Projekt aus und du bekommst einen sauberen Report. Nach Jahren, in denen man Dutzende Audit-Warnungen in jedem SPFx Projekt ignoriert hat, macht allein das schon das Upgrade wert.

Dein erstes SPFx 1.22 Projekt erstellen

Bevor du loslegst, stell sicher, dass du Node.js v22 LTS installiert hast. SPFx 1.22 braucht Node 22 – frühere Versionen wie Node 18 oder Node 20 funktionieren nicht.

Den neuesten Generator installieren:

npm install @microsoft/generator-sharepoint@latest --global

Ein neues Projekt scaffolden:

yo @microsoft/sharepoint

Der Yeoman Generator führt dich durch dieselben Prompts wie vorher – Solution Name, Web Part oder Extension, React oder kein React. Nichts Neues dort. Aber der Output ist, wo es interessant wird.

Die neue Projektstruktur

Öffne dein frisch gescaffoldetes Projekt und das Erste, was dir auffällt: es gibt kein gulpfile.js. Stattdessen findest du neue Config Files im config/ Verzeichnis.

Was sich geändert hat:

config/rig.json

Das ist das wichtigste neue File. Es sagt deinem Projekt, dass es seine gesamte Build-Konfiguration von einem geteilten “Rig”-Package erben soll:

{
  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
  "rigPackageName": "@microsoft/spfx-web-build-rig"
}

Diese eine Zeile – rigPackageName – zeigt auf ein npm Package, das die komplette SPFx Build-Definition enthält. Phases, Tasks, Webpack-Konfiguration, TypeScript-Einstellungen – alles im Rig definiert. Dein Projekt referenziert es nur. Das bedeutet weniger Config-Clutter in deinem Repo und eine einzige Source of Truth für die Build Pipeline.

config/sass.json

Dieses File erweitert die Default Sass-Konfiguration aus dem Rig:

{
  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft-sass-plugin.schema.json",
  "extends": "@microsoft/spfx-web-build-rig/profiles/default/config/sass.json"
}

Wenn du die Sass-Verarbeitung anpassen musst (zum Beispiel File Extensions einschränken), überschreibst du Properties in diesem File, anstatt custom Gulp Tasks zu schreiben.

Kein lokales heft.json

Du würdest vielleicht ein config/heft.json in deinem Projekt erwarten. Du wirst keins finden. Das Rig Package enthält das heft.json mit allen Phase- und Task-Definitionen. Dein Projekt erbt alles von @microsoft/spfx-web-build-rig, außer du überschreibst es explizit.

Die neuen Build Commands

Das ist der Teil, der dein Muskelgedächtnis betrifft. Die npm Scripts in package.json rufen jetzt Heft statt Gulp auf.

Hier das Mapping von alt zu neu:

Ein paar Dinge, auf die du aufpassen solltest:

• --ship ist jetzt --production. Überall. Du wirst das mindestens einmal vergessen.
• Build und Bundle sind kombiniert. Heft hat kein separates bundle Command – heft build kompiliert und bundled in einem Schritt.
• heft start ersetzt gulp serve. Selbes Ergebnis, anderer Befehl.
• Es gibt ein neues heft dev-deploy Command, das deine gebauten Assets auf ein Testing CDN deployed, damit du validieren kannst, wie deine Komponente von einer externen Quelle lädt. Gulp hatte nichts Vergleichbares.

Dein typischer Entwicklungs-Workflow wird:

# Dependencies installieren
npm install

# Lokale Workbench starten
heft start

# Production Build und Package
heft build --production
heft package-solution --production

Oder wenn du lieber die npm Scripts aus package.json verwendest:

npm run build
npm start

Was gleich bleibt

Nicht alles hat sich geändert, und das ist erwähnenswert.

Webpack ist weiterhin der Bundler – Heft orchestriert ihn nur. React funktioniert genau wie vorher. Die src/ Ordnerstruktur ist identisch, Web Parts und Extensions leben an denselben Stellen, und der config/ Ordner hat weiterhin package-solution.json, serve.json und den Rest. Das .sppkg Output hat auch dasselbe Format, also braucht deine CI/CD Pipeline nur aktualisierte Build Commands, keinen Rewrite. Die Yeoman Generator Prompts haben sich auch nicht geändert.

Wenn du SPFx kennst, kennst du auch SPFx 1.22. Das konzeptuelle Modell hat sich nicht geändert. Nur die Build-Leitungen darunter sind anders.

Häufige Stolpersteine und Troubleshooting

Ich arbeite mit 1.22 seit es draußen ist, und ein paar Sachen haben mich gestolpert. Ich hab auch gesehen, dass andere darauf reingefallen sind.

Node.js Version ist wichtig

SPFx 1.22 braucht Node.js v22 LTS. Wenn du noch auf Node 18 oder 20 bist, musst du upgraden. Ich empfehle nvm für die Verwaltung mehrerer Node-Versionen, wenn du auch ältere SPFx Projekte warten musst:

nvm install 22
nvm use 22
node --version  # sollte v22.x.x zeigen

Muskelgedächtnis: –ship vs –production

Du wirst --ship aus Gewohnheit tippen. Ich hab’s mehrmals gemacht. Es funktioniert nicht. Das Heft-Äquivalent ist --production. Wenn dein Build aussieht, als würde er nicht minifizieren oder optimieren, check dieses Flag.

Custom Gulp Tasks lassen sich nicht übertragen

Wenn du custom Tasks in deinem gulpfile.js hattest – File Copying, Code Generation, Version Stamping – müssen die migriert werden. Das Heft-Äquivalent ist entweder ein Heft Plugin oder das Heft Run Script Plugin, das dir erlaubt, beliebiges JavaScript während einer Build Phase auszuführen. Laut Microsoft solltest du deine bestehenden Anpassungen mit Config-Änderungen und etwas Code-Verschiebung migrieren können, kein kompletter Rewrite.

SCSS Module Handling

Die Heft Toolchain behandelt .scss Files standardmäßig als CSS Modules. Files die auf .global.scss enden, werden als globale Styles behandelt. Das ist eigentlich expliziter und vorhersagbarer als das alte Verhalten, aber es kann dich kalt erwischen, wenn du SCSS Files hast, die auf implizites globales Scoping angewiesen waren.

Bundle Size Unterschiede

Manche Early Adopters haben berichtet, dass .sppkg Bundle Sizes während der Beta-Phase größer waren als bei 1.21.1 Builds. Das wurde in späteren Patches behoben, aber behalte deine Bundle Sizes nach dem Upgrade im Auge und vergleiche sie mit deinen vorherigen Builds.

Der Legacy Escape Hatch

Wenn du wirklich Gulp für ein neues Projekt brauchst (vielleicht ein schneller Prototyp während du Heft lernst), unterstützt der Generator das noch:

yo @microsoft/sharepoint --use-gulp

Das scaffolded ein Projekt mit der alten Gulp-basierten Toolchain. Aber wisse, dass das temporär ist – ab SPFx 1.23 werden neue Projekte nur noch Heft als Default haben, und ab 1.24 wird die Gulp Toolchain offiziell nicht mehr unterstützt.

Solltest du bestehende Projekte jetzt upgraden?

Kommt drauf an, wo du stehst.

Für neue Projekte, nimm einfach 1.22. Es gibt keinen Grund, mit der alten Toolchain zu starten, wenn du TypeScript 5.8, null Audit-Warnungen und Heft out of the box bekommst.

Wenn du bestehende Projekte ohne custom Gulp Tasks hast, kannst du deine package.json Dependencies auf 1.22 upgraden und vorerst weiter Gulp verwenden. Dein bestehender Build bricht nicht. Plane die Heft-Migration für ein Maintenance Window, wenn du Zeit zum ordentlichen Testen hast.

Wenn du bestehende Projekte mit custom Gulp Tasks hast, würd ich warten. Schau dir an, was diese custom Tasks tatsächlich machen, prüf ob Heft Plugins oder das Run Script Plugin sie ersetzen können, und migriere Stück für Stück. Microsoft hat einen eigenen Migration Guide veröffentlicht, der durch den Prozess führt.

Die Support Timeline gibt dir Spielraum. Gulp funktioniert in 1.22 und 1.23. Es wird in 1.24 nicht mehr unterstützt. Du hast Zeit, aber ignorier es nicht.

Was das längerfristig bedeutet

Microsoft bringt die externe Developer Toolchain in Einklang mit dem, was sie intern verwenden. Das ist ein gutes Zeichen. Es bedeutet normalerweise, dass das Tooling maintained wird, anstatt vor sich hin zu rotten.

Der Heft-Umstieg macht auch Dinge möglich, die vorher mühsam waren – ordentlicher Monorepo Support, geteilte Build Configs über Projekte hinweg und ein Plugin-Ökosystem, das nicht von einem verlassenen Gulp Stack abhängt. Ich bin gespannt, wie viel davon tatsächlich in 1.23 und 1.24 kommt.

Für jetzt: installier den Generator, scaffold ein Projekt und schau dich um. Die Heft Commands werden sich eine Woche lang ungewohnt anfühlen und dann wirst du dich fragen, warum das so lang gedauert hat.

Weiterlesen

• SPFx 1.22 GA Announcement – Microsoft 365 Dev Blog – die offizielle Ankündigung zum Heft-Wechsel, TypeScript 5.8 und npm audit Verbesserungen
• SPFx 1.22 Release Notes – Microsoft Learn – vollständige Release Notes mit Breaking Changes und Feature-Details
• Heft-based Toolchain Overview – Microsoft Learn – wie Heft in die SPFx Build Pipeline passt
• Understanding the Heft-based Toolchain – Microsoft Learn – tieferer Einblick in die Heft-Anpassung für deine Projekte
• Migrate from Gulp to Heft Toolchain – Microsoft Learn – Schritt-für-Schritt Migrationsleitfaden für bestehende Projekte
• Heft Official Documentation – Rush Stack – die Upstream Heft-Docs zu Plugins, Rigs und dem vollen Config-Modell