Porque é que o SharePoint Framework continua a correr em React 17

Catorze versões seguidas do SharePoint Framework saíram com o React 17.0.1. Catorze.

Parece estagnação. Não é, e é apenas raramente discutido de outra forma.

Os factos primeiro

A Microsoft publica uma tabela de compatibilidade para cada versão do SPFx. Isto é o que ela diz sobre o React, consultada a 5 de agosto de 2026 (compatibilidade de plataforma e toolchain do SPFx):

Três versões maiores do React em dez anos de SPFx, e a atual aguenta-se há catorze versões seguidas. A versão que a mudou tem data e é explícita: SPFx 1.16.0, lançada a 15 de novembro de 2022, "o SPFx passa a funcionar com o React 17 por omissão" (notas da versão 1.16.0).

Uma comparação torna isto mais nítido. O React 18 saiu em março de 2022, oito meses antes. A Microsoft não escolheu a versão mais recente e depois ficou para trás. Lançou uma versão que já estava uma geração atrasada no dia em que chegou.

Seja isto o que for, nunca foi uma aposta na novidade.

Sabemos o que custa mudar de versão maior do React, porque já aconteceu

A pergunta óbvia é porque é que demora tanto. A resposta está nas notas da versão da última vez que aconteceu.

A SPFx 1.16.0 é a versão que passou o SharePoint do React 16 para o React 17. Durante essa transição, a Microsoft corrigiu problemas que incluem:

• extensões de lista a falhar por incompatibilidade de versão do React (#8482)
• erros de invalid hook call em web parts (#8487)
• o painel de propriedades a não aparecer (#8496)
• um erro minificado do React, o #321 (#8510)

São as notas de versão da própria Microsoft. Não é uma queixa de fórum nem uma anedota.

Mudar uma versão maior do React partiu código de clientes em produção, e as correções saíram ao lado da alteração que as causou.

A frase que muda a história

O roadmap do SPFx lista versões datadas até setembro de 2026. O React 18 não está em nenhuma delas. Está numa secção à parte chamada Top of Mind, sem versão e sem data, com este texto (roadmap do SPFx, consultado a 5 de agosto de 2026):

"Suporte do React 18 para soluções SPFx. Esta atualização depende da atualização das web parts e experiências fornecidas pela Microsoft para a versão React 18. Este trabalho está em curso."

Leia a dependência outra vez, porque ela corre no sentido contrário ao que se costuma assumir.

Não são os clientes que esperam que a Microsoft termine uma atualização de framework. É a Microsoft que não pode oferecer a atualização enquanto as suas próprias web parts não se mexerem.

A superfície da própria Microsoft é o bloqueio.

Qualquer organização com uma web part à medida está a jusante de uma migração interna que não vê, não influencia e não agenda.

Lido em conjunto com a secção anterior, o quadro fica claro. Se passar do 16 para o 17 partiu extensões de lista, painéis de propriedades e hooks em produção, a ausência de data no 17 para o 18 deixa de parecer desleixo e passa a parecer uma estimativa correta.

Isto não é sobre o npm

Visto de fora, isto parece uma atualização de dependência. Não é.

O que tem mesmo de se aguentar no momento em que o React muda:

• as web parts da própria Microsoft, que renderizam em centenas de milhões de páginas que ninguém vai testar uma a uma;
• o Fluent UI, que os projetos SPFx usam na v8 desde a 1.18 (usar o Fluent UI no SPFx);
• todas as soluções de clientes alguma vez instaladas, construídas contra um contrato de runtime que era verdade quando foram feitas;
• o próprio runtime, onde o código da Microsoft e o seu partilham uma página e uma instância do React.

Este último ponto é o problema todo. Uma página de SharePoint não é uma aplicação com um dono. É um runtime partilhado onde o código da Microsoft e o seu correm lado a lado, e uma versão maior do React não é um detalhe de implementação privado quando as duas metades têm de concordar sobre ela.

O React 17 já não é apenas uma versão de framework no SharePoint. Passou a ser uma dependência de plataforma. As dependências de plataforma não se movem quando uma das partes está pronta. Movem-se quando todas estão.

Porque é que isto lhe diz respeito fora da Microsoft

Tudo o que está acima descreve o desafio da Microsoft. Esta parte é a sua.

A restrição não fica dentro da plataforma. Aterra no seu repositório, na versão que instala, e no que a sua web part faz numa página que não controla.

O modo de falha é o silêncio

A página de compatibilidade da Microsoft traz este aviso:

"Usar versões incompatíveis do React pode causar falhas silenciosas em runtime, sem mensagens de erro claras durante o processo de compilação."

E recomenda fixar a versão exata:

npm install react@17.0.1 react-dom@17.0.1 --save-exact

Silenciosas é a palavra que interessa. Uma solução construída sobre o React 18 compila. Corre localmente. Passa na revisão. E depois renderiza uma área em branco em produção, sem nada na consola que o explique.

Não há erro para procurar, porque não há erro nenhum. Se levar uma única instrução deste artigo: fixe exatamente a versão do React que a sua versão do SPFx indica, e confirme-o em revisão. Não porque um React mais recente seja pior, mas porque o runtime para onde está a instalar já decidiu.

O que a IA muda aqui, que é menos do que parece

Um agente escreve a sua web part em segundos. Escreve o JSX, as propriedades, os hooks e os testes, e escreve-os bem.

Nada disso é a restrição. A restrição é que uma página tem de carregar código da Microsoft e código de terceiros no mesmo runtime e os dois têm de funcionar. Nenhuma quantidade de código gerado torna um ecossistema compatível consigo próprio, porque compatibilidade não é um problema de escrita de código. É um acordo entre partes que lançam em calendários diferentes, e uma delas tem centenas de milhões de utilizadores que nunca acordaram nada.

A IA escreve componentes. As plataformas continuam a ter de concordar sobre o runtime.

O que não sabemos

Preferimos um "não sabemos" explícito a um palpite confiante que estará errado daqui a seis meses.

• Quando chega o React 18. A Microsoft diz que o trabalho está em curso e não dá data. À data em que isto se escreve, o roadmap oficial do SharePoint Framework não associa o suporte do React 18 a nenhuma versão do SPFx lançada ou agendada.
• Se o próximo passo é sequer o React 18. O React continuou a evoluir desde o 17. Saltar uma versão é uma estratégia legítima, e a Microsoft não disse nada em nenhum dos sentidos. A pergunta interessante não é o que o React lançou a seguir, mas o que tem de mudar antes de o SharePoint Framework poder acompanhar.
• Quanto do Microsoft 365 já está migrado. "Em curso" é toda a informação pública.

A pergunta que está por baixo

A pergunta nunca foi porque é que a Microsoft continua a usar o React 17.

O problema da Microsoft não é atualizar o React. O problema da Microsoft é atualizar um ecossistema: uma superfície própria, uma biblioteca de componentes, um runtime partilhado, e todas as soluções que qualquer cliente alguma vez instalou, e todos eles têm de concordar no mesmo dia.

Muitas organizações descobrem que têm exatamente o mesmo problema. A dependência é outra, o runtime é mais pequeno e o público mede-se em milhares em vez de centenas de milhões, mas a forma é idêntica. Alguma coisa fundamental precisa de mudar, e a resposta a "o que é que isso parte" não está escrita em lado nenhum.

Se a uma organização com os recursos da Microsoft isto leva mais de quatro anos, vale a pena perguntar o que teria de se mexer, e quem teria de concordar, antes de conseguir mudar uma dependência fundamental no seu próprio património.

A maioria das organizações nunca contou. É essa, normalmente, a resposta.

Porque é que este artigo deve envelhecer. Contamos que o SharePoint Framework venha a aceitar uma versão mais recente do React. Quando isso acontecer, este artigo deixa de ser sobre o React 17 e continua a ser sobre outra coisa: porque é que as dependências de plataforma se movem mais devagar do que as dependências de uma aplicação, e porque é que isso é uma propriedade da plataforma e não uma falha de quem a mantém.

Se este tipo de análise de engenharia lhe é útil, o SharePoint Migration Field Guide segue a mesma abordagem: primeiro as decisões, depois a documentação, marketing nunca. Escrito em inglês.