SharePoint Copilot Apps: The SPFx Web Part Migration Guide

Microsoft announced SharePoint Copilot Apps on the Microsoft 365 dev blog in June 2026, with public preview landing in July alongside SPFx v1.24 and general availability planned for autumn 2026. If you own a portfolio of SPFx web parts — and most enterprise SharePoint tenants have between 20 and 200 of them — you now have a decision to make on every single one: keep, port, or rewrite.

Our team has been building SPFx solutions since the SharePoint Framework general availability in 2017 and has spent the last two months in the private preview of Copilot Apps. This is the working migration guide we now walk customers through.

What Copilot Apps actually means

SharePoint Copilot Apps are the SharePoint implementation of the MCP Apps model — the model context protocol app packaging pattern Microsoft ratified in early 2026. A Copilot App is packaged, distributed, and permissioned differently from an SPFx web part, and it runs in a fundamentally different context.

The short version:

• SPFx web part. Renders inside a SharePoint page. Runs in the user's browser. Has access to the SharePoint page context, the current user's identity, and any Graph or SharePoint APIs the app registration permits.
• SharePoint Copilot App. Registered as an MCP App. Callable from Copilot as a tool, embedded in a SharePoint page as a widget, or invoked from a Copilot Studio agent. Runs on a Microsoft-hosted app runtime. Has its own agent-scoped identity (via Agent 365 / Entra Agent Identity) and its own permission surface.

These are not the same thing. A Copilot App is not "SPFx v2." It is a different distribution model, a different hosting model, and a different permission model, all at once. The similarities are cosmetic: both can render UI, both can call Graph, both can appear on a SharePoint page.

Official announcement: Going beyond text in Microsoft 365 Copilot — introducing SharePoint Copilot Apps.

Differences at a glance

| Dimension | SPFx web part | SharePoint Copilot App |

|-----------|---------------|------------------------|

| Context | Page context + current user | Agent identity + user context passed as a parameter |

| Distribution | App catalog (tenant or site) | Microsoft 365 Copilot store + Teams admin center |

| Hosting | Static assets on your CDN, runtime in browser | Microsoft-hosted runtime, packaged bundle |

| Permissions | App registration scopes granted tenant-wide | Agent-identity-scoped, plus per-invocation user context |

| Callable from Copilot | No (unless you build a custom Copilot connector) | Yes, natively — the whole point |

| Callable from Copilot Studio agents | No | Yes, as a tool |

| Rendered on classic SharePoint page | Yes | Preview: as a widget; GA planned autumn 2026 |

| UI framework | React (typical), Fluent UI | React + Fluent UI + Adaptive Cards |

| Manifest | SPFx manifest (JSON) | MCP App manifest (JSON) + Copilot manifest (JSON) |

Migration decision matrix

Not every SPFx web part should become a Copilot App. This is the matrix we run every portfolio through:

| Web part characteristic | Recommendation |

|-------------------------|----------------|

| Presents read-only data from a single SharePoint list to a specific page audience | Keep as SPFx. Copilot App gains nothing. |

| Presents cross-tenant data (Graph, external API) and is used by Copilot users to answer questions | Port to Copilot App. Highest ROI conversion. |

| Complex form with heavy client-side validation, tied to a SharePoint list | Keep as SPFx for now. Port when GA lands and form controls mature. |

| Analytics dashboard consumed both on pages and by Copilot conversationally | Rewrite as Copilot App. The dual surface is the entire value prop. |

| Third-party integration (Salesforce, ServiceNow, Jira widget) | Rewrite as Copilot App — pair with a Federated Copilot Connector for the data. |

| Utility web part (weather, stock ticker, birthdays) | Keep as SPFx. Do not spend the migration budget here. |

| Extension surface (application customizers, field customizers, list view command sets) | Keep as SPFx. Copilot Apps do not cover extensions. |

The pattern to internalize: port the web parts where Copilot invocability changes the user experience. Keep everything else.

Code-shape example

Here is the same "recent policies from a document library" web part expressed two ways. Skim rather than read line-by-line — the point is the shape difference.

SPFx web part (abbreviated):

```typescript

export default class RecentPoliciesWebPart extends BaseClientSideWebPart {

public render(): void {

const element: React.ReactElement = React.createElement(

RecentPolicies,

{

libraryUrl: this.properties.libraryUrl,

maxItems: this.properties.maxItems,

context: this.context,

}

);

ReactDom.render(element, this.domElement);

}

}

```

SharePoint Copilot App (abbreviated):

```typescript

// mcp-app.manifest.json declares tool + widget

// runtime is Microsoft-hosted; you export handlers

export const recentPolicies = defineTool({

name: 'recent_policies',

description: 'Returns the most recent policy documents from the compliance library.',

input: z.object({

maxItems: z.number().min(1).max(50).default(10),

}),

handler: async ({ input, context }) => {

// context.agentIdentity is the Entra Agent Identity

// context.userContext is the invoking user, passed as a parameter

const items = await graph

.site(POLICY_SITE_ID)

.drive('Compliance')

.items()

.top(input.maxItems)

.orderBy('lastModifiedDateTime desc')

.get({ actAs: context.userContext });

return {

items,

renderAs: adaptiveCard(items),

};

},

});

```

Three shape differences to notice:

• The Copilot App exports a tool, not a render function. The Copilot host decides when and how to invoke it.
• The identity story is explicit — the agent identity is one thing, the user context is a parameter. This maps directly to Agent 365 governance.
• The output is dual-purpose — data plus an Adaptive Card. Same handler serves conversational Copilot and page-embedded widget.

Migration mechanics

Once you have picked a web part to migrate, the mechanics are roughly:

• Extract the data layer. Every SPFx web part has a "get data" function somewhere. That function becomes the handler.
• Refactor the render layer to Adaptive Card output. Fluent UI React still works for the widget surface but the conversational surface is Adaptive Card only.
• Rewrite the manifest. MCP App manifest plus Copilot manifest. There is no automated converter yet.
• Reissue permissions. The agent identity needs its own SharePoint and Graph permissions. The old app registration permissions do NOT transfer.
• Register with Copilot store. During preview this is tenant-only; at GA the public store opens.

Budget: our team has been averaging 3-5 developer-days per web part migration for straightforward cases, 8-12 days for cases with heavy custom UI.

Related SharePoint development

• SharePoint consulting for portfolio assessment and migration planning.
• SharePoint Copilot for the broader Copilot rollout strategy.
• SharePoint intranets for how Copilot Apps change intranet architecture.

Expert help from our SharePoint consultants

The SPFx-to-Copilot-App migration is a portfolio decision, not a per-web-part decision, and getting the decision matrix wrong is expensive both ways — porting web parts that should have stayed SPFx wastes budget, keeping web parts that should have been ported leaves user experience improvements on the table. Our SharePoint consultants run the matrix above against your full portfolio and produce a prioritized migration plan you can execute in phases. If you own more than 20 SPFx web parts and Copilot is on your 2026 roadmap, reach out and we will scope a portfolio assessment.