Mastering SharePoint Hub Sites with PnPjs in SPFx

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.