Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify documentation around build tooling #2662

Open
srmagura opened this issue Feb 26, 2022 · 2 comments
Open

Clarify documentation around build tooling #2662

srmagura opened this issue Feb 26, 2022 · 2 comments
Assignees

Comments

@srmagura
Copy link
Contributor

srmagura commented Feb 26, 2022

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 srmagura self-assigned this Feb 26, 2022
@srmagura srmagura assigned Andarist and unassigned srmagura Mar 15, 2022
@srmagura
Copy link
Contributor Author

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

@srmagura srmagura changed the title Clarify documentation around css prop / Create React App / Babel Macros Clarify documentation around build tooling Apr 24, 2022
@Andarist
Copy link
Member

Andarist commented Jun 27, 2022

  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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants