Building solutions with the library component type in SharePoint Framework

How to create a third-party SPFx library

  1. Using the instructions here, set up the dev environment.

  2. Create a new project directory in your favorite location

    md corporate-library
    
  3. Go to the project directory

    cd corporate-library
    
  4. Create a new library by running the Yeoman SharePoint Generator

    yo @microsoft/sharepoint
    
  5. When prompted:

  6. 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?: Y
    • Which type of client-side component to create?: Library
    • What is your Library name?: CorporateLibrary
    • What is your Library description?: CorporateLibrary description
  7. Once the project is scaffolded, you'll see the library created with an index.ts file containing an export from the CorporateLibrary created.

  8. Open the solution in your favorite editor and navigate to src\corporateLibrary\CorporateLibraryLibrary.ts

  9. 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();
    }
    
  10. Run gulp on the command prompt to see everything builds fine.

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

  1. Run npm link from the root directory of library solution. In this case, it would be from the corporate-library folder.

  2. 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", therefore, that location needs to exist prior to any import attempt.

  3. This will create a local npm link to the library with the name, which is provided in the package.json.

  4. 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.

  5. From the root of the new web part folder, run the command npm link corporate-library

  6. 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.

  7. Open the web part solution in your preferred editor and navigate to src\webparts\corporateWebPart\CorporateWebPartWebPart.ts

  8. Add an import to refer to your library:

    import * as myLibrary from 'corporate-library';
    
  9. 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.

  10. 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

  1. Navigate to the corporate-library root folder and 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, which is located in the sharepoint\solution folder.

  2. 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.

  3. Navigate to the web part solution folder, and open the package.json file in the root of that folder.

  4. 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.

  5. Build the web part:

    gulp bundle --ship
    gulp package-solution --ship
    
  6. Deploy the web part solution to the tenant App Catalog.

  7. Add the newly added web part to a page and notice that the library is automatically made available to the web part functions.

  8. 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.

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

See also