Lodash is one of those utility classes many JavaScript developers uses. This modern JavaScript utility library delivering modularity, performance & extras. I agree with most of their marketing terms, but you might run in problems in case of performance when you use it the wrong way and bloat up your SPFx packages.

If you think you never used it then maybe you haven’t used it directly, but a lot of npm package utilise this library too. On npmjs.com this package is listed as the most popular package with more than 26 million downloads a month. They all cannot be wrong.

lodash in SPFx

Every new project in SPFx includes ‘lodash’. You find it, in a ReactJS based project, in the component as the following import.

import { escape } from '@microsoft/sp-lodash-subset';

This imported escape function convert a string into HTML entities later in the component. The npmjs description of sp-lodash-subset only mention.

This package provides a custom bundle of lodash for use with the SharePoint Framework’s module loader. To improve runtime performance, it only includes a subset of the essential functions.

Good to know but we don’t know about what subset in this context means or what it includes. A safer bet is to use the official library. In the end, you find my thoughts on this subset.

lodash – the original package – Take 1

To use this package, you have first to install two npm packages to your SPFx project.

npm install --save-dev lodash @types/lodash

Now you have the library and the type definition for the library ready to use. Using the escape method now works the same way as the original included from the project template.

import { escape } from 'lodash';

Be careful to use the code like this. It harms your SPFx package size and load impact of your code.

Package	Stat Size	Parsed	Gzip	Ship bundle overall
sp-lodash-subset	42 bytes	88 bytes	98 bytes	10 kb
lodash	527,84 kb	528,0.5 kb	93 kb	39 kb

The overall package size is around four times larger than the package with the Microsoft subset. The overall library nearly is 0,5 MB in size that transfers to your users.

You might think that putting lodash in a CDN or SPFx library instead. When you use it in a CDN or library component, the size is even more significant increase to around 1.6 Mb. Now you have one explanation why Microsoft internally uses a subset and not the full version.

lodash – the right way to use it – Take 2

This library was well known for bloating your solutions or apps. It has not as many impacts when you use it in NodeJS, but it is not suitable for front end development. Size reduction of this library additional tools was available. Those are not suitable and needed for newer versions of this library or in Webpack 4.

With the Webpack 4 that was coming to SharePoint some versions ago, you can directly only import specific functions.

import { escape } from 'lodash';

So the previous syntax includes nearly the full package still. For target just the escape method, it is recommended to use the following syntax.

import escape from 'lodash/escape';

This simple change in the code reduces the package and download size dramatically. If you also need the ‘isEqual’ method to be able to compare objects you can import this explicitly.

import isEqual from 'lodash/isEqual';

It is not the prettiest thing to code but effective and a simple solution to improve your overall extension or web part. The bundle size is now smaller again.

Package	Stat Size	Parsed	Gzip	Ship bundle overall
sp-lodash-subset	42 bytes	88 bytes	98 bytes	10 kb
lodash	527,84 kb	528,0.5 kb	93 kb	39 kb
lodash/escape	9,22 kb	10,51 kb	3 kb	15 kb

The package size dropped back to 15kb, compared the previous 39kb a vast improvement. Even the parsed size is no down to 10kb instead of 500kb. Still not at the level of the native SPFx version but better.

Why not sp-lodash-subset?

Libraries that don’t have documentation do not exist or are safe to use in your custom code. This rule also applies to API that does not have documentation. Sp-lodash-subset from my point of view can be considered as an internal library any lack of documentation too.

Reference ‘lodash’ correctly is crucial for the performance of your code and in case of package size. You get a good result out of it even you don’t use the subset.

My assumption in case of the subset is that somewhere an SPFx library component deployed to Office 365 that contains some function of lodash.

In any case and from a perspective of supportability of your code. The safer bet is to use the original ‘lodash’ library. Use it properly to use the benefits of the Webpack 4 tree shaking mechanism.

Number 1 rule for performance improvements always is load only the code you need.