Enable PnP webparts in SharePoint Online: app catalog, deployment, and permissions

How can you activate PnP Webparts in SharePoint Online without accidentally releasing the package across the entire tenant or granting unnecessary API permissions? Three separate decisions are critical: which App Catalog will store the SPFx package, which sites will receive the deployment, and which optional Microsoft Graph permissions are actually required.

For a controlled start, test the package first in a test site or a site collection App Catalog. Only after testing Webparts, permissions, search results, and update behavior should you proceed with deployment to production sites.

What PnP modern search brings as an spfx package

PnP Modern Search is delivered as a SharePoint Framework solution. The downloaded package typically carries the name pnp-modern-search-parts-v4.sppkg and includes several combinable Webparts, including:

• Search Box for entering search terms
• Search Results for displaying hits
• Search Filters for filters and refinements
• Search Verticals for different search areas

Deploying the package does not configure a finished search page. It initially ensures only that the Webparts become available in the designated sites. Search queries, result layouts, filters, managed properties, and connections between Webparts are then set up on the respective pages.

How a request works technically

The Webparts run as client-side SPFx components in the browser. They use the context of the logged-in user and access SharePoint Search, Microsoft Search, or Microsoft Graph depending on the configuration.

This means specifically: The Webparts bypass no existing content permissions. A user receives only hits and details they can access without the individual search page. The deployment extends the interface, not the access rights to documents, lists, or sites.

Optional API permissions

The package can request additional Microsoft Graph permissions. These are used, for example, for person information, availability status, Microsoft Search bookmarks, or Graph-based file and person searches.

The requested permissions are not automatically required for every search page. If they are not approved, the basic Webparts remain generally available, while individual additional features may be limited.

Therefore, check before approval:

• Which functions in the planned search solution are actually used
• Which permissions the specific downloaded package version requests
• Whether particularly broad areas such as organization-wide file or user access are needed
• Who assumes business and technical responsibility for these approvals

Prerequisites before activating PnP webparts

Before activating the PnP Webparts in SharePoint Online, the following prerequisites should be met:

• A tenant App Catalog exists.
• The desired deployment strategy has been defined.
• A separate test or pilot site is available.
• The current package file comes from the official release area of the project.
• The previous production package version has been backed up for a possible rollback.
• The required administrator roles are available.
• At least one modern SharePoint page is available for the functional test.

Also note the downloaded version, the download date, and the associated release notes. The filename alone is often not enough for later version assignment.

Tenant app catalog or site collection app catalog?

Both App Catalog variants can accept SPFx packages. The difference lies in the scope of validity and thus in the possible impact of a change.

Criterion: Scope of validity

Tenant App Catalog: Generally available throughout the entire tenant

Site Collection App Catalog: Limited to a single site collection

Criterion: Suitable for

Tenant App Catalog: Central standards and many production sites

Site Collection App Catalog: Pilots, isolated solutions, and separate areas of responsibility

Criterion: Rollout

Tenant App Catalog: Tenant-wide or installation per site

Site Collection App Catalog: Only within the relevant site collection

Criterion: Impact of an update

Tenant App Catalog: Depending on deployment, potentially many sites simultaneously

Site Collection App Catalog: Limited to the respective site collection

Criterion: Administration

Tenant App Catalog: Centrally by the App Catalog owners

Site Collection App Catalog: Decentrally by authorized site collection administrators

When the tenant app catalog makes sense

The tenant App Catalog is suitable when PnP Modern Search is to be used as a centrally managed platform component. This is useful, for example, when multiple intranet, knowledge, or department sites are to use the same package version.

Central deployment reduces installation effort but expands the impact area of a faulty update. A package change can then affect all pages where the web parts are used.

When a site collection app catalog is useful

A Site Collection App Catalog is suitable for a limited pilot operation or for sites whose extensions are to be managed independently of the rest of the tenant.

The catalog must first be activated for the relevant site collection by a SharePoint administrator. For this, the SharePoint Online Management Shell can be used, for example:

Connect-SPOService -Url https://contoso-admin.sharepoint.com

Add-SPOSiteCollectionAppCatalog `
  -Site https://contoso.sharepoint.com/sites/search-pilot

A prerequisite is an existing tenant App Catalog. The executing account must also be listed as a site collection administrator in both the central App Catalog and the target site.

Avoid, if possible, operating the same solution simultaneously and uncoordinated in the tenant App Catalog and in multiple site collection App catalogs. Different package states complicate error analysis, updates, and the assignment of the actually loaded version.

Upload package, release, and make visible in sites

1. Check package and release

Download the stable package version from the official release area of PnP Modern Search. Before uploading, check at least:

• Version number and release date
• Notes on breaking changes
• Known errors and limitations
• Changed or new API permissions
• Notes on the SPFx version used

Do not test a pre-release directly in a production App Catalog. Even for stable releases, the change should first take place on a copied or specifically created search page.

2. Upload package to the app catalog

Open the area for apps or the central page for app management in the SharePoint Admin Center. Upload the file pnp-modern-search-parts-v4.sppkg there.

When uploading, SharePoint displays a release dialog. Check there, in particular, whether the option for deployment to all sites is activated.

3. Define deployment scope

For the package, two ways are available in principle:

1. Central deployment: The solution is made available for all sites. The web parts appear without separate app installation in the intended sites.
2. Installation per site: The package is in the App Catalog but must be installed on each target site explicitly via "From your organization" or site content.

For a pilot operation, installation per site is usually easier to control. For a broad production rollout, central deployment reduces administrative effort but requires a robust test and release process.

In a Site Collection App Catalog, the deployment option that appears tenant-wide applies only to that specific Site Collection. Other Site Collections do not gain access to the package through this.

4. Check optional API requirements

After the upload, new permission requirements may appear in the SharePoint Admin Center under API Access. These requirements are separate from the actual package upload.

Handle each requirement individually:

1. Open the pending permission request.
2. Check the resource, permission name, and scope.
3. Assign the permission to a specific planned function.
4. Approve only the requirements that are actually needed.
5. Document the approver, date, and justification.

Microsoft Graph permissions typically require a correspondingly privileged Entra ID administrator role for approval. Access to the App Catalog alone is not sufficient for this.

5. Install app on the target site

If the package was not deployed centrally for all sites, open the target site and install the app via Site Contents or the From Your Organization area.

Wait until the installation is complete. Only then should the included webparts appear in the webpart selection menu on modern pages.

6. Check webparts on a test page

First, create a separate test page. Add at least one Search Box and one Search Results webpart to it. For a pure deployment test, a simple query without a custom layout and without complex filters is sufficient.

Only then expand the page with Search Filters and Search Verticals if the basic result output works correctly.

Who needs which rights for deployment and usage

Separate the roles for package deployment, API approval, and page configuration as much as possible. This makes it clear who approved a technical solution and who set it up content-wise.

Test deployment systematically

A successful upload does not mean the package works correctly on all intended sites. Therefore, use a short test matrix.

Technical baseline test

• The app is shown as activated in the App Catalog.
• The app is installed on the pilot site or available tenant-wide.
• The PnP web parts appear in the web part selection menu.
• A simple search query returns results.
• The browser console contains no recurring load errors.
• The page works after a full reload and in a private browser window.

Permission test

Test with at least two accounts:

• a Site Owner or administrator
• a normal user with limited read rights

Both accounts may receive different results. This is not an error, but the expected security filtering of the search.

If external users need access to the search page, you must also verify that all SPFx resources are accessible to guests. Missing access to package or asset locations can cause a web part to work for internal users but fail to load for guests.

Test optional features

Test features with additional API dependencies separately from normal SharePoint search. Examples include:

• Person cards
• Presence information
• Graph-based file searches
• Microsoft Search bookmarks
• Additional organization-wide Graph data

This helps distinguish whether an error stems from package deployment, a missing API permission, or the search configuration itself.

Typical errors and their causes

Web parts do not appear in the selection

First, check whether the package was only uploaded or also activated. For per-site deployments, the app must additionally be installed in the target site. Also verify that you are working in the correct app catalog and that the page is a modern SharePoint page.

The app is installed but some features are missing

In this case, optional API permissions are often missing. Open the API Access section in the SharePoint admin center and check for pending or rejected requests. Approve these only for the specific features used, not in general.

Only administrators see results

The deployment usually works in principle. Check permissions on the expected content, the search index, and the query used. Test whether the affected user can directly open the document or list item.

The search returns no results at all

Reduce the configuration to a simple query. Temporarily remove custom templates, filters, and dynamic connections. If even the simplified query returns no hits, the problem is more likely in the search scope, query template, indexing, or permissions than in the app catalog.

Old display remains visible after an update

Do not immediately clear global configurations or remove the package. Check first:

• whether the new package file is actually in the correct app catalog
• whether the upload was recognized as an update and confirmed
• whether the package version was changed
• whether browser or CDN caches are still serving old assets
• whether the tested site uses a local version from a Site Collection App Catalog

API access is not displayed in the admin center

Check whether the Tenant App Catalog is fully set up and correctly registered. If the central App Catalog is missing, the associated areas for managing API requests may also be missing.

Version changes, testing, and rollback paths

An update is typically performed by uploading the new .sppkg file to the existing App Catalog and replacing the existing file. For a centrally deployed solution, existing Webpart instances subsequently use the updated components.

As a result, every page does not need to be edited again. At the same time, an incompatible update can affect many pages at once.

Back up before every update

• Currently in production .sppkg file
• Version number and release notes
• List of sites and production search pages
• Screenshots of important Webpart settings
• Exported pages or site templates, as planned in operations
• List of approved API permissions
• Results of the last functional tests

The configuration of a PnP Webpart lies in the respective page. Therefore, a backed-up package alone does not automatically restore all page configurations.

Perform updates in deployment rings

A practical process consists of three stages:

1. Technical Test Site: Load the package, open Webparts, and run basic tests.
2. Pilot Sites: Test real configurations, user roles, and search scenarios.
3. Productive Rollout: Update the package in the central App Catalog or distribute it to additional sites in a controlled manner.

Between the pilot and the productive rollout, at least the most important search pages, templates, filter connections, and API-dependent functions should be checked.

Prepare a rollback path

Keep the last working package file outside the App Catalog. Additionally, the version control of the App Catalog library should remain active.

In case of a faulty update, the rollback path typically involves restoring the previous file version in the App Catalog or redeploying the last working package. Subsequently, activation status, API requests, and affected search pages must be checked again.

Note that a page configuration saved with a newer web part version may not be fully compatible with an older version. Therefore, test the rollback on a copy of the production page before a broad rollout.

Removing the package should be the final step. If a production-used SPFx solution is removed or disabled from the App Catalog, existing web part instances on many pages may no longer load.

Governance and rollout across multiple sites

Once PnP Modern Search is used across multiple sites, the package should be managed as a shared platform component. Simple technical documentation should include at least the following information:

• Package name and production version
• Source and release date
• App Catalog used
• Deployment scope
• Approved API permissions
• Owners of the package and search configuration
• Pilot and production sites
• Update and rollback procedures

For many sites, a central tenant App Catalog is usually easier to maintain than multiple independent package copies. Site Collection App Catalogs remain useful when individual solutions are intentionally isolated, tested separately, or owned by different teams.

In multi-geo environments, you must also consider that App Catalogs and deployments can be handled separately by geo-location. The rollout should then be documented and tested not only by site but also by geographic storage location.

Decision guide for the first rollout

Whether PnP web parts should initially be deployed locally, in a pilot, or tenant-wide depends less on the package file itself than on the operating model of the SharePoint environment. What matters is who approves changes, how many production pages are affected, and how quickly a rollback path can be implemented.

Situation: Initial technical review

Recommended starting point: Separate pilot site

Reasoning: Web parts, permissions, and search queries can be tested without broad impact.

Situation: A business team with its own responsibility

Recommended starting point: Site Collection App Catalog

Reasoning: The package scope remains limited to the department and can be evaluated separately.

Situation: Multiple intranet or knowledge sites

Recommended starting point: Tenant App Catalog with an approval process

Rationale: A central version reduces sprawl but requires controlled updates.

Situation: Existing production search pages

Logical starting point: Update in a ring

Rationale: Templates, filters, and API dependencies are first tested on copies.

After deployment, the actual search page is not yet complete. The next steps involve configuring the Search Box and Search Results, preparing Managed Properties for filters, and for more complex search scenarios, implementing PnP Search Filters with Refiners and KQL.

Checklist for approval and operations

• The package source, version, and release notes are documented.
• The deployment scope is intentionally chosen and not accidentally activated tenant-wide.
• API permissions were individually reviewed and justified from a business perspective.
• At least one pilot page was tested with a normal user account.
• The previous package version and a rollback procedure are available.
• Responsibilities for package updates and page configuration are clearly assigned separately.

This governance is especially important when PnP Modern Search is used as a shared search platform in the intranet.

How to introduce the package controlledly into production sites

For a secure introduction, you should first define the deployment scope, activate the package in a pilot site, and test both normal search queries and API-dependent functions there. Only then follows the approval for additional sites.

The most important control points are the App Catalog used, the option for tenant-wide deployment, the separately approved Graph permissions, and a tested rollback path. If these points are documented, later updates can be significantly easier to narrow down and trace.