How to use the SPFx Library component

Have you ever needed to share code between multiple SharePoint Framework projects but struggle to maintain it?

The answer to your problem is the SharePoint Framework Library component!

The Library component allows you to deploy an SPPKG and to reuse the code contained in the library package in other SPFx projects deployed in the same tenant.

I created this sample solution following the documentation on Microsoft Learn, if you want to know more check out the article.

If you’re interested in checking out the code you can find it here on GitHub.

Starting with the awesome and pretty complex UI (of course I’m joking), here is the result of the sample:

The bold text is from the web part, the other rows comes from the custom library component and are from three different methods.

Ok, but how do I achieve that?

To demonstrate how the library component is used I defined two projects:

• base-library: this contains the actual implementation of the library component.
• test-project: this contains the sample web part to demonstrate how to use the library component from another SPFx project.

To create both the projects I used the SharePoint Framework Toolkit Visual Studio Code extension (if you don’t already know this extension, and I think you should, check it out), as you can see when creating a new project you can choose the type of component you want to create, for the base-library solution I chose the library type:

Instead, for the test project, I chose the web part component:

Setup the library project

Once the projects are scaffolded using the VSCode extension I started with developing the library component.

In the main code of the library project (/src/libraries/baseLibrary/BaseLibrary.ts) there is an exported BaseLibrary class which contains three sample methods, those methods are:

• getPirateGreeting: it simply returns a greeting, but in pirate style!
• getDayOfWeek: it returns the string representing the day of the input date.
• isLeapYearMessage: returns a message which specify if the year of the input date is a leap year or not.

Those are very simple and straight forward methods but here I want to demonstrate how to use a library component and not a real world implementation.

Once that the code is ready we can build the project and get ready to test it in the web part:

gulp build

To enable the execution of the linking command it’s required to run at least once the bundle command:

gulp bundle --ship

To achieve the local testing we need to enable the linking of the custom library component from the web part project, to do so we need to use the NPM link command in the folder containing the custom library code:

npm link

This will enable the project linking from the web part project.

Once the symbolic link is created it’s required to run, at least once, the build command to ensure that the required files exists to enable the import from the target project, this is also required if you’re testing the code locally and made some changes to the library component:

gulp build

Now we can proceed with the consumer project.

Setup the consumer project

The consumer project consist in a simple web part project to demonstrate how to utilize the library component code.

Once created the project, it’s required to link the library project, to achieve this it’s mandatory to execute the link command specifying the link to be consumed, in my sample:

npm link base-library

The name base-library comes from the name attribute of the package.json file of the library component.

Once created the symbolic link you can use it in the web part code to debug it locally (I’ll show later how to set it up for deployment). To import the library component it’s simply required to add an import statement in the web part component:

import * as BaseLibrary from 'base-library';

At this point it’s possible to instantiate the class and use the methods defined in the library component:

const baseLibrary = new BaseLibrary.BaseLibrary();

const greeting = baseLibrary.getPirateGreeting();
const currentDate = new Date();
const dayOfWeek = baseLibrary.getDayOfWeek(currentDate);
const isLeapYearMessage = baseLibrary.isLeapYearMessage(currentDate);

After retrieving the values you can display those in the render method.

At this point it would be nice to test in the workbench and see how the web part renders, right? It’s a piece of cake! Simply run the following command and go to the workbench to test your web part:

gulp serve --nobrowser

Ok but…how do I deploy it?

To publish and use your packages in SharePoint Online you need to perform some other steps after the previous ones.

It’s mandatory to tell the web part project that there’s a dependency from the library component and it’s easily done adding the corresponding statement under the dependencies section of the package.json file, for example in the sample solution:

"dependencies": {
  "base-library": "0.0.4",

After adding the dependency you can package both the projects and deploy them in the App Catalog. To package the projects run the following commands in the root folder of each project to create the SPPKG files:

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

At this point the last thing to do is to deploy the SPPKG files in the App Catalog, first the library component package file and then the web part one and you’re ready to use the web part!

If you’re wondering how to publish the SPPKG files you can have a look at this article.

Conclusions

The library component is quite a useful type of SharePoint Framework component, especially when you have to deploy a custom centralized code that you want to reuse in your tenant.

Hope this helps!