📝 Docs: Explain *why* each package should be replaced

[JoshuaKGoldberg]

I personally am bought into the idea of dropping bloat from dependencies 😄. But, for folks who're new to this, their first introduction might be a modules/*.md page in this repo. Many of those pages don't really do much to explain why the package in question should be replaced.

For example, glob:

/Users/josh/repos/mocha/lib/cli/lookup-files.js
  10:12  error  "glob" should be replaced with an alternative package. Read more here: https://github.com/es-tooling/module-replacements/blob/main/docs/modules/glob.md  depend/ban-dependencies

https://github.com/es-tooling/module-replacements/blob/main/docs/modules/glob.md just says:

module-replacements/docs/modules/glob.md

Line 3 in 5560f17

Many glob libraries are bloated and have lighter and faster alternatives.

I as a theoretical new user am never actually told: what's so bad about glob?

Suggestion: for each page, including at least glob, mandate at least a sentence or two explaining the problems (perf, size, etc.) of the package in question?

[lukekarrys]

I think this a really good idea.

Related to this, I also think there’s room for a section like “Why you might not want to migrate away from X” for some modules, especially ones that get replaced by core.

I have a few specific examples from my experience that I think could help users make more informed decisions. The goal should be to present information that will increase confidence even if the decision is still to migrate away.

Thinking from a similar perspective of a theoretical new user, they should read these and think “my code is not doing any of that , this is safe to replace”

Here are some rough examples from my experience:

• fs-extra: This library also applies graceful-fs if your code does not need to be resilient to EMFILE errors then it is safe to migrate away. If it does, consider installing and applying graceful-fs yourself.
• rimraf: One of the primary use cases to rimraf is to be resilient to transient EPERM (and similar) errors on Windows. These tend to only happen when removing many files in rapid succession on resource constrained machines. If this is a concern of your code, consider handling these errors manually or sticking with rimraf ¹.

---

Please minimize if this is off-topic. I can also open a new issue if a further discussion around this is warranted.

Footnotes

1. I removed most of the uses of rimraf from npm so it could be dropped as a dependency in favor of core fs methods. I also have a WIP PR for rimraf that increases resiliency on Windows where I test by deleting files in CI in a loop for 30+ minutes. ↩

[43081j]

Fair point!

We haven't yet put much effort into the explanations in each doc. It would be good to expand a little, although some literally are just because they're smaller and/or faster

Mentioning situations where you may not want to migrate is a good idea too

[lukekarrys]

It would be good to expand a little, although some literally are just because they're smaller and/or faster

I singled out the ones that are
mostly replaced by core because those are more likely to be nuanced due to the tradeoffs of what gets implemented in core vs userland.

For ones where there is a new userland dropin(-ish) replacement, I don't think this section would be necessary.

Happy to create a few separate PRs for modules I have experience with if that would be helpful.

[43081j]

sure if you want to have a stab at it, maybe that'll at least give us a PR to discuss. then whatever structure we settle on in that can become the template