Article
3 comments

Tips and Tricks working with SPFx library components

Following the instruction on how to create a library component, get you pretty easy up and running to try out this new feature.

Tips and Tricks working with library components

To make it production-ready you have to do some manual steps and tweaks. Here are some suggestions.

Do not use ‘npm link’

NPM link in case of library components is a bit misused in this purpose. In general, it’s a tool to run a local development package as a global installed dependency. For example, from our area Office 365 CLI development, Yeoman generator development (PnP/spfx) or Teams generator. In short, everything that is executable from everywhere. In this case, it just mimics an ‘npm install’ in the wrong way.

One caveat is that you can only have one ‘npm link’ to a specific folder at a time. This way you lose track which folder is currently in charge and which have been ‘unlinked’.

The easiest way to check the folder in charge is by using the following npm command.

npm ls -g 'corporate-library'

It gives you an indication where the library component is stored. Sorry, the screenshot is from a macOS, but the path should display the same way on Windows.

'npm ls' can be used to find the library origin folder

‘npm ls’ can be used to find the library origin folder

When you reinstall upgrade your NodeJS version, reinstall NodeJS, or use NVM you have to ‘npm link’ the library again. You are out of luck when you don’t remember where this last instance was.

‘npm link’ should only be used when you are the one that develops the library component, not reuse it.

Another side effect is when you delete the folder at some point. The only chance you have is to recreate that file path and perform an ‘npm unlink’ on that folder. The dirty way is to delete the link manually in the global registration.

If you still like to use ‘npm link’

Let’s say you develop a library component and have a consumer project for your component. Both are on in the same base folder.

Project setup of one library component and web part project

Project setup of one library component and web part project

‘corporate-library’ is your library component and ‘corporate-webpart’ your web part project. Instead of juggling around go to this folder and that folder you only have to be in the ‘corporate-webpart’.

npm link ../corporate-library

This command places both symbolic links at once in the global registration as well as in your current project.

Add npm post-install script

NPM allows you to define script shortcuts in the package.json configuration. It also offers what happens in specific situations when something happens in the project.

  • pre-install – Occurs before you install a package
  • post-install – Occurs after you have installed a package

NPM script documentation has a complete list of actions for you.

In the case of library components, it makes sense to add a post-install script. This way, it automatically creates a new build whenever you refer to it.

Open the ‘package.json’ file in the library component root folder and add the following entry in the script section.

  "scripts": {
    "build": "gulp bundle",
    "clean": "gulp clean",
    "test": "gulp test",
    "postinstall": "gulp"
  },

‘postinstall’ is the key ‘gulp’ is the script that gets executed after ‘npm link’ and ‘npm install’. The Yeoman generator could have done this automatically but for some reason haven’t.

Post-Install execution after npm link to component library

Post-Install execution after npm link to component library

This way, you are on the safe side. In case the code changes or you unsure execute ‘npm link ‘ again. You get a new fresh build without hoping to the library component folder.

Use ‘npm install’ instead of ‘npm link’

When you have library component and web part next to each other you can execute ‘npm install’ too.

npm install ../corporate-library

Again, the post-install script gets executed to create a fresh build. Besides your ‘package.json’ contains the correct package information too.

npm install to library component

The Microsoft recommended a way to add entries manually has more a decorative than a real purpose. Well, it has to be there, but I doubt the impact other than identifying that an external package is involved in the build process.

Other options are: You create your own private npm registry.

npm install [email protected] --save

Install and library component via a git repo is a second right alternative approach.

npm install https://github.com/StfBauer/corporate-library#master-1.0.0 --save

After the hash in the repo URL, you find the branch name as well as the version number. In the ‘package.json’ this npm install gets added like this.

package.json entry when library component was installed from a git repo

package.json entry when library component was installed from a git repo

Whenever you come later back to your project, you know precisely the origin of the library component. In this case, also the ‘postinstall’ get executed. This post-install is crucial, especially in this scenario. In the SharePoint Framework ‘.gitignore’ excludes the lib folder. For a successful build of the web part project, this folder needs to be there.

NPM version your library components

More general considerations not only specifically to library components. Make yourself familiar with ‘npm version’ this saves you many headaches.

In a previous blog post, I wrote how you could use an NPM Script for this too.

After the first look

After experimenting the first time hands-on with library components, I must say it is a helpful tool for SharePoint developers. It allows easily to deploy reusable libraries.

I still have my doubts about what should go in there, and in the case, I use a CDN for my SharePoint if I ever deploy it this way. The limitations, for now, have multiple versions available can be a challenging venture.

Another option is to deploy directly to a private held Azure CDN which then supports multiple versions and gives better control. As long there is only one company involved that develop SharePoint web parts, it’s easier to handle.

In the long run, I see that danger that too many old library components exist in an environment. Components that aren’t in use anymore or no-one knows where they are in use.

Like I researched in the last couple of weeks a custom written Webpack, Browserify build configuration might also be more efficient. One that allows building reusable core components in a modular way like it is now in the SharePoint Framework.

Approaches like “Hey can I deploy the whole Office UI Fabric as a library component” is also not efficient. Not everything in Office UI Fabric component a web part uses and the build pipeline makes sure only to include the things really in use is included. It is also too much effort to keep everything on the same version.

3 Comments

  1. Thanks for the sharing.

    As an alternative, you can also use any monorepo tool. I personally use pnpm (because of its workspace feature, but also because npm is shamefully slow). Yarn has workspace feature too, and lerna is very common (thought the project is dead).

    The initial setup may be a bit more tricky, but it make things more straightforward when the setup is done.

    Reply

  2. Wouldn’t avoiding npm link be defeating the whole purpose of the SPFX library. SPFX library is meant to cut down on the number of dependencies. So, for instance, you have 5 different web parts. If they all referencing same third party components essentially it would load that 5 different times. SPFX library is meant to reduce that so it will only reference that third party component once. If you are adding it as a npm install dependency I would imagine that adding the 5 web parts to the page would load the spfx library five separate times. I’m going off theory here but I think that is the reason why you should not reference it as a npm install.

    Reply

    • To be honest there is no purpose of library components. You can only deploy one library component and version at a time. Like you mentioned you always need to make sure that all web parts running on the same version. So you might be constantly upgrading. Create a dedicated NPM package for your library components, you could put the output on a CDN in a dedicated version. So you can introduce new features for one web part while the other still are allowed to run on an older version.
      Web Part 1, 2 and 4 – reference from version 1.0
      Web Part 3 and 5 – reference from version 1.1

      Makes it easier and better to maintain. So you basically are more flexible and safer and you only load each library once.

      Reply

Leave a Reply

Required fields are marked *.


This site uses Akismet to reduce spam. Learn how your comment data is processed.