• OVERVIEW
• PREREQUISITES
• Why this is a migration, not an upgrade
• Architecture comparison
• Workflow changes to plan for
• Migration checklist
• Feature mapping
• Testing and rollout
• Common migration risks

OVERVIEW

Use this article when planning a move from Classic Bonzai on Classic SharePoint to Bonzai 2 on Modern SharePoint. The goal is to set expectations before work begins: Bonzai 2 is a platform change, not an in-place upgrade. Pages, lists, web part configuration, navigation, and theming must be reviewed and rebuilt for Modern SharePoint.

Outcome: After planning, you should know what content must be recreated, which Bonzai 2 components replace Classic features, what permissions and package deployment steps are required, and how much validation work is needed before launch.

PREREQUISITES

• An inventory of current Classic Bonzai site collections, pages, page owners, and web parts.
• Access to the current Classic Bonzai configuration, including theme colors, navigation, targeting rules, and any custom list structures.
• A Modern SharePoint site plan, such as new Communication Sites or Team Sites using the modern experience.
• SharePoint Administrator or App Catalog Administrator access for the Bonzai 2 package deployment.
• Content owners available to validate rebuilt pages.

Why this is a migration, not an upgrade

Classic Bonzai used Classic SharePoint publishing sites, master pages, Brick administration, CDN-hosted assets, JSOM/CAML patterns, and Classic page layouts. Bonzai 2 uses SharePoint Framework, React, Fluent UI, SharePoint REST APIs, Modern SharePoint pages, the App Catalog, and on-page configuration through property panes and Theme Manager.

Why this matters: Classic pages cannot simply become Modern pages with the same layout and configuration. Modern SharePoint uses a different page model, so content and configuration must be recreated in the modern experience.

Warning: Plan in weeks or months, not hours, unless the site is very small. A successful migration includes discovery, infrastructure setup, pilot pages, content recreation, testing, training, and launch communications.

What You Don't Need Anymore

One of the best parts of migrating to Bonzai 2 is the elimination of legacy infrastructure:

- Brick login & AWS Cognito credentials: No longer needed; everything is configured natively inside SharePoint.

- CDN wait times: Changes are instant since assets are served directly from your Office 365 tenant.

- Custom master pages: Replaced entirely by standard SPFx Application Customizers.

- Image renditions: Replaced by native Modern SharePoint responsive image handling.

- JSOM/CAML & Font Awesome: Replaced by SPHttpClient (REST) and modern Fluent UI icons.

Architecture comparison

Area	Classic Bonzai	Bonzai 2
Platform	Classic SharePoint publishing sites	Modern SharePoint sites
UI technology	Classic page layouts, master pages, and bonzai.min.js	SharePoint Framework web parts and Application Customizers
Administration	Brick and external infrastructure	SharePoint App Catalog, property panes, and Theme Manager
Data access	JSOM and CAML patterns	SharePoint REST APIs through SPFx
Theming	Brick Theme Editor and published theme assets	Theme Manager with CSS Custom Properties
Navigation	Classic navigation and master-page integration	Mega Menu Application Customizer driven by MegaMenuNavigation
Footer	Classic master-page or Brick-driven footer	Footer Application Customizer driven by FooterNavigation
Icons	Font Awesome patterns	Fluent UI icon names

Workflow changes to plan for

⚠️ Two-step activation for extensions (Mega Menu & Footer)

Uploading `Bonzai-2.0.sppkg` to the App Catalog is not enough. 

For each site collection where you want the Mega Menu or Footer to appear, you must also add the Bonzai app via Site Contents → New → App → Bonzai 2, or register the customizers in the Tenant Wide Extensions list if "Apps you can add" is blocked by tenant policies.

Adding web parts: In Classic Bonzai, editors selected web parts from Classic edit mode, chose fixed zones, and often typed list or view names manually. In Bonzai 2, editors use Modern page edit mode, select the + button, search for Bonzai web parts, and configure them through property panes with pickers.

Theming: In Classic Bonzai, theme changes required Brick access and publishing. In Bonzai 2, Theme Manager lets editors preview colors on-page and save the theme for the site.

Navigation: Classic navigation should be inventoried and redesigned for the MegaMenuNavigation list. Do not assume Classic term-set navigation maps one-to-one to the Mega Menu; the Mega Menu supports a three-level hierarchy and uses list relationships.

Migration checklist

Phase	Actions	Why it matters
Discovery and planning	Inventory sites and pages; document page owners; record every Classic web part; export theme colors; document navigation and targeting rules; identify obsolete pages.	This prevents rebuilding pages nobody needs and preserves configuration decisions that are otherwise easy to lose.
Infrastructure setup	Prepare the App Catalog; upload Bonzai-2.0.sppkg; create Modern SharePoint sites; add the Bonzai app to pilot sites.	Bonzai 2 components must exist in the tenant and be activated on the target site before editors can build pages.
Content recreation	Create pilot pages first; recreate high-value pages; connect each web part to the correct list, library, search scope, or page metadata; rebuild navigation and footer lists.	Modern pages and property-pane settings are new artifacts, not converted Classic page layouts.
Validation	Test every page, list, permission, content-targeting rule, device size, and search-based component.	Most migration issues are configuration, permissions, indexing, or missing metadata problems.
Rollout	Train content editors; soft-launch to a limited audience; collect feedback; communicate the full launch; redirect or retire old URLs where appropriate.	Users need to understand changed navigation, changed editing workflows, and where to report issues.

Feature mapping

✅ Success: Marketplace is back in Bonzai 2

The Marketplace web part has been completely re-implemented for Modern SharePoint and ships in Bonzai 2. It now points at any SharePoint list with dynamic columns, filtering, sorting, and an optional creation button.

General Features & Infrastructure Mapping

Classic feature	Bonzai 2 Equivalent	Migration action
Theme Editor	Theme Manager web part	Recreate colors, dark mode settings, and branding properties.
Content Targeting	SharePoint list columns	Add metadata columns (Department, Location, Role) directly to lists.
Footer	Footer App Customizer	Rebuild links in FooterNavigation (+ optional FooterFeedback) list.
Page layouts	Page Banner + Sidebar web parts	Recreate page structure using Page Banner + matching Sidebars.
Header Search	Advanced Search web part	Add to a dedicated modern search page.
Comments	SharePoint native comments	Enable page comments toggle on modern pages.
Icons	Fluent UI icons	Map existing Font Awesome class names to Fluent UI icon names.
Mega Menu	Mega Menu App Customizer	Rebuild navigation structure (up to three levels) in MegaMenuNavigation list.
Navigation	SharePoint navigation	Configure modern site navigation and MegaMenuNavigation list.

Precise Web Part Mapping Table

Bonzai 2 ships with 29 web parts; 22 of these map directly to legacy Bonzai web parts with high feature parity:

New Modern Capabilities

These web parts are brand new in Bonzai 2 and unlock modern web patterns:

- Theme Manager: On-page brand color configuration with real-time preview and light/dark modes.

- Page Banner: Full-width hero banner for News, Events, and Spotlights that auto-reads page metadata.

- News Sidebar / Event Sidebar / Spotlight Sidebar: Companion metadata widgets for modern articles.

- Content Cards: Highly responsive card grids built from custom SharePoint lists.

- Image Link Gallery: Elegant tile/image gallery grids driven by a list, with quick pagination.

Testing and rollout

1. Build three to five pilot pages that represent the most important page types.
2. Test each Bonzai 2 web part with real source content and a non-admin user account.
3. Verify content targeting by signing in as users from different SharePoint groups.
4. Test mobile and tablet layouts, especially Mega Menu, Footer, Slider, Landing, and card-based web parts.
5. Confirm search-based components after SharePoint Search has indexed the content.
6. Review the pilot with page owners before rebuilding the rest of the intranet.
7. Train editors on Modern page editing, property panes, Theme Manager, and list-driven configuration.

Common migration risks

Risk	What causes it	Mitigation
Modern pages do not match Classic layouts exactly	Modern SharePoint has different sections, responsive behavior, and no Classic page-layout zones.	Design new page patterns instead of trying to reproduce every Classic pixel.
Rollups are empty	Source lists, Showcase values, categories, tags, permissions, or search indexing do not match the new configuration.	Test each web part against a known item and loosen filters until the base source works.
Theme looks inconsistent	Theme Manager was not saved site-wide or pages lack Bonzai components that load the theme variables.	Save Theme with site-wide persistence and test on multiple pages.
Navigation hierarchy is confusing	Classic term-set structure was copied without simplifying for the three-level Mega Menu model.	Redesign the navigation tree for Level 1, Level 2, and Level 3 before data entry.
Editors cannot maintain the site	Editors know Classic publishing workflows but not Modern page editing and property panes.	Include hands-on editor training before launch.
Launch takes longer than expected	The plan underestimates content recreation and stakeholder review time.	Use pilot pages to measure real rebuild time, then forecast the rest of the migration from that evidence.