Simplify external dependency tree and/or documentation

[jyoko]

Feature Request

• I would like to work on this feature!

Is your feature request related to a problem? Please describe.

As demonstrated by this comment and the plan to drop part of core-js support and due to how integral Babel is to parts of the larger Javascript community, I believe the current ways to list Babel's direct external dependencies are insufficient.

Currently, the package.json in this repository's master branch does not have core-js anywhere in it. The Makefile has two lines mentioning it as a reference to internal packages. I linked to the first line, unless your screen height is very small it is likely you can also see the second. If I search the babel organization for Code related to core-js there are 449 results at the time I'm writing this.

Finally, the yarn.lock file externally references core-js-compat. If we look at how Yarn works then we can see that's transparently going to NPM's core-js-compat, which has a homepage going to the same repository as core-js and currently has this issue (edit: see that thread for that project's details; in context with this issue & project, any given external dependency could have this same situation) with unresolved answers about the who/what/how of that project's future.

I believe this project, Babel as a whole, could either be re-architected or documentation could be improved to make Babel's specific external dependencies easier to manage and that this is important for the broader Javascript community, especially mostly-passive users of this project.

Describe the solution you'd like

I am honestly not even a heavy user of Babel, nevermind knowledgeable enough about its specific internals to make any kind of broad architectural suggestion, which is why I didn't check "I would like to work on this feature." I am willing to help with it but I don't have much personal motivation to build it myself in any particular way. Re-designing the way Babel imports external dependencies would be, I believe, an elegant solution to this problem but may be a huge amount of work. For me personally at this time, I now know how to trace this project's dependencies and your choice here will either make my life easier or cause it to stay exactly the same.

Describe alternatives you've considered

I believe documentation can simplify this problem, even with a list of the dependencies and where they can be found in the README(s). The downside is it is still harder to verify that's really what the code does, but if people aren't auditing the code that closely we can assume they're OK taking you at your word anyway! I believe this could be more quickly and accurately done by someone who already works on Babel's internals regularly, which is why I am willing to help but probably not collect all this information myself.

Teachability, Documentation, Adoption, Migration Strategy
If you can, explain how users will be able to use this and possibly write out a version the docs.
Maybe a screenshot or design?

If re-architected, as the simplest possible example, core-js-compat would appear in the package.json or similar files with a clear relationship to the place the actual files are fetched from.

If done as documentation, I believe a literal list is fine, eg:

• core-js-compat in package.json
• something-other-dependency in some other file

The yarn.lock file arguably meets the criteria I'm defining, and in that case I would ask that notes be added to the README.md file in this repository explaining that Yarn is the canonical package manager: I would then know to check those files and how Yarn works. As far as I know NPM is still the standard for NodeJS so package.json is the place I will look initially after the product's own documentation like the readme.

[babel-bot]

Hey @jyoko! We really appreciate you taking the time to report an issue. The collaborators on this project attempt to help as many people as possible, but we're a limited number of volunteers, so it's possible this won't be addressed swiftly.

If you need any help, or just have general Babel or JavaScript questions, we have a vibrant Slack community that typically always has someone willing to help. You can sign-up here for an invite."

[JLHwung]

Currently, the package.json in this repository's master branch does not have core-js anywhere in it.

Note that babel is a monorepo. That said, the top level package.json does not specify babel's dependencies, but the packages which we need to build all babel packages.

Finally, the yarn.lock file externally references core-js-compat

core-js-compat is not an external dependency, it is depended by @babel/preset-env. Similarly the other packages' dependencies are declared in their own package.json.

[jyoko]

core-js-compat is not an external dependency, it is depended by @babel/preset-env.

I would stipulate that core-js-compat as I used it refers to the things downloaded as I described in the original issue text, and that anything namespaced @babel is part of this project. If I have somehow notified the relevant people incorrectly, please let me know how to correctly inform them.

I opened an issue and not a pull request because I do not know the best way to address this situation.

[nicolo-ribaudo]

@jyoko Could you clarify exactly which of the packages in the @babel/ namespace (you can find them at https://github.com/babel/babel/tree/master/packages) has an undeclared dependency on core-js/core-js-compat?

The 449 references you linked are mostly for tests, in snapshot files that aren't executed but compared as if they were strings.

[jyoko]

@nicolo-ribaudo I'm not saying anything has an undeclared dependency, I'm saying that I think for me as a new developer (to Babel) looking at Babel it's unnecessarily indirect for me to see what "Babel" (not pieces of Babel, because I'm unfamiliar with it) pulls in from other places.

I'm not criticizing Babel or the design decisions. The original issue describes how I found out what Babel did and I also could have watched an install to see what it pulled; the code works and people love it and that's great.

For me, the solution to this can be done either in code in multiple ways or it can be documented in multiple ways. As an external observer I think you all generally do a great job and I don't have any idea what the best plan is!

Please let me know if I can clarify anything.

(edited in after original post)

The yarn.lock file arguably meets the criteria I'm defining, and in that case I would ask that notes be added to the README.md file in this repository explaining that Yarn is the canonical package manager: I would then know to check those files and how Yarn works.

[nicolo-ribaudo]

I'm closing this issue since:

1. Babel is a monorepo (which is a common architecture at least in the JS world), so dependencies are not specified in the top-level package.json
2. I have never seen a popular JavaScript project documenting its dependencies. It's easy to go on npm and check there for specific packages.
3. Babel does not depend on core-js, but it provides an opt-in explicit option (it's called corejs) to make the user code depend on it.