Introdução Técnica ao SharePoint Framework — SPFx

1. Introdução

O SharePoint Framework (SPFx) é o principal modelo de desenvolvimento client-side utilizado para criar extensões e experiências personalizadas integradas ao SharePoint e a outras superfícies do Microsoft 365.

Mais do que uma tecnologia para criação de Web Parts, o SPFx deve ser entendido como um framework de extensibilidade do Microsoft 365, fornecendo uma arquitetura controlada para executar aplicações web modernas dentro do contexto do SharePoint e, em determinados cenários, Microsoft Teams e Microsoft Viva.

A Microsoft define o SharePoint Framework como um modelo de página e Web Part que oferece suporte ao desenvolvimento client-side do SharePoint, integração com dados do SharePoint e extensão de experiências Microsoft 365.

Essa definição é importante porque posiciona o SPFx de maneira diferente das antigas abordagens de customização do SharePoint.

Historicamente, desenvolvedores SharePoint trabalharam com tecnologias como:

• SharePoint Solutions;
• Farm Solutions;
• Sandbox Solutions;
• SharePoint Add-ins;
• JavaScript Injection;
• Script Editor;
• Content Editor Web Part;
• SharePoint-hosted Add-ins;
• Provider-hosted Add-ins.

A evolução para SharePoint Online e para a experiência moderna exigiu um modelo diferente.

O código customizado não deveria executar arbitrariamente no servidor SharePoint. Em vez disso, a Microsoft precisava de um modelo no qual a aplicação fosse executada predominantemente no navegador, utilizando APIs suportadas para comunicação com os serviços Microsoft 365.

O SPFx surgiu para atender exatamente a esse modelo.

Uma representação conceitual simplificada é:

User
↓
SharePoint Modern Page
↓
SPFx Component
↓
Browser
↓
Microsoft 365 APIs
↓
SharePoint / Microsoft Graph / External APIs

Portanto, o SPFx não é uma tecnologia server-side equivalente às antigas Farm Solutions.

Ele pertence essencialmente à camada de presentation e client-side extensibility.

2. O que é SPFx?

SPFx significa:

SharePoint Framework

É um framework de desenvolvimento baseado em tecnologias web modernas que permite criar componentes personalizados capazes de executar dentro das experiências suportadas pelo Microsoft 365.

Entre os principais tipos de soluções encontramos:

• Client-side Web Parts;
• Application Customizers;
• Field Customizers;
• Command Sets;
• Adaptive Card Extensions;
• componentes reutilizáveis;
• integrações com SharePoint REST;
• integrações com Microsoft Graph;
• integrações com APIs corporativas;
• experiências integradas a Microsoft Teams e Viva.

O modelo fundamental pode ser representado como:

Microsoft 365
↓
SharePoint
↓
SPFx Runtime
↓
Custom Component
↓
JavaScript / TypeScript
↓
Browser

Isso significa que grande parte da lógica da aplicação é executada no navegador do usuário.

Essa característica influencia diretamente arquitetura, segurança, autenticação, performance e integração.

3. SPFx como modelo de extensibilidade

Uma maneira importante de compreender SPFx é não pensar inicialmente em React.

React é apenas uma das tecnologias que podem participar da implementação.

O conceito central é:

SPFx = Extensibility Framework

O framework fornece infraestrutura para que uma solução customizada participe de uma experiência Microsoft 365 suportada.

Podemos imaginar:

Microsoft 365 Platform

↓

SharePoint Framework

↓

Custom Solution

↓

User Experience

A aplicação continua sendo customizada, mas sua execução ocorre dentro de uma arquitetura reconhecida pela plataforma.

Isso diferencia SPFx de simplesmente inserir JavaScript arbitrário em uma página.

4. O papel do navegador

SPFx é fundamentalmente client-side.

Considere uma Web Part que apresenta documentos de uma biblioteca.

A arquitetura pode ser:

Browser
↓
SPFx Web Part
↓
SharePoint API
↓
Document Library
↓
JSON
↓
SPFx
↓
React Components
↓
HTML
↓
User

O servidor SharePoint não executa uma DLL customizada para gerar aquela interface.

O browser executa o código da solução e utiliza APIs para acessar os recursos necessários.

Essa mudança representa uma diferença arquitetural profunda em relação ao desenvolvimento SharePoint tradicional.

5. A stack tecnológica do SPFx

O desenvolvimento SPFx utiliza tecnologias familiares ao desenvolvimento web moderno.

Uma solução pode envolver:

É importante separar runtime de development toolchain.

Node.js, por exemplo, é utilizado durante o processo de desenvolvimento e build.

Isso não significa que o Node.js esteja executando a Web Part no SharePoint.

Uma representação mais correta seria:

Development:

Developer
↓
TypeScript / React
↓
Node.js Toolchain
↓
Build
↓
JavaScript Bundle
↓
SPFx Package

Runtime:

Browser
↓
SharePoint
↓
SPFx
↓
JavaScript Bundle

Essa distinção evita uma confusão bastante comum entre iniciantes.

6. TypeScript

TypeScript é particularmente importante no ecossistema SPFx.

Ele adiciona ao JavaScript recursos como:

• static typing;
• interfaces;
• generics;
• classes;
• type checking;
• melhor IntelliSense;
• contratos entre componentes;
• maior segurança durante refactoring.

Considere conceitualmente:

export interface IEmployee {
  id: number;
  title: string;
  email: string;
}

Agora uma função pode declarar explicitamente:

function loadEmployee(): Promise<IEmployee>

Isso fornece ao compilador informações sobre o contrato esperado.

Em soluções empresariais maiores, essa característica é extremamente valiosa.

7. React

React é frequentemente utilizado para construir a interface das Web Parts.

A ideia central é componentização.

Em vez de construir uma interface inteira como um bloco monolítico, podemos ter:

EmployeeDirectory

├── SearchBox
├── DepartmentFilter
├── EmployeeList
│ ├── EmployeeCard
│ ├── EmployeeCard
│ └── EmployeeCard
└── Pagination

Cada componente possui responsabilidades menores.

Essa abordagem facilita:

• manutenção;
• testes;
• reutilização;
• composição;
• gerenciamento de estado;
• evolução da aplicação.

Mas existe uma observação arquitetural importante:

SPFx não é React.

React pode ser utilizado dentro do SPFx.

O SPFx fornece o ambiente de extensibilidade.

React fornece um modelo para construção da interface.

8. SPFx Web Parts

A Client-side Web Part provavelmente é o tipo mais conhecido de componente SPFx.

Ela representa um componente visual inserido em uma página.

Exemplos:

Employee Directory

Project Dashboard

Document Explorer

Search Interface

News Aggregator

Corporate Links

Training Dashboard

Document Management Interface

Power BI Navigation

Application Launcher

Uma página poderia conter:

SharePoint Page

├── Text Web Part
├── Hero Web Part
├── SPFx Project Dashboard
├── Document Library Web Part
└── SPFx Employee Directory

As Web Parts SPFx participam da composição normal das páginas modernas.

9. Property Pane

Uma Web Part pode possuir propriedades configuráveis.

Por exemplo:

Employee Directory

Property Pane:

Site URL
List Name
Page Size
Department
Show Pictures
Sort Order
Display Mode

Isso cria uma separação importante entre:

Developer configuration

e

Content author configuration

O desenvolvedor cria a capacidade.

O autor da página configura seu comportamento.

Conceitualmente:

Developer
↓
Creates Web Part
↓
Defines Properties
↓
Deploys

Site Owner
↓
Adds Web Part
↓
Configures Property Pane

User
↓
Consumes Experience

Essa separação torna a mesma Web Part reutilizável em diferentes páginas e contextos.

10. Extensions

SPFx não se limita a Web Parts.

As Extensions permitem modificar determinadas experiências da interface SharePoint.

Três categorias tradicionais são especialmente importantes:

Application Customizer

Permite adicionar comportamento e conteúdo em áreas da aplicação.

Um cenário clássico é trabalhar com placeholders como:

Top

Bottom

Pode ser utilizado, por exemplo, para experiências corporativas globais, mensagens, navegação complementar ou integrações específicas.

Field Customizer

Permite customizar visualmente a apresentação de um campo.

Imagine uma coluna:

Status

Valores:

Approved
Pending
Rejected

Um Field Customizer pode transformar esses valores em uma experiência visual mais rica.

ListView Command Set

Permite adicionar comandos à experiência de listas e bibliotecas.

Por exemplo:

Documents

New
Upload
Download
Share
Send for Approval

O último comando poderia ser fornecido por uma extensão SPFx.

11. SPFx e SharePoint REST API

Uma das utilizações mais comuns do SPFx é acessar informações armazenadas no próprio SharePoint.

Por exemplo:

SPFx
↓
SharePoint REST API
↓
Site
↓
List
↓
Items

Um endpoint conceitual poderia acessar:

/_api/web/lists/getbytitle('Projects')/items

A resposta retorna dados estruturados que podem ser processados pela aplicação.

Essa arquitetura permite implementar aplicações completas sobre listas e bibliotecas SharePoint.

12. SPFx e PnPjs

PnPjs tornou-se extremamente popular em projetos SPFx porque fornece abstrações TypeScript/JavaScript convenientes para trabalhar com APIs Microsoft 365.

Em vez de trabalhar constantemente com chamadas HTTP de baixo nível, podemos utilizar uma API orientada ao domínio SharePoint.

Conceitualmente:

SPFx Component
↓
PnPjs
↓
SharePoint API
↓
SharePoint Online

Um padrão conceitual é:

const items = await sp.web.lists
  .getByTitle("Projects")
  .items();

Isso torna o código bastante legível.

Em projetos maiores, podemos separar ainda mais:

React Component
↓
Service Layer
↓
PnPjs
↓
SharePoint API

Por exemplo:

ProjectDashboard.tsx
↓
ProjectService.ts
↓
PnPjs
↓
Projects List

Essa separação reduz o acoplamento entre UI e acesso aos dados.

13. SPFx e Microsoft Graph

Nem toda informação necessária para uma aplicação está armazenada no SharePoint.

O Microsoft Graph fornece uma superfície unificada de APIs para diversos recursos Microsoft 365.

Dependendo do cenário e das permissões disponíveis, uma solução pode trabalhar com informações relacionadas a:

• users;
• groups;
• sites;
• files;
• Teams;
• calendars;
• mail;
• organizational information;
• outros recursos Microsoft 365.

A arquitetura passa a ser:

SPFx
↓
Microsoft Graph
↓
Microsoft 365 Services

Uma solução pode inclusive combinar múltiplas fontes:

SPFx Dashboard

├── SharePoint REST → Projects
├── Microsoft Graph → Users
├── Corporate API → ERP
└── Azure API → External Service

Nesse ponto, SPFx deixa claramente de ser apenas uma tecnologia para “customizar SharePoint”.

Ele funciona como uma camada de experiência integrada ao ecossistema Microsoft 365.

14. Autenticação e contexto do usuário

Um aspecto extremamente importante do SPFx é que a solução normalmente é executada dentro de um contexto Microsoft 365 autenticado.

Isso permite integrar a aplicação com recursos protegidos sem desenvolver um mecanismo de login independente para cada Web Part.

Mas isso não significa que uma Web Part possa acessar qualquer informação.

Devemos distinguir:

Authentication

Quem é o usuário?

de:

Authorization

O que esse usuário pode acessar?

Uma arquitetura segura precisa considerar:

User
↓
Microsoft 365 Authentication
↓
SPFx
↓
API
↓
Authorization Check
↓
Resource

Se o usuário não possui acesso a determinado documento SharePoint, uma Web Part não deveria ser concebida como mecanismo para contornar essa autorização.

Da mesma forma, chamadas Microsoft Graph podem depender de permissões específicas concedidas à solução e ao contexto utilizado.

15. SPFx e segurança

Uma característica arquitetural essencial do SPFx é que grande parte do código é entregue ao navegador.

Portanto, nunca devemos tratar código client-side como local seguro para armazenar secrets.

Isso significa que não devemos simplesmente colocar dentro do bundle:

API passwords

Client secrets

Database passwords

Permanent API tokens

Private keys

O browser não é um cofre.

Conceitualmente:

SPFx
↓
Browser
↓
User can inspect client resources

Portanto, integrações que dependem de segredos normalmente exigem uma arquitetura intermediária.

Por exemplo:

SPFx
↓
Secure API
↓
Authentication / Authorization
↓
Secret Store / Managed Identity
↓
External System

Essa API intermediária poderia ser implementada utilizando tecnologias como Azure Functions ou outro backend adequadamente protegido.

16. Deployment

Depois do desenvolvimento, a solução SPFx é empacotada.

O artefato tradicional é:

.sppkg

Conceitualmente:

Source Code
↓
Build
↓
Bundle
↓
Package
↓
.sppkg
↓
App Catalog
↓
Deployment
↓
SharePoint Sites

O App Catalog desempenha papel central na distribuição de soluções SPFx.

Essa arquitetura permite que administradores controlem quais soluções são disponibilizadas ao ambiente.

17. Tenant App Catalog

Em ambientes corporativos, uma solução pode ser disponibilizada através do App Catalog apropriado.

Isso introduz uma separação importante:

Developer cria

↓

Package é produzido

↓

Administrator / deployment process controla distribuição

↓

Solution becomes available

↓

Site consumes component

Isso é importante para governança.

Não queremos que cada desenvolvedor simplesmente injete JavaScript arbitrário em produção.

SPFx fornece um modelo mais administrável para extensibilidade.

18. SPFx e ALM

Em organizações maduras, uma solução SPFx deveria participar de um processo de Application Lifecycle Management.

Por exemplo:

Development

↓

Git Repository

↓

Pull Request

↓

Build

↓

Automated Tests

↓

Package

↓

DEV

↓

TEST

↓

UAT

↓

PROD

Isso aproxima o desenvolvimento SharePoint de práticas tradicionais de engenharia de software.

Podemos adicionar:

• source control;
• branching strategy;
• code review;
• CI/CD;
• automated builds;
• versioning;
• dependency management;
• release management;
• rollback strategy.

19. SPFx como aplicação corporativa

Uma Web Part pode começar pequena:

“Mostrar cinco documentos.”

Mas pode evoluir para uma aplicação significativamente maior:

Project Management Portal

↓

SPFx Application

├── Project Dashboard
├── Search
├── Documents
├── Tasks
├── Team Members
├── Reports
├── Notifications
└── Administration

Dados:

├── SharePoint Lists
├── Document Libraries
├── Microsoft Graph
├── Power Automate
└── External APIs

Nesse cenário, SPFx está atuando como a presentation layer de uma aplicação corporativa.

20. Arquitetura em camadas

Para aplicações maiores, é recomendável evitar colocar tudo diretamente dentro do componente React.

Uma arquitetura mais organizada poderia ser:

Presentation Layer

React Components

↓

Application Layer

Business Logic

↓

Service Layer

SharePointService
GraphService
ApiService

↓

Integration Layer

PnPjs
Microsoft Graph
REST APIs

↓

Data / Services

SharePoint
Microsoft 365
External Systems

Isso permite que cada camada tenha responsabilidades mais claras.

21. Exemplo arquitetural

Imagine um Project Management Dashboard.

O usuário abre uma página SharePoint.

A página carrega uma Web Part SPFx.

A Web Part consulta uma lista Projects.

Depois consulta usuários responsáveis pelos projetos.

Finalmente apresenta os resultados em uma interface React.

Arquitetura:

User

↓

SharePoint Online

↓

Modern Page

↓

SPFx Project Dashboard

↓

React

↓

Service Layer

↓

┌────────────────────────────┐
│ PnPjs │
│ Microsoft Graph Client │
│ Corporate REST Client │
└────────────────────────────┘

↓

┌────────────────────────────┐
│ SharePoint Lists │
│ Microsoft Graph │
│ Corporate API │
└────────────────────────────┘

↓

Structured Data

↓

React State

↓

Components

↓

User Interface

Esse é um modelo bastante representativo de aplicações SPFx modernas.

22. SPFx e Power Automate

SPFx também pode participar de soluções que utilizam Power Automate.

Mas devemos manter responsabilidades claras.

SPFx é especialmente adequado para:

User Experience

Power Automate é especialmente adequado para:

Workflow / Automation

Imagine:

User
↓
SPFx Form
↓
SharePoint List
↓
Power Automate
↓
Approval
↓
Teams / Outlook
↓
SharePoint Update

A Web Part oferece uma experiência especializada.

SharePoint armazena os dados.

Power Automate executa o processo.

Essa composição costuma ser mais sustentável do que tentar colocar toda a lógica do processo no JavaScript da Web Part.

23. SPFx e Power Apps

Outra decisão arquitetural frequente é:

SPFx ou Power Apps?

Não existe uma resposta universal.

Power Apps pode ser excelente quando queremos desenvolver rapidamente uma aplicação de negócio low-code profundamente integrada à Power Platform.

SPFx pode ser melhor quando precisamos de:

• experiência profundamente integrada ao SharePoint;
• controle detalhado da interface;
• TypeScript;
• React;
• bibliotecas JavaScript;
• componentes reutilizáveis;
• comportamento client-side avançado;
• integração customizada;
• desenvolvimento pro-code.

Em algumas arquiteturas, ambas as tecnologias podem coexistir.

24. SPFx e Copilot/Agents

Com a expansão de Copilot e Agents, tornou-se ainda mais importante entender onde SPFx se encaixa.

Uma simplificação útil é:

SPFx = Experience

Agent = Reasoning / Conversation

Knowledge = Information

Action = Operation

Power Automate = Workflow

SharePoint = Content / Collaboration / Data

Por exemplo:

Employee
↓
SharePoint Portal
↓
SPFx Experience
↓
Copilot/Agent
↓
Knowledge
↓
SharePoint Documentation

Enquanto outro caminho pode ser:

Agent
↓
Action
↓
Power Automate
↓
SharePoint List

SPFx não precisa competir com Agents.

Eles pertencem a responsabilidades arquiteturais diferentes e podem participar da mesma solução.

Dentro da nossa abordagem de arquitetura Microsoft 365, isso é particularmente importante: Agents não devem ser tratados como substitutos automáticos de SPFx, Power Apps ou Power Automate. A decisão deve considerar qual tecnologia resolve cada responsabilidade da forma mais simples, segura e previsível.

25. Quando usar SPFx

SPFx é particularmente apropriado quando precisamos de uma experiência customizada profundamente integrada ao SharePoint ou Microsoft 365.

Exemplos:

Document Management Dashboard

Corporate Search Experience

Employee Directory

Project Management Dashboard

Metadata Management Interface

Custom Navigation

Document Approval Interface

Administrative Dashboard

Corporate Portal Components

Microsoft Graph Dashboard

External System Integration

A pergunta arquitetural deveria ser:

Existe uma necessidade real de uma experiência customizada pro-code integrada ao Microsoft 365?

Se sim, SPFx deve ser considerado.

26. Quando NÃO usar SPFx

Nem todo problema SharePoint exige SPFx.

Se o requisito é simplesmente:

“Adicionar uma coluna.”

Use SharePoint.

Se for:

“Quando um item for criado, enviar um email.”

Provavelmente Power Automate.

Se for:

“Criar rapidamente um formulário empresarial customizado.”

Talvez Power Apps.

Se for:

“Responder perguntas sobre políticas corporativas.”

Talvez um Agent baseado em Knowledge.

Se for:

“Criar uma interface sofisticada de gestão documental integrada ao SharePoint.”

SPFx passa a ser uma alternativa muito mais natural.

Essa capacidade de não utilizar SPFx quando ele não é necessário também faz parte de uma boa arquitetura.

27. SPFx no cenário atual

SPFx continua sendo uma tecnologia estratégica para extensibilidade do Microsoft 365.

A Microsoft documenta explicitamente que a descontinuação do SharePoint Add-in model no SharePoint Online não afeta o SharePoint Framework. Pelo contrário, o SPFx é apresentado como a principal tecnologia substituta para SharePoint Add-ins e continua suportado como modelo de extensibilidade.

Também existe integração do SPFx com experiências além do SharePoint, incluindo Microsoft Teams e Microsoft Viva. Portanto, enxergar SPFx apenas como “framework para Web Parts do SharePoint” é uma visão limitada de sua função atual.

28. Toolchain atual e versionamento

Existe um aspecto do SPFx que merece atenção especial: a versão do framework determina as versões compatíveis de diversas ferramentas e bibliotecas.

Não é seguro simplesmente instalar a versão mais recente de Node.js, React ou TypeScript e assumir que funcionará.

A matriz oficial de compatibilidade deve ser consultada.

Em setembro de 2026, por exemplo, a documentação Microsoft lista para SPFx 1.23.x:

A Microsoft inclusive alerta que versões incompatíveis de React podem produzir falhas de runtime difíceis de diagnosticar.

Existe também SPFx 1.24 em preview, trazendo, entre outras mudanças, suporte a React 18. Por ser uma versão pré-release, a própria Microsoft recomenda utilizar para produção a versão indicada pela documentação oficial de configuração do ambiente.

Portanto, uma regra prática importante é:

Nunca escolha a toolchain SPFx por memória. Consulte a compatibility matrix da versão utilizada.

29. SharePoint Online vs SharePoint Server

Também precisamos distinguir SharePoint Online de SharePoint Server.

SharePoint Online evolui continuamente e suporta as versões modernas do SPFx.

As versões on-premises possuem limitações específicas.

A documentação atual indica, por exemplo:

Isso possui consequências arquiteturais enormes.

Uma solução criada utilizando recursos modernos de SPFx para SharePoint Online não deve ser automaticamente considerada compatível com SharePoint Server.

30. Modelo mental do SPFx

Uma maneira simples de memorizar o framework é:

SPFx = experiência pro-code executada predominantemente no browser e integrada ao contexto Microsoft 365.

Podemos expandir:

User

↓

Microsoft 365

↓

SharePoint / Teams / Viva

↓

SPFx

↓

TypeScript

↓

React / UI

↓

Services

↓

┌─────────────────────────────┐
│ SharePoint REST │
│ PnPjs │
│ Microsoft Graph │
│ Corporate APIs │
└─────────────────────────────┘

↓

Enterprise Data & Services

Isso posiciona SPFx dentro da arquitetura Microsoft 365 sem transformá-lo em uma tecnologia que precisa resolver todas as camadas.

31. Tabela técnica do SPFx

32. Tabela de responsabilidades arquiteturais

33. Tabela comparativa resumida

34. Resumo técnico final

Conclusão

O SharePoint Framework representa a evolução do desenvolvimento customizado do SharePoint para uma arquitetura alinhada ao desenvolvimento web moderno e ao modelo cloud do Microsoft 365.

Seu valor não está apenas na possibilidade de criar Web Parts.

SPFx fornece uma camada de extensibilidade pro-code capaz de conectar experiência, dados e serviços dentro do Microsoft 365.

Uma arquitetura moderna pode combinar:

SharePoint

SPFx

PnPjs

Microsoft Graph

Power Automate

External APIs

Copilot Studio / Agents

Cada componente possui uma responsabilidade diferente.

O SPFx é particularmente forte quando precisamos controlar a experiência digital apresentada ao usuário.

SharePoint fornece conteúdo, colaboração e dados.

Power Automate fornece automação determinística.

Microsoft Graph fornece acesso programático ao Microsoft 365.

Copilot Studio e Agents introduzem raciocínio, conversação, Knowledge, orchestration e Actions.

Essa separação de responsabilidades é essencial.

A pergunta arquitetural moderna deixou de ser simplesmente:

“Como customizo o SharePoint?”

Ela passou a ser:

“Qual componente do ecossistema Microsoft 365 deve assumir cada responsabilidade desta solução?”

Nesse modelo, SPFx continua ocupando uma posição extremamente importante: ele é uma das principais tecnologias disponíveis quando a resposta para determinada responsabilidade é:

precisamos construir uma experiência Microsoft 365 customizada, integrada e profissional utilizando desenvolvimento pro-code.