Build solutions with the library component type in SharePoint Framework

Article
06/29/2022

In this tutorial, you'll create a SharePoint Framework (SPFx) library component and use it within a client-side web part.

How to create a third-party SPFx library

Create a new project directory in your favorite location
```
md corporate-library
```
Go to the project directory
```
cd corporate-library
```
Create a new library by running the Yeoman SharePoint Generator
```
yo @microsoft/sharepoint
```
When prompted, enter the following values (select the default option for all prompts omitted below):
- 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 or adding apps in sites?: Yes
- Which type of client-side component to create?: Library
- What is your Library name?: CorporateLibrary
- What is your Library description?: CorporateLibrary description
Once the project is scaffolded, you'll see the library created with an index.ts file containing an export from the CorporateLibrary created.
Open the solution in your favorite editor and navigate to src/corporateLibrary/CorporateLibraryLibrary.ts

You'll notice that a default method, name() has been created. Rename this method as follows:

public getCurrentTime(): string {
  return 'The current time as returned from the corporate library is ' + new Date().toTimeString();
}

Run gulp on the command prompt to see everything builds fine.

How to consume a third-party SPFx library (for local testing)

Run gulp bundle --ship from the root directory of library solution. a simple gulp build not work.
Run npm link from the root directory of library solution. In this case, it would be from the corporate-library folder.
Right after creating the symbolic link to your new SPFx library component, don't forget to run at least once gulp build. Compile your library component at least once in order to be able to import it as a module into a different project. Remember that the package.json says that "main": "lib/index.js", so that location needs to exist before any import attempt.
This will create a local npm link to the library with the name, which is provided in the package.json.
Create a web part project in a separate project folder, so not in the library project folder structure, following the instructions from here. Name your web part CorporateWebPart.
From the root of the new web part folder, run the command npm link corporate-library
This will create a symbolic link to that locally built library in to the web part and will make it available to your web part.
Open the web part solution in your preferred editor and navigate to src/webparts/corporateWebPart/CorporateWebPartWebPart.ts

Add an import to refer to your library:

import * as myLibrary from 'corporate-library';

Change the render() method as follows:

public render(): void {
  const myInstance = new myLibrary.CorporateLibraryLibrary();

  this.domElement.innerHTML = `
  <div class="${ styles.corporateWebPart }">
      <div class="${ styles.container }">
      <div class="${ styles.row }">
          <div class="${ styles.column }">
          <span class="${ styles.title }">Welcome to SharePoint!</span>
          <p class="${ styles.subTitle }">Customize SharePoint experiences using Web Parts.</p>
          <p>${myInstance.getCurrentTime()}</p>
          <a href="https://aka.ms/spfx" class="${ styles.button }">
              <span class="${ styles.label }">Learn more</span>
          </a>
          </div>
      </div>
      </div>
  </div>`;
}

Notice that we're creating a new instance of the library, and then refer to the getCurrentTime() method to retrieve the current time string from the library.

Test your web part by launching the local workbench and add the web part to the page:
```
gulp serve
```

How to deploy and consume a third-party SPFx library from tenant App Catalog

Navigate to the corporate-library root folder to bundle and package the solution:
```
gulp bundle --ship
gulp package-solution --ship
```
This will build any local changes made and package the solution into an *.sppkg file in the sharepoint/solution folder.
Deploy this package in the tenant App Catalog and make it tenant wide deployed by checking the Make this solution available to all sites in the organization option.
Navigate to the web part solution folder, and open the ./package.json file.
Add an entry to reflect the library entry and its version to the dependencies section (you can find this in the package.json file of the library solution you're created earlier) as follows:
```
"dependencies": {
  "corporate-library": "0.0.1", // here we added the reference to the library
  "@microsoft/sp-core-library": "1.9.0",
  "@types/webpack-env": "1.13.1",
  "@types/es6-promise": "0.0.33"
},
```
Note

npm install will throw an error if you create a web part and you just added a reference to package.json and don't create a local reference using npm link. If you have created a link using npm link and run npm install, you will not receive an error during npm install but the symbolic link will be removed. If you want to run npm install, you will have to temporarily remove the reference to the corporate library and re-establish the reference by running npm link corporate-library and update the reference in package.json.

Build the web part:

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

Deploy the web part solution to the tenant App Catalog.
Add the newly added web part to a page and notice that the library is automatically made available to the web part functions.
Making any changes to the library, and publishing the library to the App Catalog again will automatically update the web part without the need to rebuild/republish the web part.

How to unlink SPFx library

To unlink a SPFx library that was symlinked during development in your SPFx project, navigate to SPFx project root folder and run the command.

npm unlink corporate-library

To check the folder location of SPFx library.

npm ls -g 'corporate-library'

To remove local npm link to the library, navigate to the SPFx library root folder and run the command.

npm unlink

Build solutions with the library component type in SharePoint Framework

How to create a third-party SPFx library

How to consume a third-party SPFx library (for local testing)

How to deploy and consume a third-party SPFx library from tenant App Catalog

How to unlink SPFx library

See also

Feedback

Additional resources