-
-
Notifications
You must be signed in to change notification settings - Fork 1.1k
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
The docs have taken a sharp downhill turn with v10 #1059
Comments
I have to agree here. I am a huge fan of this project, but I can imagine looking at v10 with fresh eyes and being too confused to jump in, or deciding to look at other projects. The opposite was true when I saw the first version of the docs circa v6 (or 7?). Intuitive, simple, powerful. |
This is a completely valid criticism. I think we can address a few items to make this better for our users.
This list is obviously not complete and it would be very helpful to point out specific pain points in this issue that are actionable so we can get them addressed. Also, if you see some documentation that is confusing please feel free to open a PR with better wording or general edits. Any changes made to the documentation markdown files is automatically reflected on the site so there is little friction to getting any changes live. I feel like we can all work together to improve these docs. I truely appreciate you calling us out and hope both you and others can help point out specific issues in the docs so they can be addressed. |
I kind of disagree with making the preset the recommended way to use the css prop. The pragma works everywhere whereas a babel preset can't be added in certain places(like create-react-app) and maybe i'm wrong but I think the default should work everywhere. |
Maybe we should have a dedicated |
Yeah, maybe that would be good, I still kind of think the idea of having adding configuration being the default isn't great though but if other people really like it then I won't prevent it from changing. |
One thing I have been looking for is clearer documentation around the use of pseudo classes. I've beed doing the upgrade to version 10 and received an error about |
@jhoffmcd SSR renders style elements as part of the component (so u end up with MANY style elements when SSRing, but that's not a perf issue anyhow). By doing so only SSR just works - it has a caveat though that first child is a style tag and this makes this pseudo selector "unsafe". I agree that it would be good to at least turn this warning off as not everyone is doing SSR. Idea - not sure if possible, but maybe it would be possible to rewrite |
I'm also not a big fan of the new docs/approach. It's probably not a right issue to complain, but I fully agree with @jaredLunde. I've been using emotion for over a year in multiple projects. And I'm a big fan of the library. Because of simplicity of After 40 minutes of reading docs, it seems, that the way to keep this workflow is to use old emotion package (https://emotion.sh/docs/emotion). But it refers on the new version, doesn't have How is v10 simpler than v9?
Defining |
Hmm. Add me to the list of people who love emotion 9 and hate emotion 10. |
@dperetti old APIs (styled etc) are usable in emotion@10 as is without any problems, you basically have to make near to 0 changes when upgrading |
A few things that should be documented:
|
Another suggestion is to help those of us out that are still on v9 docs.
For the core team, I get that tightening up v10 docs is your main priority but a lot of us won't/can't move off of v9 for the moment for a variety of reasons. Still, I can imagine a good chunk is still on v9 and reference the docs daily so I think that supporting v9 users in this transition phase is definitely something to prioritize as well. |
I'm working through this upgrade now on a decently large Gatsby site. I'm stumbling through trying to figure out which packages I do or don't need for which features and it's quite unproductive and frustrating.
|
Im not sure about your other questions though. I would be interested to set up a quick test and see what happens when you use non-jsx methods of rendering components. |
@jhoffmcd Thanks for the response.
I've also had to disable import * as React from "react"
import { css } from "@emotion/core"
const demo = () => (
<div
css={css`
color: hotPink;
`}
>
Hi!
</div>
) In reality, this works fine when using |
I just spent the better part of yesterday migrating several libs from 9 -> 10 and have some notes that answer some of these questions.
|
react-create-app + True;
Non- |
@Andarist it looks like people loved emotion for its simplicity of using I really dislike how this "evolution" changed the way we work with emotion. I tried it in sandbox and it looks like the package itself have become fatty and has dependency to react. Why would I need such dependency in project that is not using react? The only thing I'd like to use is |
If you are not using react then you can just install latest |
@kkwiatkowski I suggest taking a look at these docs which are linked directly from the introduction of the site. |
@Andarist Can you explain your comment about SSR performance?
My understanding is that including all your css in your html generally does have a performance cost - specifically your html file size can increase dramatically and you can lose a lot of caching benefits. If this does apply to the new SSR API a note on performance tradeoffs in the documentation would be helpful. |
Ty @jaredLunde .. Jan 2020, the gaps in the 10 docs are still painfully there and your comment cleared up a ton of problems for us. |
Closing since this issue is pretty stale. Please open a new issue if you find any gaps in the current docs for v11. |
The documentation for v10 needs some work. v10 isn't a small API change, it completely changes the way a user has to interact with the library. I have used
emotion
on all of my projects for over a year so it's not like I'm a newb to this library. If it's hard for me to understand just what is going on I can't imagine the hurdle for actual newcomers.Given the obscure API that comes with this version (
@emotion/core
vsemotion
,jsx
as an used import?This pragma is supposed to be more clear/easy to use than a babel plugin? ), it would be nice if each of these new packages had their own documentation, since apparently they're all completely different. As it stands you have them all randomly strewn about with notes like 'you only need this if...'Grant you I'm coming at this from a place of general negativity because I've disagreed with this direction from the start (gave a thumbs down on your initial proposal for example), but those feelings are compounded by the fact that the migration guide isn't at all clear. It makes suggestions about moving from
emotion
to@emotion/core
but still says elsewhere in the docs you can still useemotion
. OK. Well, when should I use each? Why should I use@emotion/core
overemotion
? What am I missing out on by not doing so?I really hope this issue with the docs gets ironed out. I'd help, but clearly I don't understand the API as it is so I don't have anything to offer. The only concrete suggestions I have are that you create completely separate sites for
emotion
and@emotion/core
and highlight whatever the differences are somewhere in addition to explaining more clearly whatjsx
is for. Some more clarity about the newcss
prop usage would also be nice.The text was updated successfully, but these errors were encountered: