To deploy a SharePoint Framework (SPFx) solution for example navigation, here’s what you need to do step-by-step:
1. Setup Development Environment
Before deploying your SPFx solution, ensure your development environment is ready:
- Install Node.js (version 14.x.x recommended for SPFx development)
- Install Yeoman and Gulp:
Bash – Copy code below
npm install -g yo gulp
- Install SharePoint Framework Yeoman generator:
Bash – Copy code below
npm install -g @microsoft/generator-sharepoint
2. Create SPFx Web Part for Navigation
- Generate a new SPFx solution using Yeoman:
Bash – Copy code below
yo @microsoft/sharepoint
- When prompted, choose “WebPart” or “Extension” based on your navigation needs (most likely a Header/Footer navigation will be an Extension).
- Use the React framework if you prefer working with it, as it’s great for handling navigation components dynamically.
3. Customize Navigation
Depending on what type of navigation you’re creating, you might either:
- Create a Navigation Web Part: Use SharePoint REST API to fetch site navigation and dynamically create links.
- Use SPFx Application Customizer: This is used for extending the header or footer for global navigation, ensuring it’s present on every page.
Here’s a basic guide for Application Customizer:
Bash – Copy code below
yo @microsoft/sharepoint
# Choose Extension, then Application Customizer.
In the onInit() method, you can write the logic to update the navigation dynamically, for example:
Typescript – Copy code below
protected onInit(): Promise<void> {
// Custom logic for building navigation here
return Promise.resolve();
}
4. Build the Solution
After writing your code, use Gulp to build and bundle the solution:
Bash – Copy code below
gulp build
gulp bundle –ship
5. Package the Solution
Package the solution so it can be deployed:
Bash – Copy code below
gulp package-solution –ship
Note: This will generate a .sppkg file in the sharepoint/solution folder.
6. Deploy to SharePoint
- Go to your SharePoint Online App Catalog (make sure you have the necessary permissions).
- Upload the .sppkg file to the Apps for SharePoint library.
- You’ll be prompted to deploy the solution globally, which means it will be available on all sites.
7. Add the Navigation Component
Once deployed, navigate to the SharePoint site where you want to use your SPFx navigation solution:
- Add a Web Part: If you built a navigation web part, add it to the page where you want it to display.
- Activate the Application Customizer: If you used the Application Customizer, ensure that it’s activated either through the UI or by using a custom action script.
8. Test and Validate
Test the navigation on your SharePoint site to ensure it works correctly. Ensure it dynamically updates based on the site structure if you’re using dynamic navigation.
Deploy & manage SPFx (SharePoint Framework) solution
To deploy and manage an SPFx (SharePoint Framework) solution, you need certain privileges depending on the environment and what you want to achieve. Here’s a breakdown of the privileges you need for different tasks:
1. SharePoint App Catalog Access
- Permission Required: Tenant Administrator or App Catalog Site Owner
- Why: You need access to the App Catalog to upload and deploy SPFx solutions. The App Catalog is the centralized location for managing custom apps in SharePoint.
Privileges:
- Tenant Administrator: Full control over the entire SharePoint Online environment, including the ability to create the App Catalog.
- App Catalog Site Owner: Full control over the App Catalog site. If the App Catalog already exists, you need to be a site owner to upload the SPFx package (.sppkg file).
2. Deploy Solution Globally
- Permission Required: Tenant Administrator or delegated permissions to manage the App Catalog.
- Why: When deploying an SPFx solution globally (so it’s available across all SharePoint sites), this privilege is required.
Privileges:
- Global Tenant Administrator: Can approve and deploy the app across the tenant.
- App Catalog Site Owner: Can upload and deploy the solution, but might need approval from a Tenant Admin if additional permissions are required (such as API permissions).
3. Site Collection Administrator (Optional)
- Permission Required: Site Collection Administrator
- Why: You may need this to activate or manage the solution on specific SharePoint sites.
Privileges:
- Full Control over a specific SharePoint site collection.
- Can add the SPFx web parts or extensions to the pages of the site.
4. Manage Site Features (For Site-Specific Deployments)
- Permission Required: Site Owner or Full Control on specific sites.
- Why: If you’re deploying SPFx solutions only on specific sites (not globally), you need sufficient permissions to manage site features.
5. API Permissions (Optional)
- Permission Required: API Management Access
- Why: If your SPFx solution calls external services or needs API access (e.g., Microsoft Graph or Azure AD), you’ll need permissions to grant API access on behalf of users.
Privileges:
- Tenant Admin or App Catalog Admin: Can grant API permissions for the SPFx solution via the SharePoint Admin Center.
Summary of Required Permissions
| Task | Required Permission |
| Upload SPFx solution to App Catalog | App Catalog Site Owner or Tenant Admin |
| Deploy solution across tenant | Tenant Admin |
| Deploy solution to a specific site | Site Collection Admin or Site Owner |
| Manage API permissions (if needed) | Tenant Admin |
| Activate Web Part/Extension in a site | Site Owner or Full Control permissions |
For most cases, you’ll need App Catalog Site Owner or Tenant Admin privileges to upload and deploy the SPFx solution globally. For site-specific activation, you need Site Collection Admin or Site Owner privileges.
Deployment type Tenant-wide or Site Collection-specific.
You can deploy SPFx solutions in two ways: Tenant-wide or Site Collection-specific. Here’s a breakdown of both options:
1. Deploying Tenant-wide (Global Deployment)
- Use Case: You want the SPFx solution to be available across all SharePoint sites in your tenant.
- How:
- Upload the .sppkg file to the App Catalog (Tenant-level App Catalog).
- When you upload the package, you’ll be prompted with the option to “Make this solution available to all sites in the organization”.
- Select Yes to deploy it globally, making it available to all site collections without needing to manually add it to each site.
Pros:
- Available to all sites automatically.
- Easier to manage for large environments with multiple site collections.
Cons:
- Might expose the solution where it’s not needed if it applies to a limited number of sites.
- Requires Tenant Admin or App Catalog Admin rights.
2. Deploying to a Specific Site Collection
- Use Case: You want the SPFx solution available only on specific sites (site collections).
- How:
- Upload the .sppkg file to the App Catalog at the site collection level (if you have a site collection app catalog).
- Install and activate the solution within the specific site collection you want it to be available.
- Alternatively, if deploying via the Tenant App Catalog, you can choose not to deploy it globally, then manually add it to the specific site collection where it’s needed.
Pros:
- Greater control over where the solution is deployed.
- Limits exposure of custom solutions to specific site collections.
Cons:
- Requires manual deployment for each site collection.
- For larger environments, this can be more tedious.
Site Collection App Catalogs
If you don’t want to deploy tenant-wide but want app-level control over specific site collections, you can enable a site collection app catalog:
- It allows you to manage SPFx solutions at the site collection level.
- You can enable it using PowerShell with the following command:
Powershell – Copy code below
Connect-SPOService -Url https://yourtenant-admin.sharepoint.com
Add-SPOSiteCollectionAppCatalog -Site https://yourtenant.sharepoint.com/sites/yoursitecollection
This creates a local app catalog for the specific site collection, where you can upload and deploy SPFx solutions only for that site.
Recap:
- Tenant-wide Deployment: Best for making solutions available across all sites.
- Site Collection-specific Deployment: Best for controlling deployment to individual site collections where needed.
Note: if you like, use or share this content please credit author by including Name (David Coello) and link to original work.