@optimize-lodash/esbuild-plugin

Optimize lodash imports with esbuild

This is a proof of concept! esbuild loader plugins are "greedy" and need additional code to enable chaining. If you want something that's proven in production, consider using @optimize-lodash/rollup-plugin.

There are multiple issues surrounding tree-shaking of lodash. Minifiers, even with dead-code elimination, cannot currently solve this problem. With this plugin, bundled code output will only include the specific lodash methods your code requires.

There is also an option to use lodash-es for projects which ship CommonJS and ES builds: the ES build will be transformed to import from lodash-es.

Versions of this plugin before 3.x did not support Typescript. 3.x and later support Typescript, although Typescript support is considered experimental.

This input

import { isNil, isString } from "lodash";
import { padStart as padStartFp } from "lodash/fp";

Becomes this output

import isNil from "lodash/isNil.js";
import isString from "lodash/isString.js";
import padStartFp from "lodash/fp/padStart.js";

useLodashEs for ES Module Output

While lodash-es is not usable from CommonJS modules, some projects use Rollup to create two outputs: one for ES and one for CommonJS.

In this case, you can offer your users the best of both:

Your source input

import { isNil } from "lodash";

CommonJS output

import isNil from "lodash/isNil.js";

ES output (with useLodashEs: true)

import { isNil } from "lodash-es";

Usage

Please see the esbuild docs for the most up to date info on using plugins.

const { lodashOptimizeImports } = require("@optimize-lodash/esbuild-plugin");

require("esbuild").buildSync({
  entryPoints: ["app.js"],
  outfile: "out.js",
  plugins: [lodashOptimizeImports()],
});

Options

useLodashEs

Type: boolean
Default: false

If true, the plugin will rewrite lodash imports to use lodash-es.

*NOTE: be sure esbuild's format: "esm" option is set!*

appendDotJs

Type: boolean
Default: true

If true, the plugin will append .js to the end of CommonJS lodash imports.

Set to false if you don't want the .js suffix added (prior to v2.x, this was the default).

Limitations

Default imports are not optimized

Unlike babel-plugin-lodash, there is no support for optimizing the lodash default import, such as in this case:

// this import can't be optimized
import _ from "lodash";

export function testX(x) {
  return _.isNil(x);
}

The above code will not be optimized, and Rollup will print a warning.

To avoid this, always import the specific method(s) you need:

// this import will be optimized
import { isNil } from "lodash";

export function testX(x) {
  return isNil(x);
}

Alternatives

There aren't a lot of esbuild plugins today.

If you wish to shift the responsibility off to developers, eslint-plugin-lodash with the import-scope rule enabled may help.

Using Rollup? Check out @optimize-lodash/rollup-plugin.

Using Babel? Check out babel-plugin-lodash (it fixes default imports too!).