SPFx 1.23.2: actualizar no es cambiar un número
La versión anterior fue retirada de npm por regresiones, y eso es el aviso: el riesgo de actualizar SharePoint Framework casi nunca está en el runtime de SharePoint, está en el build. Qué cambió en Heft, en Sass y en npm audit, con el código mostrando cómo era, cómo es, y cómo va a ser.
SharePoint Framework 1.23.2 salió el 30 de junio de 2026 como un minor bump: corrige vulnerabilidades de npm y algunos problemas reportados. Parece una actualización de rutina, de esas que se hacen sin pensar. No lo es.
La pista está en la versión anterior. La 1.23.1 llegó a publicarse y fue retirada de npm por regresiones. En un framework maduro, una versión sacada de circulación es un aviso: el riesgo de actualizar SPFx casi nunca está en el runtime de SharePoint, está en el build. Este artículo trata de qué cambió, qué se rompió, y qué todavía se va a romper, con el código mostrando cómo era, cómo es, y cómo va a ser.
Lo que se rompe no es SharePoint, es el build
Un web part de SPFx corre en el navegador, dentro de una página de SharePoint, y esa parte lleva años estable. Lo que Microsoft está moviendo, y con fuerza, es la cadena de build: la herramienta que compila el TypeScript, procesa el Sass y empaqueta el .sppkg. Actualizar los paquetes de SPFx y migrar el proceso de build son dos cosas relacionadas, pero no la misma, y es la segunda la que rompe builds.
De ahí la regla número uno: una actualización de SPFx no es mecánica. No se cambia el número en package.json y se espera que compile, la propia Microsoft avisa de que hacerlo da errores de build. Lo que sigue son los cuatro sitios donde esto muerde, y qué hacer en cada uno.
Gulp se está yendo
El cambio estructural es el fin de Gulp. Hasta la 1.21, Gulp lo orquestaba todo. A partir de la 1.22, los proyectos nuevos pasaron a usar Heft, que sigue usando webpack por debajo pero comandado por él; el gulpfile.js dejó de ser compatible y el config.json desapareció. En la 1.23, un proyecto existente aún puede seguir con Gulp. En la 1.24, Gulp queda oficialmente sin soporte.
# WAS (SPFx 1.21 and earlier): Gulp orchestrated the whole build.
gulp bundle --ship
gulp package-solution --ship
# IS (SPFx 1.22-1.23): Heft orchestrates webpack. gulpfile.js and config.json
# are gone; the commands are plain npm scripts.
npm run build
npm run package
# WILL BE (SPFx 1.24): the Gulp toolchain is officially unsupported, and the
# Yeoman generator gives way to the new SPFx CLI.
npm install -g @microsoft/spfx-cli
Al mismo tiempo, Yeoman está siendo reemplazado por el nuevo @microsoft/spfx-cli, todavía en pre-lanzamiento, con disponibilidad general prevista para la 1.25, en septiembre. Es decir: tocar los paquetes y migrar el build son proyectos separados. Se actualiza primero a la 1.23.2, y se planifica la migración a Heft aparte, con pruebas.
Sass cambió sin aviso
La regresión que más cuesta pillar en la 1.23 está en Sass, y la propia Microsoft la clasifica como no documentada (issue #10854). Imports que funcionaban en la 1.22 dejan de resolver: el prefijo ~, los bare specifiers, y el importIncludePaths dejan de funcionar. Un proyecto con Sass en serio compila en la 1.22 y falla en la 1.23 sin una línea de código cambiada.
// WAS (worked in SPFx 1.22): the webpack tilde and importIncludePaths.
@use "~@scope/package/styles";
@use "sass:meta";
.card { @include meta.load-css("~@scope/package/styles"); }
// IS (SPFx 1.23, issue #10854): the tilde and bare specifiers stop resolving,
// and importIncludePaths is gone. Import npm packages with the pkg: scheme.
@use "pkg:@scope/package/styles";
@use "sass:meta";
.card { @include meta.load-css("pkg:@scope/package/styles"); }
El camino es el esquema pkg: para importar paquetes de npm, y revisar todos los meta.load-css(). Hay más en el mismo lote: los source maps de SCSS apuntaban a CSS intermedio en vez del .scss original (#10831), y ficheros .scss normales generaban tipos de CSS Module aunque webpack los tratara como globales (#10832). La 1.23.2 da esto por corregido, pero algunos issues siguen abiertos en el tracker: prueba antes de asumir que está resuelto en tu escenario.
npm audit fix --force hace más mal que bien
La 1.23.2 corrigió las vulnerabilidades críticas y altas, y quedan algunas moderadas en dependencias externas. La reacción instintiva, correr npm audit fix --force, es la equivocada, y Microsoft dice expresamente que no lo hagas: reescribe paquetes transitivos que Microsoft probó y te deja un build que ya no es reproducible.
# WAS (the footgun Microsoft tells you not to pull): rewrites the transitive
# packages Microsoft tested, and leaves you a build that no longer reproduces.
npm audit fix --force
# IS (look before you touch): most vulnerable packages are build-time only, and
# node_modules never ships inside the .sppkg.
npm audit --omit=dev
npm ls the-flagged-package
npm explain the-flagged-package
La distinción que importa: la mayoría de las dependencias vulnerables son del entorno de build, y el node_modules nunca va dentro del .sppkg. Una vulnerabilidad en una herramienta local no es una vulnerabilidad en producción en SharePoint. Antes de tocar nada, mira si la dependencia es solo de desarrollo, si entra en el bundle final, y quién la trajo.
Fijar versiones, no @latest
La lección de la 1.23.1 es esta: en una pipeline, @latest es una bomba con temporizador. Si el build hubiera pillado la 1.23.1 el día equivocado, habría instalado una versión que Microsoft acabó retirando. Se fijan versiones exactas, y React se instala exactamente como manda la matriz, con --save-exact, porque una versión de React equivocada falla en silencio, sin error en el build.
# The 1.23.1 lesson: it was delisted from npm for regressions. In a pipeline,
# @latest is a time bomb. Pin exact versions.
npm install react@17.0.1 react-dom@17.0.1 --save-exact
# SPFx 1.23.2 matrix: Node v22, TypeScript up to 5.8, React 17.0.1. Not 18 yet.
La matriz de la 1.23.2 es clara: Node v22, TypeScript hasta 5.8, React 17.0.1. SPFx todavía no da React 18, sigue en el roadmap. Fijar no es burocracia: es lo que separa un build que se repite de uno que cambia bajo los pies entre una máquina y la pipeline.
¿Y la 1.24?
La 1.24 está en preview, en beta desde el 8 de julio de 2026, y trae la novedad que explica hacia dónde va SPFx: las SharePoint Copilot Apps. Son componentes SPFx, con el mismo empaquetado y las mismas herramientas, pero que renderizan dentro del canvas de Microsoft 365 Copilot, en vez de una página de SharePoint. Un componente Copilot extiende BaseCopilotComponent, no BaseClientSideWebPart, y un solo .sppkg puede juntar los dos.
Es preview de verdad, y Microsoft lo asume: solo renderiza en el canvas de Copilot, no se distribuye por la Store, y el propio nombre puede cambiar antes de la versión final. Es para laboratorio, en un tenant de desarrollo, no para producción. La señal que importa es la dirección: SPFx deja de ser solo de SharePoint y pasa a ser la forma de poner interfaz propia dentro de Copilot.
Lo que queda
La 1.23.2 es la versión correcta para nuevos proyectos en producción, pero no se trata como un cambio de número. El runtime de SharePoint aguanta; lo que se rompe es la cadena de build, los imports de Sass, las customizaciones Gulp que mueren en la 1.24, y funcionalidades cuyo rollout del lado del servidor aún no ha terminado. Actualizar SPFx es una migración de build disfrazada de bump. Fija las versiones, prueba el build, y haz la migración a Heft con un plan, no con un npm install.
