SPFx 1.23.2: atualizar não é mudar um número
A versão anterior foi retirada do npm por regressões, e isso é o aviso: o risco de atualizar a SharePoint Framework quase nunca está no runtime do SharePoint, está no build. O que mudou no Heft, no Sass e no npm audit, com o código a mostrar como era, como é, e como vai ser.
A SharePoint Framework 1.23.2 saiu a 30 de junho de 2026 como um minor bump: corrige vulnerabilidades de npm e alguns problemas reportados. Parece uma atualização de rotina, daquelas que se fazem sem pensar. Não é.
A pista está na versão anterior. A 1.23.1 chegou a ser publicada e foi retirada do npm por regressões. Numa framework madura, uma versão puxada de circulação é um aviso: o risco de atualizar o SPFx quase nunca está no runtime do SharePoint, está no build. Este artigo é sobre o que mudou, o que se partiu, e o que ainda vai partir, com o código a mostrar como era, como é, e como vai ser.
O que se parte não é o SharePoint, é o build
Um web part do SPFx corre no navegador, dentro de uma página do SharePoint, e essa parte é estável há anos. O que a Microsoft anda a mexer, e com força, é a cadeia de build: a ferramenta que compila o TypeScript, processa o Sass e empacota o .sppkg. Atualizar os pacotes do SPFx e migrar o processo de build são duas coisas relacionadas, mas não a mesma, e é a segunda que estraga builds.
Por isso a regra número um: um upgrade de SPFx não é mecânico. Não se muda o número no package.json e se espera que compile, a própria Microsoft avisa que fazê-lo dá erros de build. O que se segue são os quatro sítios onde isto morde, e o que fazer em cada um.
O Gulp está a sair
A mudança estrutural é o fim do Gulp. Até à 1.21, o Gulp orquestrava tudo. A partir da 1.22, os projetos novos passaram a usar o Heft, que continua a usar o webpack por baixo mas comandado por ele; o gulpfile.js deixou de ser compatível e o config.json desapareceu. Na 1.23, um projeto existente ainda pode continuar com Gulp. Na 1.24, o Gulp fica oficialmente sem suporte.
# 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
Ao mesmo tempo, o Yeoman está a ser substituído pelo novo @microsoft/spfx-cli, ainda em pré-lançamento, com disponibilidade geral prevista para a 1.25, em setembro. Ou seja: mexer nos pacotes e migrar o build são projetos separados. Atualiza-se primeiro para a 1.23.2, e planeia-se a migração para Heft à parte, com testes.
O Sass mudou sem aviso
A regressão que mais custa a apanhar na 1.23 é no Sass, e a própria Microsoft classifica-a como não documentada (issue #10854). Imports que funcionavam na 1.22 deixam de resolver: o prefixo ~, os bare specifiers, e o importIncludePaths deixam de funcionar. Um projeto com Sass a sério compila na 1.22 e falha na 1.23 sem uma linha de código mudada.
// 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"); }
O caminho é o esquema pkg: para importar pacotes de npm, e rever todos os meta.load-css(). Há mais no mesmo lote: os source maps de SCSS apontavam para CSS intermédio em vez do .scss original (#10831), e ficheiros .scss normais geravam tipos de CSS Module apesar de o webpack os tratar como globais (#10832). A 1.23.2 dá isto como corrigido, mas alguns issues continuam abertos no tracker: testa antes de assumir que está resolvido no teu cenário.
npm audit fix --force faz mais mal que bem
A 1.23.2 corrigiu as vulnerabilidades críticas e altas, e sobram algumas moderadas em dependências externas. A reação instintiva, correr npm audit fix --force, é a errada, e a Microsoft diz expressamente para não o fazer: reescreve pacotes transitivos que a Microsoft testou e dá um build que já não é reproduzível.
# 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
A distinção que interessa: a maioria das dependências vulneráveis é do ambiente de build, e o node_modules nunca vai dentro do .sppkg. Uma vulnerabilidade numa ferramenta local não é uma vulnerabilidade em produção no SharePoint. Antes de mexer, vê se a dependência é só de desenvolvimento, se entra no bundle final, e quem a trouxe.
Fixar versões, não @latest
A lição da 1.23.1 é esta: numa pipeline, o @latest é uma bomba com temporizador. Se o build tivesse apanhado a 1.23.1 no dia errado, tinha instalado uma versão que a Microsoft acabou por retirar. Fixam-se versões exatas, e o React instala-se exatamente como a matriz manda, com --save-exact, porque uma versão de React errada falha em silêncio, sem erro no 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.
A matriz da 1.23.2 é clara: Node v22, TypeScript até 5.8, React 17.0.1. O SPFx ainda não dá React 18, continua no roadmap. Fixar não é burocracia: é o que separa um build que se repete de um que muda debaixo dos pés entre uma máquina e a pipeline.
E a 1.24?
A 1.24 está em preview, em beta desde 8 de julho de 2026, e traz a novidade que explica para onde o SPFx vai: as SharePoint Copilot Apps. São componentes SPFx, com o mesmo empacotamento e as mesmas ferramentas, mas que renderizam dentro do canvas do Microsoft 365 Copilot, em vez de uma página do SharePoint. Um componente Copilot estende BaseCopilotComponent, não BaseClientSideWebPart, e um único .sppkg pode juntar os dois.
É preview a sério, e a Microsoft assume-o: só renderiza no canvas do Copilot, não se distribui pela Store, e o próprio nome pode mudar antes da versão final. É para laboratório, num tenant de desenvolvimento, não para produção. O sinal que interessa é a direção: o SPFx deixa de ser só do SharePoint e passa a ser a forma de pôr interface própria dentro do Copilot.
O que fica
A 1.23.2 é a versão certa para novos projetos em produção, mas não se trata como uma troca de número. O runtime do SharePoint aguenta; o que parte é a cadeia de build, os imports de Sass, as customizações Gulp que morrem na 1.24, e funcionalidades cujo rollout do lado do servidor ainda não acabou. Atualizar o SPFx é uma migração de build disfarçada de bump. Fixa as versões, testa o build, e faz a migração para Heft com um plano, não com um npm install.
