Expand the explanation on what the plugin actually is doing

[fatso83]

I have some problems understanding what this plugin actually does and how. And especially how to use it safely! I think the README might benefit from expanding on this.

This is what I can see from the tiny text in the all-too-quick GIF:

1. a default build is made using lodash and webpack that is 23KB
2. a build using the lodash babel plugin (to help tree-shaking) brings the build down to 5KB
3. modifying the last build to use the lodash webpack plugin brings the build down to an incredible 0.8KB.

If I were to see something trimming down our builds by 29x I'd be quite worried if this still works in the same way. Which brings me to the safety disclaimer:

DISCLAIMER: Using this plugin without enabling the proper feature sets may cause lodash functions to behave in unexpected ways. Methods may appear to work, however they might return incorrect results.

Obviously, things can go wrong by using this plugin. Unit tests are run on the code before this transformation, so they won't help, but luckily we do have E2E GUI tests for some degree of build verification. Still, did we cover all the branches?

At first, I assumed it would just noop the functions that weren't in use, but since the example gif uses this in combination with tree shaking, I assume the functions that are left to be worked on by this plugin are the ones in actual use. And if they are in use by my code, wouldn't using this plugin guarantee that things would break/work differently?

What I fail to see is how I can deterministically make my program works as intended by enabling the features I need. Thing is, how can I know which methods will be removed. Sentences like "for methods like", "& other edge cases" makes me a bit wary, as it means there is no defined list of methods that will be affected by removing a certain feature.

To me, this plugin seems like a unsafe alternative you use when tree-shaking can't be done. I guess I'm missing something ...

Main points

1. There should be some transformation examples, along the lines of what babel-plugin-lodash has to functionally show what is happening
2. Some guide lines on how to analyze your program for features that seem "safe" to remove.
3. A section or example on code that could end up giving false results. "Don't do this:".

I usually step-it-up by making a pull request when I have an issue, but in this case I'm a bit lost.

[jdalton]

Hi @fatso83!

If you'd like to tweak the readme feel free to open a PR. You should ideally run your unit tests after this transform (on the final generated bundle of your code).