Building SharePoint SPFx Extensions: The Advanced Guide

In this eighth article of the SharePoint Framework (SPFx) development series, we will focus on SPFx Extensions. Extensions are powerful tools that allow developers to customize and extend SharePoint experiences beyond web parts. By using extensions, you can enhance modern SharePoint pages, libraries, and lists to provide a more tailored experience for users.

This guide will cover the types of SPFx extensions, their use cases, and how to build a custom extension from scratch, leveraging PnP JS and Fluent UI for more advanced functionalities.

What Are SPFx Extensions?

SPFx Extensions allow developers to interact with and customize key areas of SharePoint sites, such as:

Command Set Extensions: These add custom commands to the SharePoint UI (e.g., buttons in the toolbar).
Application Customizers: These allow you to customize the overall experience by adding scripts, headers, or footers across the entire site.
Field Customizers: These are used to modify the way fields are displayed in SharePoint lists.

With these extensions, you can extend the SharePoint experience beyond what’s available through configuration and declarative customizations, giving developers flexibility to add more advanced, tailored solutions.

Types of SPFx Extensions

Command Set Extensions Command Set extensions allow you to add custom commands to the modern SharePoint lists or libraries. These commands can be configured to appear as buttons or menu items in the list toolbar or list item context menu. Use Cases:

Add buttons to perform bulk actions like sending emails, exporting data, or updating metadata.
Integrate third-party services, such as triggering a process in Microsoft Flow or an Azure Function when a list item is selected.

Application Customizers Application Customizers allow you to inject custom HTML, JavaScript, or CSS into the header or footer of every page on a site. This is useful when you want to provide global notifications, additional navigation, or even third-party scripts like Google Analytics. Use Cases:

Add a persistent navigation bar or footer.
Display custom banners for site-wide announcements or alerts.
Integrate analytics tracking across all SharePoint pages.

Field Customizers Field Customizers are used to modify how individual fields in SharePoint lists are displayed. This can be useful for customizing how certain types of data, such as dates, numbers, or URLs, are rendered. Use Cases:

Customize the display of status fields (e.g., green/red status indicators).
Render complex data visualizations within list fields (e.g., progress bars, icons).
Apply conditional formatting based on field values.

Building an SPFx Extension: Step-by-Step

1. Setting Up Your Environment

Make sure you have the SharePoint Framework development environment set up:

Node.js: Ensure you’re using a version supported by SPFx (e.g., 14.x or 16.x).
Yo generator for SPFx: Install the Yeoman generator globally if you haven’t already.

   npm install -g @microsoft/generator-sharepoint

2. Create a New SPFx Extension

To create an SPFx Extension project, run the following command:

yo @microsoft/sharepoint

During the prompt, select Extension and choose which type of extension you want to create (e.g., Application Customizer, Field Customizer, or Command Set).

Example: For this guide, we will create an Application Customizer:

? What is your solution name? MySPFxExtension
? Which baseline packages do you want to target? SharePoint Online only (latest)
? Where do you want to place the files? Use the current folder
? Do you want to allow the tenant admin the choice of being able to deploy the solution to all sites immediately without running any feature deployment? No
? Will the components in the solution require permissions to access web APIs that are unique and not shared with other components in the tenant? No
? Which type of client-side component to create? Extension
? Which type of extension do you want to create? Application Customizer

After creating the project, navigate to the src/extensions folder to start building the custom logic for your extension.

3. Write Your Custom Code

The core code for your SPFx extension will be located in the ApplicationCustomizer.ts file for an Application Customizer. You can modify this file to inject custom HTML, CSS, or JavaScript.

Example: Inject a simple header on every page in your SharePoint site:

import { override } from '@microsoft/decorators';
import { Log } from '@microsoft/sp-core-library';
import { BaseApplicationCustomizer } from '@microsoft/sp-application-base';
import * as strings from 'MySPFxExtensionStrings';
import { Dialog } from '@microsoft/sp-dialog';

const LOG_SOURCE: string = 'MySPFxExtensionApplicationCustomizer';

export interface IMySPFxExtensionApplicationCustomizerProperties {
  Top: string;
}

export default class MySPFxExtensionApplicationCustomizer extends BaseApplicationCustomizer<IMySPFxExtensionApplicationCustomizerProperties> {

  @override
  public onInit(): Promise<void> {
    Log.info(LOG_SOURCE, `Initialized ${strings.Title}`);

    let topPlaceholder = this.context.placeholderProvider.tryCreateContent('Top', { onDispose: this._onDispose });

    if (topPlaceholder) {
      topPlaceholder.domElement.innerHTML = `
        <div style="background-color: #ffcc00; text-align: center;">
          <p>Welcome to our SharePoint site!</p>
        </div>
      `;
    }

    return Promise.resolve();
  }
}

This simple example injects a yellow banner at the top of every page in your SharePoint site.

4. Debugging Your SPFx Extension

To test your extension, run the following command:

gulp serve --nobrowser

SharePoint Online provides an easy way to test extensions locally using the debug query parameters. Open a SharePoint site and append the following to the URL to load your local extension:

?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js

Now your extension will be injected into the page, and you can see your custom header in action.

5. Deploying Your Extension

After testing your extension, you can package and deploy it to your SharePoint site.

Package the solution:

   gulp bundle --ship
   gulp package-solution --ship

Upload the package: Navigate to your SharePoint App Catalog site and upload the .sppkg file from the sharepoint/solution folder. Once uploaded, you will be prompted to deploy the solution. Make sure to deploy the extension globally or to specific sites as required.
Add the Extension to a SharePoint Site: Once the solution is deployed, you can associate the extension with a SharePoint site by either using PowerShell commands, the SharePoint REST API, or the UI in the SharePoint site.

Leveraging PnP JS and Fluent UI

To further extend the functionality of your SPFx extensions, you can integrate libraries such as PnP JS and Fluent UI.

PnP JS: A lightweight library to simplify SharePoint REST API calls. Example of fetching SharePoint list items using PnP JS:

  import { sp } from '@pnp/sp';

  sp.web.lists.getByTitle('MyList').items.get().then((items: any[]) => {
    console.log(items);
  });

Fluent UI: A modern UI library from Microsoft to build consistent user experiences across web applications. Example of adding a Fluent UI button in your extension:

  import { PrimaryButton } from '@fluentui/react/lib/Button';

  const MyButton = () => (
    <PrimaryButton text="Click me!" onClick={() => console.log("Button clicked!")} />
  );

  export default MyButton;

Conclusion

SPFx extensions are powerful tools for customizing and enhancing SharePoint experiences. Whether you’re adding custom commands, headers, or visualizations, these extensions allow you to build tailored solutions for users. By leveraging PnP JS and Fluent UI, you can build more advanced and interactive extensions with ease.

Stay tuned for the next article in the series, where we’ll dive deeper into integrating third-party APIs with SharePoint extensions.

edvaldo b. guimarães filho

Building SharePoint SPFx Extensions: The Advanced Guide