• OVERVIEW
• PREREQUISITES
• Prepare the App Catalog
• Upload and deploy the Bonzai 2 package
• Activate Bonzai 2 on a site
• Verify the installation
• If apps are blocked by tenant policy
• PowerShell deployment option
• Troubleshooting and escalation details

OVERVIEW

Use this article when you need to deploy Bonzai 2 to a Microsoft 365 tenant and activate the Bonzai 2 web parts, Mega Menu, and Footer on one or more Modern SharePoint sites. Bonzai 2 is delivered as a SharePoint Framework package named Bonzai-2.0.sppkg. Uploading the package makes the components available in the tenant; adding the Bonzai app to a site activates the site-wide Mega Menu and Footer extensions for that site.

Why this matters: Uploading the package and activating it on a site are separate actions. If the package is only uploaded to the App Catalog, the web parts may be available to add, but the site-wide extensions do not necessarily run on the target site. If the solution is made available to every site during deployment, the extensions can appear more broadly than intended.

PREREQUISITES

• A SharePoint Online tenant.
• The Bonzai 2 SharePoint Framework package file, Bonzai-2.0.sppkg, supplied to your organization (Where to Download)
• One of these roles: SharePoint Administrator, Global Administrator, or App Catalog Administrator.
• A tenant App Catalog. Microsoft documents the App Catalog creation path in Set up your Microsoft 365 tenant.
• A Modern SharePoint site where Bonzai 2 should be used, such as a Communication Site or a Team Site using the modern experience.
• Permission to add apps to the target site. If tenant policy blocks user-added apps, use the blocked-apps section instead of guessing component IDs.

Prepare the App Catalog

1. Open the SharePoint Admin Center at https://[tenant]-admin.sharepoint.com, replacing [tenant] with your tenant prefix.
2. In the left navigation, select More features > Apps > Open.
3. Open App Catalog. If the tenant does not have one yet, create a new App Catalog site.
4. In the App Catalog site, open Apps for SharePoint.

Why this works: The App Catalog is the tenant-level library where SharePoint Framework packages are uploaded and trusted. SharePoint uses it to make the packaged web parts and extensions available to sites.

Upload and deploy the Bonzai 2 package

1. In Apps for SharePoint, select Upload or drag the Bonzai-2.0.sppkg file into the library.
2. When the deployment dialog appears, review the package name, included components, and requested permissions.
3. If Microsoft Graph permissions are requested, review them carefully. Bonzai features such as Outlook add-to-calendar behavior and directory lookup can require administrator approval before the related feature works for users.
4. Leave Make this solution available to all sites in the organization unchecked unless your implementation plan explicitly requires Bonzai 2 extensions to be available across the whole tenant by default.
5. Select Deploy.
6. Confirm that the package status changes to Deployed.

What would go wrong if you deploy too broadly: Tenant-wide availability can cause the Mega Menu and Footer to initialize on sites that were not part of the rollout plan. Keep the checkbox unchecked when you want to control activation site by site.

Activate Bonzai 2 on a site

1. Open the Modern SharePoint site where Bonzai 2 should run.
2. Go to Site Contents > New > App.
3. Find Bonzai 2 and select Add.
4. Wait for the app to finish adding to the site.
5. Hard-refresh the site in the browser.

Why this works: Adding the app to the site activates the Bonzai 2 feature for that site collection. That activation is what enables the Mega Menu and Footer Application Customizers to run site-wide.

Warning: If the site previously used a separate bonzai-mega-menu app, remove that older app from Site Contents after upgrading to the consolidated Bonzai 2 package. Leaving both in place can create duplicate initialization.

Verify the installation

1. Open any Modern SharePoint page on the target site.
2. Select Edit.
3. Select the + button to add a web part.
4. Search for Bonzai.
5. Confirm that Bonzai web parts such as News Rollup, Events Rollup, or Theme Manager appear in the picker.
6. Add one Bonzai web part to a test page and open its property pane by selecting the pencil icon.
7. Confirm that the property pane opens and that list or view pickers load where applicable.

Expected propagation time: First deployments usually need a few minutes before components appear everywhere. Package updates can take longer because browser and CDN caches may still hold older files.

If apps are blocked by tenant policy

If Apps you can add is empty, or if users cannot add the Bonzai app because tenant policy blocks site app installation, do not invent or reuse component IDs from an example. Manual activation through Tenant Wide Extensions requires the actual component IDs from the deployed Bonzai 2 package.

1. Open the App Catalog site: https://[tenant].sharepoint.com/sites/appcatalog.
2. Go to Site Contents > Tenant Wide Extensions.
3. Click New → Application Customizer to register the Mega Menu with these values:
   • Title: Bonzai Mega Menu
   • Component Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
   • Location: ClientSideExtension.ApplicationCustomizer
   • Component Properties:

     {
     "navigationListName":"MegaMenuNavigation",
     "hideNativeNavigation":true,
     "hideMobileAppBar":true,
     "showBreadcrumb":true,
     "licenseApiUrl":""
     }

4. Click New → Application Customizer to register the Footer with these values:
   • Title: Bonzai Footer
   • Component Id: b6c8c5d2-2a6d-4f44-9d67-2b9a9a3b9f42
   • Location: ClientSideExtension.ApplicationCustomizer
   • Component Properties:

     {
     "footerListName":"FooterNavigation",
     "feedbackListName":"FooterFeedback"
     }

Why this caution matters: The Component Id must match a component that exists in the deployed package. A wrong GUID creates a Tenant Wide Extensions entry that does not activate the intended extension and can make troubleshooting harder.

PowerShell deployment option

Use PnP PowerShell when you need repeatable deployment steps. Replace the tenant prefix and package path before running the commands.

# Install PnP PowerShell module (if not already installed)
Install-Module -Name PnP.PowerShell -Scope CurrentUser

# Connect to SharePoint Admin Center
Connect-PnPOnline -Url "https://[tenant]-admin.sharepoint.com" -Interactive

# Upload and deploy the solution
Add-PnPApp -Path "C:\path\to\Bonzai-2.0.sppkg" -Scope Tenant -Publish -Overwrite

# Verify deployment
Get-PnPApp | Where-Object {$_.Title -like "*Bonzai*"}

Why this works: The script performs the same App Catalog upload and publish action as the browser workflow, but it is easier to repeat for controlled deployments or package updates.

Troubleshooting and escalation details

Symptom	What to check	Why it matters
The package does not upload	Confirm the file is the expected .sppkg, verify App Catalog permissions, retry in a modern browser, and obtain a fresh package if the upload reports corruption.	The App Catalog validates and stores the package. If the file is corrupted or the account lacks rights, SharePoint cannot trust the solution.
Bonzai web parts do not appear in the picker	Wait for propagation, hard-refresh the browser, confirm the package status is Deployed, and verify you are editing a Modern page.	The web part picker only shows deployed components that are available to the current site and page experience.
A Bonzai web part shows an error	Open browser Developer Tools with F12 > Console, verify the configured list or view still exists, and confirm the current user can access that list.	Most runtime errors are caused by missing lists, renamed views, or permissions on the configured data source.
Mega Menu or Footer does not appear	Confirm the Bonzai app was added to the target site, then hard-refresh. If the package update introduced new extensions, deactivate and reactivate the Bonzai 2.0 Suite site feature.	Uploading a new package updates web parts, but a newly introduced Application Customizer may need a one-time site feature reactivation.

If the issue remains after these checks, contact Bonzai Support and include: 

- tenant URL

- target site URL

- App Catalog package status, 

- whether the organization-wide deployment checkbox was selected, 

- whether the Bonzai app appears in Site Contents,

- browser console errors, screenshots of the web part picker, 

- and the exact web part or extension that is missing.