I understand that the cjs files are for CommonJS-style require

Yes, those work both in Node and with older bundlers. Root cjs entry (core.cjs.js) is just a proxy file to .dev and .prod because according to findings of the React team accessing process.env in Node is slow and we use it to differentiate production & development paths (where development includes helpful dev-only warnings and similar stuff). You can read about those findings here.

and I am guessing that the .esm.js file is like mjs (for importing)

Yes, those files are used by modern bundlers like webpack@>=2, rollup etc. That suffix is just a convention - has no special meaning otherwise (unlike .mjs from what I read about Node 13).

but what are the differences between the browser and non-browser releases? Is the umd release for legacy environments without modules?

Browser~ files are used by some bundlers by default when bundling for a browser (in example by webpack). Those are used in combination with alias fields, you can read a little bit more about them here. This allows us to prepare a slightly smaller build, destined for browsers, because we can assume the code in it will only ever get executed in browser and we can strip all the code which is just to handle Node.

Is the umd release for legacy environments without modules?

Yes, I would say this is rarely used nowadays.

@Andarist Thanks for the descriptions; perhaps this can be incorporated into the documentation somewhere!

Now another question: When using core via a CDN in the browser with the import statement, which one is most appropriate? Based on your explanations: core.browser.esm.js?

@Andarist Thanks for the descriptions; perhaps this can be incorporated into the documentation somewhere!

This could be documented in http://preconstruct.tools/ - this is a tool which automates generating all of those for us. Would you be willing to prepare a PR for this? 😉

I don't believe we ship such file - the file you have mentioned is the closest but it has dependencies and a browser won't be able to resolve them until things like import maps land in browsers.

Notes for anyone else who finds this issue:

• The preconstruct configuration page documents the Build types

• The spec for the webpack alias field browser is here: defunctzombie/package-browser-field-spec

@Andarist For the PR: you just want me to summarize your comment in https://github.com/emotion-js/emotion/edit/master/packages/core/README.md?

Oh, so there is already documentation around this in preconstruct. That's cool.

I would split this into 2 PRs:

• one for preconstruct - it could include info about why CJS format is coming with 2 extra files (prod & dev) and it could also mention optional browser builds
• one for our documentation - I think this could maybe add a top-level FAQ section with a subsection of "Build types", that would just merely mention using Preconstruct for building and linking to its documentation for more information about build types

@Andarist I still don't understand your meaning regarding the PR. You are much more familiar with this repo than I am, so I'm not sure what you're looking for without provision of:

• direct links to which README files to edit
• organization of information (maybe an outline?)

As to preconstruct - I would edit this one:
https://github.com/preconstruct/preconstruct/blob/294e12c85b892cb905e99de3d82bfcd6b27d9403/site/src/pages/configuration.mdx#build-types

As to in emotion's docs - add FAQ top section in here + "Build types" item. Just follow how other sections are created there. I have never actually edited those files myself, but seems pretty easy - what you list under items maps to a file in that very same directory, doc files are written in mdx - you only need to add a frontmatter with a title on the top.