|
| 1 | +--- |
| 2 | +id: per-method-packages |
| 3 | +title: Lodash per method packages |
| 4 | +layout: default |
| 5 | +--- |
| 6 | + |
| 7 | +<section> |
| 8 | + <h1>Per Method Packages</h1> |
| 9 | + <p> |
| 10 | + Lodash methods are available in standalone <a href="https://www.npmjs.com/browse/keyword/lodash-modularized">per method packages</a> |
| 11 | + like <code>lodash.mapvalues</code>, <code>lodash.pickby</code>, etc. |
| 12 | + These packages contain only the code the method depends on. |
| 13 | + </p> |
| 14 | + <p> |
| 15 | + <strong> |
| 16 | + However, use of these packages is discouraged and they <a href="https://github.com/lodash/lodash/issues/3838#issuecomment-398592530">will be removed in v5</a>. |
| 17 | + </strong> |
| 18 | + </p> |
| 19 | + <p> |
| 20 | + Although they may seem more lightweight, they will usually increase the size of |
| 21 | + <code>node_modules</code> and webpack/rollup bundles in a project that |
| 22 | + transitively depends on multiple per method packages and/or the main |
| 23 | + <code>lodash</code> package. Whereas many methods in the main |
| 24 | + <code>lodash</code> package share code, the per method packages internally |
| 25 | + bundle copies of any code they depend on. |
| 26 | + </p> |
| 27 | + <p> |
| 28 | + For example, <code>throttle</code> uses <code>debounce</code> internally. |
| 29 | + In a project using both methods from the main <code>lodash</code> package, |
| 30 | + <code>throttle</code> will import the same <code>debounce</code> module as |
| 31 | + any code that imports <code>debounce</code> directly, so only one copy of |
| 32 | + <code>debounce</code> will wind up in a webpack bundle. |
| 33 | + </p> |
| 34 | + <p> |
| 35 | + On the other hand, if a project imports <code>throttle</code> from |
| 36 | + <code>lodash.throttle</code>, the extra copy of the <code>debounce</code> |
| 37 | + code internally bundled into <code>lodash.throttle</code> will wind |
| 38 | + up in the webpack bundle, in addition to <code>debounce</code> from the main |
| 39 | + <code>lodash</code> package or <code>lodash.debounce</code>. |
| 40 | + </p> |
| 41 | +</section> |
| 42 | + |
| 43 | +<section> |
| 44 | + <h2>But <code>lodash</code> isn't lightweight enough!</h2> |
| 45 | + <p> |
| 46 | + Don't worry—if you import or require methods |
| 47 | + directly, e.g. <code>const throttle = require('lodash/throttle')</code>, only |
| 48 | + the subset of lodash code your package uses will be bundled |
| 49 | + in projects that use your package. |
| 50 | + </p> |
| 51 | + <p> |
| 52 | + If importing this way seems cumbersome, you can use |
| 53 | + <a href="https://github.com/lodash/babel-plugin-lodash"><code>babel-plugin-lodash</code></a> |
| 54 | + to transform named top-level imports like |
| 55 | + <code>import { throttle, debounce } from 'lodash'</code> into direct import statements. |
| 56 | + </p> |
| 57 | + <p> |
| 58 | + Furthermore, modern tree-shaking bundlers like webpack and rollup can avoid |
| 59 | + bundling code you don't need even if you don't use direct imports or the babel plugin. |
| 60 | + </p> |
| 61 | +</section> |
| 62 | + |
| 63 | +<section> |
| 64 | + <h2>Migrating to the main <code>lodash</code> package</h2> |
| 65 | + <p> |
| 66 | + A <a href="https://github.com/jcoreio/jscodeshift-replace-lodash-method-packages">jscodeshift transform</a> is available to convert per method package imports |
| 67 | + to main <code>lodash</code> package imports. |
| 68 | + </p> |
| 69 | + <p> |
| 70 | + </p> |
| 71 | +</section> |
0 commit comments