feat!: transform individual lodash.method package imports (#499)

Author: kyle-johnson

.changeset/bright-colts-try.md

@@ -0,0 +1,9 @@
+---
+"@optimize-lodash/esbuild-plugin": major
+"@optimize-lodash/rollup-plugin": major
+"@optimize-lodash/transform": major
+---
+
+Rewrite ["modularized" lodash packages](https://www.npmjs.com/search?q=keywords%3Alodash-modularized) such as `lodash.isnil` / `lodash.camelcase` / `lodash.clonedeep` to use the standard `lodash` / `lodash-es` packages. This enables tree-shaking of modularized imports for significant size savings.
+
+This feature can be disabled by setting `optimizeModularizedImports` to `false` (it is on by default).

package.json

@@ -6,7 +6,7 @@
   },
   "devDependencies": {
     "@changesets/changelog-github": "0.5.1",
-    "@changesets/cli": "2.27.12"
+    "@changesets/cli": "2.29.7"
   },
   "pnpm": {
     "peerDependencyRules": {

packages/esbuild-plugin/README.md

@@ -12,7 +12,7 @@ _**This is a proof of concept! esbuild loader plugins are "greedy" and need addi
 
 There are [multiple](https://github.com/webpack/webpack/issues/6925) [issues](https://github.com/lodash/lodash/issues/3839) [surrounding](https://github.com/rollup/rollup/issues/1403) [tree-shaking](https://github.com/rollup/rollup/issues/691) 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](https://www.npmjs.com/package/lodash-es) for projects which ship CommonJS and ES builds: the ES build will be transformed to import from `lodash-es`.
+There is also an option to use [lodash-es](https://www.npmjs.com/package/lodash-es) for projects which ship ESM: transform all your `lodash` imports to use `lodash-es` which is tree-shakable.
 
 Versions of this plugin _before_ 3.x did not support Typescript. 3.x and later support Typescript, although Typescript support is considered experimental.
 
@@ -21,6 +21,7 @@ Versions of this plugin _before_ 3.x did not support Typescript. 3.x and later s
 ```javascript
 import { isNil, isString } from "lodash";
 import { padStart as padStartFp } from "lodash/fp";
+import kebabCase from "lodash.kebabcase";
 ```
 
 ### Becomes this output
@@ -29,32 +30,63 @@ import { padStart as padStartFp } from "lodash/fp";
 import isNil from "lodash/isNil.js";
 import isString from "lodash/isString.js";
 import padStartFp from "lodash/fp/padStart.js";
+import kebabCase from "lodash/kebabCase.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.
+While `lodash-es` is not usable in CommonJS modules, some projects only need ESM output or build both CommonJS and ESM outputs.
 
-In this case, you can offer your users the best of both:
+In these cases, you can optimize by transforming `lodash` imports to `lodash-es` imports:
 
 ### Your source input
 
 ```javascript
 import { isNil } from "lodash";
+import kebabCase from "lodash.kebabcase";
 ```
 
 #### CommonJS output
 
 ```javascript
 import isNil from "lodash/isNil.js";
+import kebabCase from "lodash/kebabCase.js";
 ```
 
 #### ES output (with `useLodashEs: true`)
 
 ```javascript
 import { isNil } from "lodash-es";
+import { kebabCase } from "lodash-es";
 ```
 
+## Individual `lodash.*` Method Packages
+
+Imports from individual lodash method packages like `lodash.isnil` or `lodash.flattendeep` are transformed to use the optimized import path of `lodash` or `lodash-es`, consolidating your lodash usage to a single, tree-shakable ESM package.
+
+### Your source input
+
+```javascript
+import isNil from "lodash.isnil";
+import flattenDeep from "lodash.flattendeep";
+```
+
+#### CommonJS output
+
+```javascript
+import isNil from "lodash/isNil.js";
+import flattenDeep from "lodash/flattenDeep.js";
+```
+
+#### ES output (with `useLodashEs: true`)
+
+```javascript
+import { isNil } from "lodash-es";
+import { flattenDeep } from "lodash-es";
+```
+
+Aliased local names are supported (`import checkNull from "lodash.isnil"` becomes `import checkNull from "lodash/isNil.js"`).
+
 ## Usage
 
 _Please see the [esbuild docs for the most up to date info on using plugins](https://esbuild.github.io/plugins/#using-plugins)._
@@ -89,6 +121,15 @@ 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).
 
+### `optimizeModularizedImports`
+
+Type: `boolean`<br>
+Default: `true`
+
+When `true`, imports from individual lodash method packages (e.g., `lodash.isnil`, `lodash.kebabcase`) are transformed to optimized imports from `lodash` or `lodash-es`.
+
+Set to `false` if you need to disable this behavior (prior to 6.x, this transformation did not ooccur).
+
 ## Limitations
 
 ### Default imports are not optimized

packages/esbuild-plugin/src/index.ts

@@ -55,12 +55,19 @@ const isTypescriptPath = (path: string): boolean =>
 export type PluginOptions = {
   useLodashEs?: true;
   appendDotJs?: boolean;
+  /**
+   * Default: true. When true, imports from individual lodash method packages
+   * (e.g., lodash.isnil, lodash.kebabcase) are transformed to optimized imports.
+   * Set to false to disable this behavior.
+   */
+  optimizeModularizedImports?: boolean;
 };
 
 // TODO: filter https://golang.org/pkg/regexp/
 export function lodashOptimizeImports({
   useLodashEs,
   appendDotJs = true,
+  optimizeModularizedImports,
 }: PluginOptions = {}): Plugin {
   const cache = new Map<
     string,
@@ -94,6 +101,7 @@ export function lodashOptimizeImports({
               : wrappedParse,
             useLodashEs,
             appendDotJs,
+            optimizeModularizedImports,
           });
           if (result === UNCHANGED) {
             cache.set(path, { input, output: UNCHANGED });

packages/rollup-plugin/README.md

@@ -3,24 +3,25 @@
 [![npm](https://img.shields.io/npm/v/@optimize-lodash/rollup-plugin)](https://www.npmjs.com/package/@optimize-lodash/rollup-plugin)
 ![node-current](https://img.shields.io/node/v/@optimize-lodash/rollup-plugin)
 ![npm peer dependency version](https://img.shields.io/npm/dependency-version/@optimize-lodash/rollup-plugin/peer/rollup)
-![compatible with Vite 3.x](https://img.shields.io/badge/vite-%3E%3D3.x-blue)
+![compatible with Vite](https://img.shields.io/badge/vite-%3E%3D3.x-blue)
 ![compatible with rolldown](https://img.shields.io/badge/rolldown-compatible-blue)
 [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/kyle-johnson/rollup-plugin-optimize-lodash-imports/main.yml?branch=main)](https://github.com/kyle-johnson/rollup-plugin-optimize-lodash-imports/actions)
 [![license](https://img.shields.io/npm/l/@optimize-lodash/rollup-plugin)](https://github.com/kyle-johnson/rollup-plugin-optimize-lodash-imports/blob/main/packages/rollup-plugin/LICENSE)
 [![Codecov](https://img.shields.io/codecov/c/github/kyle-johnson/rollup-plugin-optimize-lodash-imports?flag=rollup-plugin&label=coverage)](https://app.codecov.io/gh/kyle-johnson/rollup-plugin-optimize-lodash-imports/)
 ![GitHub last commit](https://img.shields.io/github/last-commit/kyle-johnson/rollup-plugin-optimize-lodash-imports)
 
-There are [multiple](https://github.com/webpack/webpack/issues/6925) [issues](https://github.com/lodash/lodash/issues/3839) [surrounding](https://github.com/rollup/rollup/issues/1403) [tree-shaking](https://github.com/rollup/rollup/issues/691) of lodash. Minifiers, even with dead-code elimination, cannot currently solve this problem. Check out the test showing that even with terser as a minifier, [this plugin can still reduce bundle size by 70%](https://github.com/kyle-johnson/rollup-plugin-optimize-lodash-imports/blob/main/packages/rollup-plugin/tests/bundle-size.test.ts) for [an example input](https://github.com/kyle-johnson/rollup-plugin-optimize-lodash-imports/blob/main/packages/rollup-plugin/tests/fixtures/standard-and-fp.js). With this plugin, bundled code output will _only_ include the specific lodash methods your code requires.
+There are [multiple](https://github.com/webpack/webpack/issues/6925) [issues](https://github.com/lodash/lodash/issues/3839) [surrounding](https://github.com/rollup/rollup/issues/1403) [tree-shaking](https://github.com/rollup/rollup/issues/691) of lodash. Minifiers, even with dead-code elimination, cannot currently solve this problem. Check out the test showing [this plugin can reduce bundle size by 70%](https://github.com/kyle-johnson/rollup-plugin-optimize-lodash-imports/blob/main/packages/rollup-plugin/tests/bundle-size.test.ts) for [an example input](https://github.com/kyle-johnson/rollup-plugin-optimize-lodash-imports/blob/main/packages/rollup-plugin/tests/fixtures/standard-and-fp.js) (and that's with a minifier enabled!). 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](https://www.npmjs.com/package/lodash-es) for projects which ship CommonJS and ES builds: the ES build will be transformed to import from `lodash-es`.
+There is also an option to use [lodash-es](https://www.npmjs.com/package/lodash-es) for projects which ship ESM: transform all your `lodash` imports to use `lodash-es` which is tree-shakable.
 
-Note: versions of this plugin prior to 5.x supported NodeJS 12 and Rollup 2.x - 3.x. If you need support for these older versions, please use the 4.x release. [Rollup 4.x contains significant performance improvements](https://github.com/rollup/rollup/releases/tag/v4.0.0) over previous versions and is highly recommended.
+Version 6.x introduces a new feature: imports of ["modularized" lodash packages](https://www.npmjs.com/search?q=keywords%3Alodash-modularized), such as [`lodash.camelcase`](https://www.npmjs.com/package/lodash.camelcase) are rewritten to use optimized imports of `lodash` or `lodash-es`. This can _significantly_ reduce bundle size when using third-party dependencies that require these modularized imports: you no longer have to ship copies of the same lodash functions simply because one comes from `lodash` and another from `lodash.camelcase`. Applying this to [`kebabCase`](https://github.com/kyle-johnson/rollup-plugin-optimize-lodash-imports/blob/a05bd96a451cf2b4eb7065c83bfe25969ab5282a/packages/rollup-plugin/tests/fixtures/mixed-lodash.js) saves ~3.5kB after minification.
 
 ### This input
 
 ```javascript
 import { isNil, isString } from "lodash";
 import { padStart as padStartFp } from "lodash/fp";
+import kebabCase from "lodash.kebabcase";
 ```
 
 ### Becomes this output
@@ -29,32 +30,63 @@ import { padStart as padStartFp } from "lodash/fp";
 import isNil from "lodash/isNil.js";
 import isString from "lodash/isString.js";
 import padStartFp from "lodash/fp/padStart.js";
+import kebabCase from "lodash/kebabCase.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.
+While `lodash-es` is not usable in CommonJS modules, some projects only need ESM output or build both CommonJS and ESM outputs.
 
-In this case, you can offer your users the best of both:
+In these cases, you can optimize by transforming `lodash` imports to `lodash-es` imports:
 
 ### Your source input
 
 ```javascript
 import { isNil } from "lodash";
+import kebabCase from "lodash.kebabcase";
 ```
 
 #### CommonJS output
 
 ```javascript
 import isNil from "lodash/isNil.js";
+import kebabCase from "lodash/kebabCase.js";
 ```
 
 #### ES output (with `useLodashEs: true`)
 
 ```javascript
 import { isNil } from "lodash-es";
+import { kebabCase } from "lodash-es";
 ```
 
+## Individual `lodash.*` Method Packages
+
+Imports from individual lodash method packages like `lodash.isnil` or `lodash.flattendeep` are transformed to use the optimized import path of `lodash` or `lodash-es`, consolidating your lodash usage to a single, tree-shakable ESM package.
+
+### Your source input
+
+```javascript
+import isNil from "lodash.isnil";
+import flattenDeep from "lodash.flattendeep";
+```
+
+#### CommonJS output
+
+```javascript
+import isNil from "lodash/isNil.js";
+import flattenDeep from "lodash/flattenDeep.js";
+```
+
+#### ES output (with `useLodashEs: true`)
+
+```javascript
+import { isNil } from "lodash-es";
+import { flattenDeep } from "lodash-es";
+```
+
+Aliased local names are supported (`import checkNull from "lodash.isnil"` becomes `import checkNull from "lodash/isNil.js"`).
+
 ## Usage
 
 ```javascript
@@ -108,7 +140,7 @@ Set to `false` if you don't want the `.js` suffix added (prior to v3.x, this was
 
 ### `parseOptions`
 
-Type: `Record<string, unknown> |((id: string) => Record<string, unknown>)`<br>
+Type: `Record<string, unknown> | ((id: string) => Record<string, unknown>)`<br>
 Default: `undefined`
 
 If defined as a static object, this is passed to rollup's internal `parse` method. This can be combined with [`jsx.mode`](https://rollupjs.org/configuration-options/#jsx) to enable jsx parsing: `parseOptions: { jsx: true }`
@@ -119,26 +151,18 @@ If defined as a function, it is called with the filename. For instance, opt-in t
 parseOptions: (filename) => filename.endsWith(".jsx") ? { jsx: true } : {}
 ```
 
-## Rolldown Compatibility
+### `optimizeModularizedImports`
 
-For basic use, this plugin "just works" with [Rolldown](https://rolldown.rs/). There is [a small test suite verifying it](https://github.com/kyle-johnson/rollup-plugin-optimize-lodash-imports/tree/main/packages/rollup-plugin/tests/rolldown).
+Type: `boolean`<br>
+Default: `true`
 
-If you're relying on Rolldown to handle ts/tsx internally, you may need to use `parseOptions` to configure `lang` or [other parsing options](https://github.com/rolldown/rolldown/blob/f46e1d61d0de6f1d6c1968f3d20898e43fa3d2d7/packages/rolldown/src/binding.d.cts#L314):
+When `true`, imports from individual lodash method packages (e.g., `lodash.isnil`, `lodash.kebabcase`) are transformed to optimized imports from `lodash` or `lodash-es`.
 
-```javascript
-optimizeLodashImports({
-  // static
-  parseOptions: { lang: "ts" },
-  // or, dynamically by filename
-  parseOptions: (filename) => ({
-    lang: filename.endsWith(".ts") ? "ts" : "js",
-  }),
-});
-```
+Set to `false` if you need to disable this behavior (prior to 6.x, this transformation did not ooccur).
 
 ## Vite Compatibility
 
-This plugin "just works" as a [Vite 3.x plugin](https://vitejs.dev/guide/api-plugin.html#rollup-plugin-compatibility). Simply add it to `plugins` in your [Vite config](https://vitejs.dev/config/):
+This plugin "just works" as a [Vite plugin](https://vitejs.dev/guide/api-plugin.html#rollup-plugin-compatibility). Simply add it to `plugins` in your [Vite config](https://vitejs.dev/config/):
 
 ```javascript
 import { defineConfig } from "vite";
@@ -159,6 +183,23 @@ Example Vite output for a use of [kebabCase](https://lodash.com/docs/4.17.15#keb
 
 A ~23 KiB reduction in compressed size!
 
+## Rolldown Compatibility
+
+For basic use, this plugin "just works" with [Rolldown](https://rolldown.rs/). There is [a small test suite verifying it](https://github.com/kyle-johnson/rollup-plugin-optimize-lodash-imports/tree/main/packages/rollup-plugin/tests/rolldown).
+
+If you're relying on Rolldown to handle ts/tsx internally, you may need to use `parseOptions` to configure `lang` or [other parsing options](https://github.com/rolldown/rolldown/blob/f46e1d61d0de6f1d6c1968f3d20898e43fa3d2d7/packages/rolldown/src/binding.d.cts#L314):
+
+```javascript
+optimizeLodashImports({
+  // static
+  parseOptions: { lang: "ts" },
+  // or, dynamically by filename
+  parseOptions: (filename) => ({
+    lang: filename.endsWith(".ts") ? "ts" : "js",
+  }),
+});
+```
+
 ## Limitations
 
 ### Default imports are not optimized
@@ -191,8 +232,12 @@ export function testX(x) {
 
 The `chain()` method from `lodash` cannot be successfully imported from `"lodash/chain"` without also importing from `"lodash"`. Imports which include `chain()` are _not modified_ and the plugin prints a warning.
 
+## NodeJS 12 and Rollup 2.x / 3.x support
+
+versions of this plugin prior to 5.x supported NodeJS 12 and Rollup 2.x - 3.x. If you need support for these older versions, please use the 4.x release.
+
 ## Alternatives
 
-[`babel-plugin-lodash`](https://www.npmjs.com/package/babel-plugin-lodash) solves the issue for CommonJS outputs and modifies default imports as well. However, it doesn't enable transparent `lodash-es` use and may not make sense for projects using [@rollup/plugin-typescript](https://www.npmjs.com/package/@rollup/plugin-typescript) which don't wish to add a Babel step.
+[`babel-plugin-lodash`](https://www.npmjs.com/package/babel-plugin-lodash) solves the issue for CommonJS outputs and modifies default imports as well. However, it doesn't enable transparent `lodash-es` use and may not make sense for projects using [@rollup/plugin-typescript](https://www.npmjs.com/package/@rollup/plugin-typescript) which don't wish to add a Babel step. It also does not modify modularized package imports (`lodash.isnil`, etc).
 
 Other alternatives include `eslint-plugin-lodash` with the [`import-scope` rule enabled](https://github.com/wix/eslint-plugin-lodash/blob/HEAD/docs/rules/import-scope.md). This works for CommonJS outputs, but may require manual effort to stay on top of imports.

packages/rollup-plugin/package.json

@@ -73,7 +73,7 @@
     "rollup": "4.52.5",
     "ts-jest": "catalog:",
     "typescript": "catalog:",
-    "tsx": "4.20.6"
+    "tsx": "catalog:"
   },
   "dependencies": {
     "@rollup/pluginutils": "^5.1.0",

packages/rollup-plugin/src/index.ts

@@ -25,6 +25,13 @@ export type OptimizeLodashOptions = {
    */
   appendDotJs?: boolean;
 
+  /**
+   * Default: true. When true, imports from individual lodash method packages
+   * (e.g., lodash.isnil, lodash.kebabcase) are transformed to optimized imports.
+   * Set to false to disable this behavior.
+   */
+  optimizeModularizedImports?: boolean;
+
   /**
    * Additional options to pass to rollup's internal parse() function. For example:
    * `{ jsx: true }`
@@ -73,6 +80,7 @@ export const optimizeLodashImports: PluginImpl<OptimizeLodashOptions> = ({
   exclude,
   useLodashEs,
   appendDotJs,
+  optimizeModularizedImports,
   parseOptions,
 }: OptimizeLodashOptions = {}) => {
   const filter = createFilter(include, exclude);
@@ -118,6 +126,7 @@ export const optimizeLodashImports: PluginImpl<OptimizeLodashOptions> = ({
         warn,
         useLodashEs,
         appendDotJs,
+        optimizeModularizedImports,
       });
     },
   };