Installation Guide

Prerequisites

SharePoint Online Requirements

Administrator Permissions

You will need one of the following roles:

• SharePoint Administrator: Full access to App Catalog and tenant settings
• Global Administrator: Full access to all Microsoft 365 services
• App Catalog Administrator: Access to upload and deploy apps

App Catalog Setup

Before installing Bonzai, ensure your tenant has an App Catalog:

1. Go to SharePoint Admin Center: https://[tenant]-admin.sharepoint.com
2. Click More features → Apps → App Catalog
3. If prompted, create a new App Catalog

Pre-Installation Checklist

Installation Steps

Step 1: Download the Package

Download the Bonzai SPFx package file (Bonzai-2.0.sppkg) from our Download page.

Step 2: Access SharePoint Admin Center

1. Open your browser and navigate to: https://[your-tenant]-admin.sharepoint.com
2. Sign in with your administrator credentials

Step 3: Navigate to App Catalog

1. In the SharePoint Admin Center, click More features in the left navigation
2. Under Apps, click Open
3. Click App Catalog to open the App Catalog site
4. Click Apps for SharePoint in the left navigation

Step 4: Upload the Package

1. Click Upload in the toolbar (or drag and drop the file)
2. Select the Bonzai-2.0.sppkg file from your computer
3. Click Open to upload

Step 5: Trust and Deploy

1. A deployment dialog will appear showing the solution name and web parts included
2. Review the requested permissions. Some Bonzai features use Microsoft Graph and require admin approval (for example, Calendars.ReadWrite for Outlook “Add to Calendar” and User.Read.All for Employee Directory Graph fallback).
3. Important: The dialog shows a checkbox: "Make this solution available to all sites in the organization." Leave this UNCHECKED unless you want the Mega Menu and Footer to appear on every site in your tenant. If unchecked, you control which sites get Bonzai by adding the app individually (Step 6).
4. Click Deploy to complete the installation
5. The package status should change to "Deployed" (green checkmark)

Step 6: Add the Bonzai App to Your Site (Mega Menu + Footer Activation)

1. Open the modern site where you want to use Bonzai
2. Go to Site Contents → New → App
3. Find Bonzai 2 and click Add
4. This activates the Mega Menu and Footer extensions; you can fully configure them later

Required Step if Apps Are Blocked by Tenant Policy

If "Apps you can add" is empty and Bonzai 2 does not appear, you must register the Mega Menu or Footer via Tenant Wide Extensions to activate those extensions.

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
4. Fill in the values below and click Save

Mega Menu registration

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":""}
Sequence: 100 (optional)
Web Template / List Template / Host Properties: leave blank

Footer registration

Title: Bonzai Footer
Component Id: b6c8c5d2-2a6d-4f44-9d67-2b9a9a3b9f42
Location: ClientSideExtension.ApplicationCustomizer
Component Properties:
{"footerListName":"FooterNavigation","feedbackListName":"FooterFeedback"}
Sequence: 110 (optional)
Web Template / List Template / Host Properties: leave blank

After Uploading a New Package Version

When you upload a newer version of the Bonzai .sppkg to the App Catalog, existing web parts update automatically. However, if the new package introduces new extensions (such as the Mega Menu or Footer), sites that already had the feature active may need a one-time reactivation:

1. Go to the affected site
2. Open Site Settings → Manage site features
3. Deactivate the "Bonzai 2.0 Suite" feature
4. Wait a moment, then Activate it again
5. Hard-refresh the page (Ctrl+Shift+R / Cmd+Shift+R)

Step 7: Wait for CDN Propagation

Step 8: Verify Installation

1. Navigate to any modern SharePoint site in your tenant
2. Edit a page (click Edit button)
3. Click the + button to add a web part
4. Search for "Bonzai" in the web part picker
5. You should see the Bonzai web parts listed (News Rollup, Events Rollup, etc.)

Verification Checklist

Package Verification

• Package appears in App Catalog with "Deployed" status
• Package version matches expected version
• No error messages in App Catalog

Web Part Verification

• Bonzai app added to the site (Mega Menu and Footer activated)
• Web parts appear in web part picker when searching "Bonzai"
• At least one web part can be added to a page
• Web part property pane opens when clicking pencil icon

Troubleshooting

Package Won't Upload

Web Parts Don't Appear in Picker

• Wait for CDN: Wait 5-15 minutes for CDN propagation
• Hard refresh: Press Ctrl+Shift+R to force refresh
• Check deployment: Verify package shows "Deployed" in App Catalog
• Check site type: Ensure you're on a Modern page (not classic)
• Clear cache: Clear all cached data for SharePoint

Web Part Shows Error

• Open F12 Developer Tools → Console for error details
• Verify list/view selections are valid in property pane
• Ensure current user can access the configured list
• Try removing and re-adding the web part

PowerShell Deployment (Alternative)

For scripted deployments, use PnP PowerShell:

# 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*"}

Next Steps

After installation:

• Web Parts Reference - Explore all 29 web parts
• Extensions - Configure Mega Menu and Footer
• Theme Manager - Customize colors and branding
• What is Bonzai 2? - Learn about the architecture