The right way to publish SharePoint Framework library packages

SharePoint Framework library components are a great way to build reusable code for your solutions. But if you miss this one detail, you’ll end up including the shared code in your bundle.

Reusable code with great performance

SharePoint Framework library components are a great way to build reusable code for your solutions. Whether you need it to standardize logging or accessing line of business services, SharePoint Framework libraries allow you to ensure that the shared code is loaded only once on the page, no matter how many other components use it.

Build SharePoint Framework library components

Building SharePoint Framework library components doesn’t differ much from building web parts or extension. You build a SharePoint Framework component of type library and use the SharePoint Framework toolchain to create an solution package (.sppkg) that you’ll publish in the SharePoint app catalog.

An extra thing that you need to do for libraries, is to create an npm package. No matter how you distribute it, you need it, to reference the shared code in your solutions. But if you don’t build the library npm package correctly, instead of reusing the shared code, you’ll end up including it in your bundle. Here’s how to avoid id.

The correct way to build an npm package for SharePoint Framework libraries

To use the shared code from a SharePoint Framework library, you need to install it as a dependency in your project. At that stage, it’s just another npm package. But when you bundle your project using the SharePoint Framework gulp bundle task, the SharePoint Framework toolchain will detect for each dependency if it’s a SharePoint Framework component or not. It does that, by searching for dist/*.manifest.json file in the dependency folder in node_modules. And this is where things often go wrong.

By default, when you create an npm package for a SharePoint Framework library project, it will include the following files/folders:

  • README.md
  • .yo-rc.json
  • config/*
  • gulpfile.js
  • lib/*
  • package.json
  • src/*
  • tsconfig.json
  • tslint.json

Notice how the dist folder isn’t included by default!

So if you’d use such an npm package with a SharePoint Framework library, rather than reusing the shared code, you’d end up including it in your bundle, possibly leading to all kinds of hard-to-debug side-effects.

So how to fix it? It turns out, that all you need is to add the following .npmignore file to your SharePoint Framework library project:

!dist
config
gulpfile.js
release
src
temp
tsconfig.json
tslint.json
*.log
.yo-rc.json

With this file in place, when you run the npm publish command for your SharePoint Framework library project, it will generate a package with the following files:

  • README.md
  • .yo-rc.json
  • dist/78b11c7d-7ca8-47cb-a93c-d3beabb519a1.manifest.json
  • dist/*
  • lib/*
  • package.json

Notice, that next to the lib folder with TypeScript type definitions and the shared code used during development, the package also contains the *.manifest.json file required by the SharePoint Framework toolchain to properly recognize the npm package as a library. After this modification, your project will properly exclude the library code from your project, and on runtime load it from the shared library package deployed in SharePoint.

For more information about working with SharePoint Framework libraries see the docs.

Others found also helpful: