Replacing lodash with lodash-es for Tree-Shaking

Symptom you will see: after switching every lodash call site to named imports — import { debounce, cloneDeep } from 'lodash' — and re-running a production build, the bundle analyzer treemap still shows a single lodash block of roughly 71 KB minified. webpack --json=stats.json piped through a quick jq filter for usedExports reports an empty array for nearly every export, yet the module survives the build unchanged:

Module: node_modules/lodash/lodash.js
Size: 71.4 KB
usedExports: []
sideEffects: null
Reason: "harmony import specifier" resolved to CommonJS exports object

The change felt like it should have worked — named imports are exactly the syntax tree-shaking relies on elsewhere in the codebase — but the underlying package format never changed, so nothing about the bundler’s analysis changed either.

This is a common trap because the fix looks complete from the application code’s perspective: every ESLint rule passes, the import statements read cleanly, and TypeScript resolves the types correctly. The problem is invisible until you specifically go looking for it in a bundle analyzer report or a stats.json dump, which is why teams frequently discover it weeks or months after the “fix” shipped, usually while investigating an unrelated performance regression.

Root cause: named imports don’t change what lodash actually exports

This is a specific instance of the whole-library retention problem covered in the optimizing lodash and utility library imports cluster: import { debounce } from 'lodash' is syntactic sugar that Webpack 5 and Rollup translate into “read the debounce property off whatever lodash.js’s module.exports resolves to at runtime.” The syntax looks like a named ES module import, but the target module is still CommonJS underneath — lodash/lodash.js contains a single object literal with every method attached as a property, built by a script that concatenates all ~300 individual method files into one file for npm’s main field.

Static analysis can only track exports that are declared with the export keyword at the top level of a module. A module.exports.debounce = debounce assignment inside a function body, or an object literal with dozens of properties, provides no such guarantee — the analyzer would need to execute the module to know for certain which properties exist and which are read, and neither Webpack 5 nor Rollup executes code during the analysis pass. This is the same static-analysis boundary discussed in converting CJS libraries to ESM for better bundling: the fix is never to change how you write the import statement, but to change what package format the import statement resolves to.

lodash-es solves this by shipping the exact same method implementations as individual files, each with a real export default statement:

// node_modules/lodash-es/debounce.js (simplified)
function debounce(func, wait, options) {
  // ... implementation ...
}
export default debounce;
// node_modules/lodash-es/lodash.default.js (simplified — the namespace re-export)
export { default as debounce } from './debounce.js';
export { default as cloneDeep } from './cloneDeep.js';
// ... one export line per method

Because each re-export line references a single, statically resolvable file, the bundler can trace import { debounce } from 'lodash-es' all the way to debounce.js and stop there — no other method file needs to be included, no shared exports object needs to be preserved.

Exact migration steps

1. Swap the dependency

# Remove the CommonJS package, install the ESM equivalent
npm uninstall lodash
npm install lodash-es

If TypeScript types are needed and not already covered by lodash-es’s own .d.ts files, install the community types package as well:

# Only needed if lodash-es does not ship its own types for your version
npm install --save-dev @types/lodash-es

2. Rewrite every import statement

A project-wide find-and-replace handles the common cases, but destructured imports and default-namespace imports need different treatment:

// Before — either form retains the full CJS module
import _ from 'lodash';
import { debounce, cloneDeep } from 'lodash';

// After — named imports from lodash-es resolve to individual files
import { debounce, cloneDeep } from 'lodash-es';

Watch specifically for a lingering default/namespace import used for chaining:

// This still requires lodash-es's full method set — chaining cannot be partial
import lodash from 'lodash-es';
const total = lodash(items).filter(Boolean).map(x => x.value).sum();

Rewrite chains as direct calls before or during the migration, since chaining defeats tree-shaking under either package:

// After — direct calls only pull in filter, map, and sum
import { filter, map, sum } from 'lodash-es';
const total = sum(map(filter(items, Boolean), x => x.value));

3. Add a resolve.alias safety net

Even after a thorough migration, a transitive dependency or a future PR can reintroduce a lodash import. Aliasing lodash to lodash-es at the bundler level catches this automatically:

// webpack.config.js — Webpack 5
const path = require('path');

module.exports = {
  resolve: {
    alias: {
      lodash: 'lodash-es'
    }
  }
};
// vite.config.ts — Vite 5+
import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    alias: {
      lodash: 'lodash-es'
    }
  }
});

Be aware that this alias only helps when the stray import uses named exports (import { get } from 'lodash'). A stray import _ from 'lodash' namespace import still forces retention of the full lodash-es method set once aliased, because the namespace object needs every property available. The alias converts a namespace-import mistake from “71 KB of CJS lodash” to “the same ~71 KB total across lodash-es’s method files, now split into many small chunks” — better for caching, but not a substitute for fixing the import itself.

4. Fix the Jest transform mismatch

Jest’s default configuration only transpiles files inside your own source directories; node_modules is assumed to be pre-compiled CommonJS and is skipped. lodash-es ships raw ES module syntax, so any test file that imports it directly — or imports a component that imports it — fails with a parse error:

SyntaxError: Unexpected token 'export'
  at node_modules/lodash-es/debounce.js:1

The fix is a transformIgnorePatterns override that excludes lodash-es from the default skip pattern:

// jest.config.js — allow Babel to transpile lodash-es specifically
module.exports = {
  transformIgnorePatterns: [
    'node_modules/(?!(lodash-es)/)'
  ],
  transform: {
    '^.+\\.js$': 'babel-jest'
  }
};

An alternative that avoids adding a transform step entirely is mapping lodash-es back to lodash inside the test environment only, since the CJS package parses natively under Jest’s default CommonJS runtime and functional behaviour is identical:

// jest.config.js — alias lodash-es to lodash inside tests only
module.exports = {
  moduleNameMapper: {
    '^lodash-es$': 'lodash'
  }
};

This second approach means your production bundle tree-shakes via lodash-es while your test runtime quietly uses the CJS package — acceptable because Jest never contributes to the shipped bundle, and the method implementations are functionally identical between the two packages.

5. Handle Babel/TypeScript transpilation targets

If the build pipeline transpiles to a CommonJS module target for any reason (a legacy server-side rendering bundle, for instance), confirm the transpiler is not converting lodash-es’s ES module syntax back into a form that re-triggers whole-module retention. Setting "module": "esnext" in tsconfig.json for the client build (while keeping a separate server tsconfig with "module": "commonjs") keeps the two pipelines independent:

// tsconfig.json — client build preserves ESM for tree-shaking
{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler",
    "target": "ES2020"
  }
}

Step-by-step verification checklist

  1. Confirm zero remaining references to the old package. grep -rn "from 'lodash'" src/ --include="*.{js,jsx,ts,tsx}" should return no results (excluding any intentional test-only alias comment).
  2. Rebuild and regenerate the analyzer report. Run the production build and open the treemap; lodash-es should appear as several small named files (debounce.js, cloneDeep.js, etc.), not one 71 KB block.
  3. Measure the byte delta directly. npx size-limit --compare against a pre-migration baseline should show a reduction in the 60–90% range for any chunk that previously imported the lodash namespace.
  4. Run the full test suite, watching specifically for the Jest CJS/ESM error signature above — this is the most common regression in the migration.
  5. Grep for chaining syntax (_(, .value()) across the codebase and confirm each instance was rewritten to direct calls, since chains silently defeat the migration’s benefit even when everything else is correct.
  6. Check the resolve.alias entry resolves correctly by running webpack --stats-modules or Vite’s dependency inspector and confirming any remaining bare lodash import path physically resolves into node_modules/lodash-es.
  7. Add a size-limit budget for the migrated chunk so a regression fails CI rather than shipping.

Edge cases and gotchas

Gotcha 1 — lodash/fp has no direct lodash-es equivalent

Projects using lodash/fp (the auto-curried, immutable variant) cannot simply alias to lodash-es/fp without checking behavior differences — argument order and currying defaults differ subtly between the two variants in a handful of methods (assoc, merge). Test coverage around any lodash/fp call site is essential before switching; do not rely on the alias alone.

Gotcha 2 — a dependency pinned to an old lodash version blocks deduplication

If a UI library in the dependency tree pins lodash@^3 internally while your application uses lodash-es@^4, resolve.dedupe (Vite) or resolve.alias (Webpack) cannot safely merge them — the API surfaces differ enough between major versions that forcing one physical install risks runtime breakage in the third-party code. Run npm ls lodash to check for version splits before applying any alias, and leave the transitive lodash@3 copy alone if a mismatch is present.

Gotcha 3 — server-side rendering bundles re-introduce the CJS problem

A Node.js SSR bundle that targets a CommonJS output format may resolve lodash-es’s package.json exports map back to a CJS-compatible build if one is present, silently undoing the migration for the server bundle specifically while the client bundle remains correctly tree-shaken. Verify server bundle size separately from the client bundle after migrating — the two pipelines can diverge without any error being raised.

Gotcha 4 — bundling lodash-es for a legacy browser target reintroduces retention

Transpiling lodash-es down to an ES5-compatible target as part of a broad @babel/preset-env browserslist pass can, depending on plugin configuration, rewrite export/import statements into CommonJS exports/require calls before the bundler’s tree-shaking pass runs. If a production build targeting older browsers shows the same single-block retention pattern as the original lodash package, check whether @babel/plugin-transform-modules-commonjs is being applied to node_modules — it should be scoped to first-party source only, with node_modules (including lodash-es) left in ES module form for the bundler to shake before any Babel transform touches it.

FAQ

Why does the bundle analyzer still show lodash as one block after I switched to named imports?

Named imports from the original lodash package do not change how the package is built — it is still one CommonJS module with every method attached to a shared exports object. The bundler cannot statically determine which properties you use, so it retains the whole file regardless of your import syntax. Switching the package to lodash-es, not just changing the import statement, is what fixes it.

Do I need resolve.alias if I’ve replaced every lodash import with lodash-es?

It is a safety net rather than a strict requirement. If every first-party import statement has been migrated, resolve.alias mainly guards against a transitive dependency or a future contributor accidentally reintroducing import _ from 'lodash'. Many teams keep the alias permanently as a lint-free enforcement mechanism.

Why does Jest throw SyntaxError: Unexpected token ‘export’ after switching to lodash-es?

Jest’s default transform pipeline skips node_modules, assuming packages there are pre-compiled CommonJS. lodash-es ships untranspiled ES module syntax, which Node’s CommonJS-based Jest runtime cannot parse without help. Add an exception to transformIgnorePatterns so Babel or ts-jest processes lodash-es specifically.

More in this section

Tree-Shaking Icon Libraries and Large UI Kits Optimizing lodash and Utility Library Imports