emotion-js / emotion

👩‍🎤 CSS-in-JS library designed for high performance style composition
https://emotion.sh/
MIT License
17.52k stars 1.11k forks source link

Clarify documentation around build tooling #2662

Open srmagura opened 2 years ago

srmagura commented 2 years ago

Description:

We get many questions about build tooling and I think we could reduce the confusion around this by improving our docs.

  1. The css-prop.mdx document is still focused on the old JSX runtime, though the new JSX runtime is mentioned. We should shift the focus to the new JSX runtime. (Place more emphasis on @jsxImportSource @emotion/react.)
  2. The documentation should make it obvious how to use Emotion in: a. Create React App / CodeSandbox b. Next.js
  3. The existing documentation on our Babel macros is not very clear about exactly how to use the macro in a Create React App environment.
  4. The existing documentation does not explain what the Babel macro does and if it is essential or just a nice-to-have. a. Does it add support for the css prop? (I don't think so) b. Does it add support for component selectors? c. Is it merely a performance optimization?

Documentation links:

https://emotion.sh/docs/css-prop https://emotion.sh/docs/babel-macros

srmagura commented 2 years ago

@Andarist thoughts on items 1 through 4 in the original post? You can assign to me once answered. Thanks.

Andarist commented 2 years ago
  1. Agreed
  2. This probably should be even moved closer to the beginning of the appropriate sections. Those tools are super popular so I think it makes sense to start by mentioning them and linking to "how to" sections related to them.
  3. If you think this is unclear then we should try to make it more clear - maybe just putting more emphasis on the fact that "it just works" would do the trick there.
  4. it's mostly nice to have 4a. no, CSS prop is a runtime feature, it doesn't require a macro 4b. yes, using components as selectors is a build-time feature and thus it require a babel plugin/macro or some other tool to insert the target option into the appropriate positions in the transformed files 4c. it's mostly a DX improvement as our macros insert labels and source maps