Modern intranet architectures in Microsoft 365 rely heavily on Hub Sites. Hub Sites allow organizations to bring together related communication and team sites under a unified navigation, branding, and search scope. For developers building solutions on SharePoint, the ability to query, associate, and manage hub sites programmatically is critical.
With PnPjs, this becomes seamless. The @pnp/sp/hubsites module provides strongly-typed, fluent APIs for working with hub sites directly in your SPFx (SharePoint Framework) projects. In this article, we’ll walk through setup, key APIs, and practical use cases for hub site management.
Why Hub Sites Matter
Hub sites solve a key challenge: bringing structure to distributed content . They allow:
Centralized navigation across related sites
Unified branding (logo, theme, header)
Scoped search results across associated sites
Consistent policy and governance
For developers, hub sites are an anchor point for building portals, dashboards, and enterprise-wide solutions.
🔧 Setting Up PnPjs in SPFx
First, install PnPjs modules:
npm install @pnp/sp @pnp/sp/hubsites @pnp/sp/presets/all
Initialize PnPjs inside your SPFx web part or extension:
import { spfi, SPFx } from "@pnp/sp";
import "@pnp/sp/hubsites";
protected async onInit(): Promise<void> {
const sp = spfi().using(SPFx(this.context));
}
Now sp.hubSites , sp.site , and sp.web hub site methods are available.
Latest Hub Site APIs in PnPjs
Here’s the full set of hub site APIs you can use today with PnPjs (v3+).
1. Hub Site Collection Operations
Get all hub sites
const hubs = await sp.hubSites();
Get hub site by ID
const hub = await sp.hubSites.getById("hub-site-guid")();
Get site object for hub
const hubSite = await sp.hubSites.getById("hub-site-guid").getSite();
2. Web-Level Hub Operations
Get hub site data for current web
const hubData = await sp.web.hubSiteData();
Force refresh hub data
const hubDataRefresh = await sp.web.hubSiteData(true);
Sync hub site theme
await sp.web.syncHubSiteTheme();
3. Site-Level Hub Operations
Join current site to a hub
await sp.site.joinHubSite("hub-site-guid");
Use "00000000-0000-0000-0000-000000000000" to unjoin from any hub.
Register current site as a hub site
await sp.site.registerHubSite();
Unregister current site as a hub site
await sp.site.unRegisterHubSite();
💻 Practical Example – Hub Site Automation
Here’s a complete example combining common hub site tasks:
import { spfi, SPFx } from "@pnp/sp";
import "@pnp/sp/hubsites";
import "@pnp/sp/webs";
import "@pnp/sp/sites";
protected async onInit(): Promise<void> {
const sp = spfi().using(SPFx(this.context));
// 1. Get all hub sitesconst hubs = await sp.hubSites();
console.log("Hub Sites:", hubs);
if (hubs.length > 0) {
const hubId = hubs[0].ID;
// 2. Get hub by ID
const hub = await sp.hubSites.getById(hubId)();
console.log("Hub Details:", hub);
// 3. Get associated site object
const hubSite = await sp.hubSites.getById(hubId).getSite();
console.log("Hub Site Object:", hubSite);
// 4. Fetch hub association for current web
const hubData = await sp.web.hubSiteData();
console.log("Current Web Hub Data:", hubData);
// 5. Sync hub theme
await sp.web.syncHubSiteTheme();
console.log("Hub theme synced");
// 6. Join current site to hub
await sp.site.joinHubSite(hubId);
console.log(`Joined site to hub: ${hubId}`);
// 7. Register current site as hub
await sp.site.registerHubSite();
console.log("Site registered as hub");
// 8. Unregister hub site
await sp.site.unRegisterHubSite();
console.log("Hub site unregistered");
}
}
📊 Quick Reference Table
| Operation | API Method | Scope |
|---|
| Get all hub sites | sp.hubSites() | Tenant |
| Get hub by ID | sp.hubSites.getById(id)() | Tenant |
| Get hub’s site object | sp.hubSites.getById(id).getSite() | Tenant |
| Get web’s hub association | sp.web.hubSiteData([forceRefresh]) | Web |
| Sync hub theme | sp.web.syncHubSiteTheme() | Web |
| Join site to hub | sp.site.joinHubSite(hubId) | Site |
| Register as hub site | sp.site.registerHubSite() | Site |
| Unregister hub site | sp.site.unRegisterHubSite() | Site |
✅ Conclusion
With the latest PnPjs hub site APIs, developers can fully automate SharePoint hub lifecycle management —from registering new hubs and joining sites, to syncing themes and retrieving hub data.
If you’re building modern SPFx solutions, these APIs provide a fluent, strongly-typed, and future-proof way to interact with hub sites.