Tenant-wide vs site-by-site SPFx deployment
Last updated:
When you upload an .sppkg to the App Catalog, SharePoint asks whether to make the solution available to all sites in the organisation. Ticking it deploys once and the component becomes available everywhere. Leaving it unticked means someone has to add the app to each site before anyone there can use it.
The checkbox is not really yours to decide freely: it reflects skipFeatureDeployment in the package manifest, and some packages require true. Any solution with components exposed in Microsoft Teams must be tenant-scoped, for instance.
The important thing to settle first, because it is where the anxiety comes from: tenant-wide availability does not put anything on anyone's pages. It makes the web part appear in the picker for page authors. Nothing renders until someone with edit rights on a page deliberately places it.
What actually differs
| Tenant-wide | Site by site | |
|---|---|---|
| Deployment effort | Once | Per site, forever |
| Who can use it | Page authors on any site | Only sites where the app has been added |
| Appears in the web part picker | Everywhere | Only where added |
| Renders on pages by itself | No | No |
| Removing access from one site | Not directly — control it with site permissions | Remove the app from that site |
| Required for Teams-exposed components | Yes | Not possible |
| Governance model | Central: one decision, audited in one place | Distributed: every site owner decides |
The row people misread is the fourth. A tenant-wide web part is inert until placed. This is genuinely different from a tenant-wide extension (an application customizer), which does run on pages automatically — and that difference is why extensions deserve a stricter review than web parts.
Which to choose
Choose tenant-wide when
- The component is meant to be available to the organisation, not to one department.
- You do not want a ticket every time a new site wants it — which, for anything useful, is the normal outcome.
- The package exposes components in Microsoft Teams, in which case it is mandatory.
- You want one auditable record of what is deployed, rather than a per-site archaeology exercise a year from now.
Choose site by site when
- You are piloting with one department and want a hard boundary while you evaluate.
- The component is genuinely specific to one site and would only be noise in everyone else's picker.
- Your governance model requires each site owner to opt in explicitly, and you accept the ongoing cost of that.
In practice most organisations end up tenant-wide for anything that succeeds, because the per-site alternative turns every new adopter into a support request. The useful move is to pilot narrowly and then decide — not to pick site-by-site permanently to feel safer, because the safety it buys is smaller than it looks.
Controlling a tenant-wide deployment
If tenant-wide feels like losing control, these are the levers that remain — and there are more of them than people expect:
- Site permissions. Only people with edit rights on a page can place a web part. Withhold those and nothing can be added, regardless of what is deployed.
- The API permission. A component that needs an approved API permission does nothing useful until you approve it — and removing the approval disables it everywhere at once, without touching the package.
- The Tenant Wide Extensions list in the App Catalog, for extensions specifically: it is where you switch one off without deleting anything.
- Retiring the package. Deleting it from the App Catalog stops it rendering everywhere immediately.
- The vendor's own governance, where it exists. Some products let you disable an individual component centrally, which is finer-grained than anything SharePoint offers.
Changing your mind later
You can. The scope comes from the package manifest, so switching means the vendor ships a version with a different skipFeatureDeployment and you upload it. Going from site-by-site to tenant-wide is the easy direction; going the other way leaves apps already added to sites, which have to be removed individually.
That asymmetry is the practical argument for piloting site-by-site first if you are unsure: the cheap direction is outwards.
Frequently asked questions
Will a tenant-wide web part show up on our existing pages?
No. It becomes available in the web part picker for page authors. Existing pages are untouched, and nothing renders anywhere until someone with edit rights deliberately adds it to a page and publishes. Extensions behave differently — those do run automatically — which is why the two deserve different levels of scrutiny.
Can we deploy tenant-wide but hide it from most sites?
Not through the deployment itself: availability is all or nothing. In practice you control it with site permissions, since only page editors can place web parts. If you need genuine per-department isolation, site-by-site deployment is the mechanism that gives it, at the cost of ongoing administration.
Does tenant-wide deployment slow down page loads across the tenant?
For web parts, no. The code is only loaded on pages where the component is actually placed. Extensions are the exception again: a tenant-wide extension loads on every page in scope, so its bundle size is a legitimate performance question in a way a web part's is not.
What does skipFeatureDeployment mean, literally?
It tells SharePoint to skip the per-site feature activation step. When it is true, the solution is deployed once and its components are available everywhere without a site-level installation. When it is false, each site has to have the app added, which activates the feature there. The checkbox in the upload dialog is that setting, surfaced to the administrator.