Building solutions with the library component type in SharePoint Framework

How to create a 3rd 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:

    • Accept the default corporate-library as your solution name, and then select Enter.
    • Select SharePoint Online only (latest), and select Enter.
    • Select Use the current folder for where to place the files.
    • Select Y to allow solution to be deployed to all sites immediately.
    • Select N on the question if solution contains unique permissions.
    • Select Library as the client-side component type to be created.
    • The next set of prompts ask for specific information about your library:
    • Change the default Library name to CorporateLibrary as your library name, and then select Enter.
    • Accept the default CorporateLibrary description as your library description, and then select Enter.
  6. Once the project is scaffolded, you will see the library created with an index.ts file containing an export from the CorporateLibrary created.

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

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

How to consume a 3rd 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. This will create a local npm link to the library with the name which is provided in the package.json.

  3. 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'

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

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

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

  7. Add an import to refer to your library:

    import * as myLibrary from 'corporate-library';
    
  8. 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 are creating a new instance of the library, and then refer to the getCurrentTime method to retrieve the current time string from the library.

  9. Test your webpart by launching the local workbench and add the webpart to the page:

    gulp serve
    

How to deploy and consume a 3rd 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 your 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 do not 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 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.

See also