Mastering SharePoint Common Framework: A Practical Guide for Developers

Migrating Classic Solutions to SharePoint Common Framework: Step-by-Step

Overview

This guide walks through migrating classic SharePoint solutions (server-side web parts, script editor/content editor customizations, and classic add-ins) to the SharePoint Framework (SPFx). It assumes a working SharePoint Online tenant and basic familiarity with Node.js, Git, and modern JavaScript/TypeScript.

Before you start — checklist

• Backup: Export site collections, lists, and libraries. Save important assets (images, scripts, styles).
• Inventory: Catalog customizations: web parts, workflows, event receivers, custom actions, master pages, and JavaScript injected via Script Editor or Content Editor.
• Assess: Mark each item as: Replace with SPFx, Reimplement as Power Platform (Power Automate/Power Apps), Use SharePoint Add-in, or Retire.
• Environment: Install Node.js LTS, Yeoman, gulp, @microsoft/generator-sharepoint, Git, and an editor (VS Code). Ensure tenant App Catalog exists.

Step 1 — Inventory and impact analysis

1. Export a list of customizations (scripts, web parts, features).
2. Identify dependencies (server-side code, farm solutions, timer jobs).
3. Flag unsupported server-side features (full-trust solutions): plan alternatives (Azure Functions, Microsoft Graph, SharePoint REST).

Step 2 — Plan replacement patterns

• Classic Web Parts (ASCX, server-side): Rebuild as SPFx client-side web parts.
• Script/Content Editor custom scripts: Migrate into SPFx Application Customizers or web parts.
• Custom Actions/Command UI: Use SPFx extensions or modern list command sets.
• Event Receivers/Timer Jobs: Replace with Power Automate flows, Azure Functions with remote event receivers, or webhook-based handlers.
• Custom Master Pages: Recreate UI via modern site designs, site scripts, or SPFx components; avoid custom master pages.
• Workflows: Migrate SharePoint ⁄₂₀₁₃ workflows to Power Automate or Azure Logic Apps.

Step 3 — Set up your SPFx development environment

1. Install Node.js LTS (recommended v18/v20 as supported).
2. Install Yeoman and the SPFx generator:

   Code
   Copy CodeCopied
   npm install -g yo @microsoft/generator-sharepoint gulp 

3. Create a new project directory and scaffold:

   Code
   Copy CodeCopied
   yo @microsoft/sharepoint 

   • Choose framework (No framework, React recommended).
   • Configure web part or extension details.
4. Trust the developer certificate for local workbench:

   Code
   Copy CodeCopied
   gulp trust-dev-cert 

Step 4 — Rebuild functionality in SPFx

1. Convert UI to modern components (React + Fluent UI recommended).
2. Replace DOM-injection scripts with proper component lifecycle code.
3. For data access, use the SharePoint REST API or Microsoft Graph:
   • Use AadHttpClient/MSGraphClient for authenticated calls.
4. Implement caching and performance patterns (lazy loading, code splitting).
5. Handle permissions: declare API permissions in package-solution.json and submit to tenant admin for consent when needed.

Step 5 — Develop extensions where appropriate

• Application Customizer: global scripts, headers/footers, banner notifications.
• Field Customizers: custom rendering for list fields.
• Command Sets: custom list/command actions in command bar.

Step 6 — Packaging and tenant deployment

1. Bundle and package:

   Code
   Copy CodeCopied
   gulp bundle –ship gulp package-solution –ship 

2. Upload the .sppkg to the tenant App Catalog.
3. Deploy the package; if it needs tenant-scoped permissions, request tenant admin consent.
4. Add the web part/extension to modern pages or site scripts.

Step 7 — Migrate content and workflows

1. Recreate pages using modern web parts.
2. Migrate list/library content via SharePoint Migration Tool or third-party tools.
3. Rebuild workflows in Power Automate; connect to SPFx where necessary via Power Automate connectors or webhooks.

Step 8 — Testing and validation

• Functional testing across modern pages and classic fallback scenarios.
• Performance testing (page load, bundle sizes).
• Security review: API permission scopes, CSP compliance.
• Accessibility testing (WCAG).

Step 9 — Rollout plan

1. Pilot: Deploy to a small set of sites and gather feedback.
2. Training: Provide documentation and short workshops for site owners.
3. Phased rollout: Gradually replace classic pages and features.
4. Decommission classic customizations after successful migration.

Troubleshooting tips

• Missing APIs: use Azure Functions as a proxy for server-side logic.
• Third-party dependencies: bundle or load via CDN; prefer modern packages.
• Authentication errors: ensure correct resource URLs and permissions; test with Workbench and hosted pages.
• Large bundle size: analyze with source-map-explorer and lazy-load heavy libs.

References & resources

• SPFx official docs and generator templates (use tenant docs for exact supported Node versions).
• Microsoft Graph and SharePoint REST API docs.
• Power Automate migration guidance.

Summary: Follow the inventory → plan → rebuild → deploy → validate cycle. Prioritize reusability with SPFx, replace server-side logic with cloud services, and use Power Platform where it fits.