SPFx 1.23.2: actualizar no es cambiar un número
La versión anterior se retiró de npm por regresiones, y ese 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 notificados. 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 se retiró 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é está todavía por romperse, 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 cosa, 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 basta con cambiar el número en package.json y esperar que compile; la propia Microsoft avisa de que hacerlo da errores de build. Lo que sigue son los cuatro puntos donde esto duele, 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 apoyándose en webpack por debajo, pero gobernado por él; el gulpfile.js dejó de ser compatible y el config.json desapareció. En la 1.23, un proyecto ya existente todavía 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, el nuevo @microsoft/spfx-cli está sustituyendo a Yeoman, 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 dos proyectos distintos. Primero se actualiza a la 1.23.2 y luego se planifica la migración a Heft por separado, con pruebas.
Sass cambió sin aviso
La regresión más difícil de detectar 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 resolverse: el prefijo ~, los bare specifiers y el importIncludePaths dejan de funcionar. Un proyecto que use Sass en serio compila en la 1.22 y falla en la 1.23 sin haber cambiado una sola línea de código.
// 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"); }
La salida pasa por usar el esquema pkg: para importar paquetes de npm y por revisar todos los meta.load-css(). Hay más en el mismo lote: los source maps de SCSS apuntaban al CSS intermedio en lugar de al .scss original (#10831), y los archivos .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: pruébelo antes de dar por hecho que está resuelto en su 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, ejecutar npm audit fix --force, es la equivocada, y Microsoft dice expresamente que no se haga: reescribe paquetes transitivos que Microsoft ya había probado y 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 viaja dentro del .sppkg. Una vulnerabilidad en una herramienta local no es una vulnerabilidad en producción en SharePoint. Antes de tocar nada, compruebe si la dependencia es solo de desarrollo, si entra en el bundle final y quién la ha traído.
Fijar versiones, no @latest
La lección de la 1.23.1 es esta: en una pipeline, @latest es una bomba de relojería. Si el build se hubiera topado con 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 tal y como manda la matriz, con --save-exact, porque una versión equivocada de React falla en silencio, sin dar ningún 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 admite React 18, que sigue en el roadmap. Fijar versiones no es burocracia: es lo que separa un build que se reproduce de otro que cambia bajo los pies al pasar de una máquina a 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 se renderizan dentro del canvas de Microsoft 365 Copilot en lugar de en una página de SharePoint. Un componente Copilot extiende BaseCopilotComponent, no BaseClientSideWebPart, y un mismo .sppkg puede reunir los dos tipos.
Es preview de verdad, y Microsoft así lo reconoce: solo se 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 material de laboratorio, para un tenant de desarrollo, no para producción. La señal que importa es la dirección: SPFx deja de ser solo cosa 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 simple cambio de número. El runtime de SharePoint aguanta; lo que se rompe es la cadena de build, los imports de Sass, las personalizaciones de Gulp que mueren en la 1.24 y las funcionalidades cuyo rollout del lado del servidor aún no ha terminado. Actualizar SPFx es una migración de build disfrazada de bump. Fije las versiones, pruebe el build y haga la migración a Heft con un plan, no con un npm install.
