non-sensical package naming

[ianstormtaylor]

First, let me say that I love Emotion. I think every other CSS-in-JS library should just deprecate themselves and everyone should be using it. I was happy using v9, and even happier with the API direction in v10.

But... that package naming is extremely confusing. I have to look up the docs every time I need to import emotion to remember which package name I'm supposed to be using and what exactly it exports...

Problem description:

Here are all the issues I see:

• emotion — Obviously this package is the older name, before everything was put into a namespace, but it's not clear what it is and why it wasn't moved into the namespace. I don't know of any other projects that use a namespace, but also maintain "core" packages outside the namespace. It's especially confusing because @emotion/core sounds like what emotion got renamed to, but it's very different.

• @emotion/core — For a library that's trying to be rendering-layer-agnostic (which is an amazing goal, thank you!) this name is extremely confusing. If you're trying to figure out which package to use for non-React apps, you're going to assume that @emotion/core is it, but it's not.

• @emotion/styled — This package is well named. It's not the recommended way any more, but it provides a nice migration path from styled-components, so it makes sense to break it off into a separate package.

• @emotion/native — Well, once you get used to the "core" naming issues, you might expect that this package is the same as @emotion/core, but for React native. But you'd be incorrect, because it is actually the native version of @emotion/styled, but there's no indication of that in the name.

• emotion-theming — This one is confusing because for some reason it's also not in the namespace? And to top it off, the word "theming" is strange and hard to spell. (Is it "themeing"? or "theming"? And how is it pronounced? Lots of typos incoming.)

• emotion-server — Again, why is this not namespaced too?

• create-emotion and create-emotion-server — These are also confusing. I assumed they were for bootstrapping projects, but turns out they are for creating custom configurations of Emotion! No other project I know of exposes these as separate packages instead of exposing the internals directly. This is really weird.

Suggested solution:

I think the following renames should be made:

• emotion becomes @emotion/core. This will be an annoying migration, but it's worth it to have everything in the namespace going forward. If you want to avoid the hard migration, you could instead name it @emotion/css which is equally agnostic sounding.

• emotion-theming becomes @emotion/theme, which puts it inside the namespace but also removes the hard to spell aspect of it.

• @emotion/core becomes @emotion/react. Because it is the recommend way to use Emotion with React applications. If the goal is to keep it completely JSX framework-independent, then it could be called @emotion/jsx instead. (But Preact support alone doesn't merit it IMO.)

• @emotion/native becomes @emotion/styled-native. This way it's very clear what it's the native counterpart to. If it's necessary, you could also use @emotion/styled/native, but that would just be an implementation concern if it's required.

• emotion-server becomes @emotion/server. Self explanatory.

• create-emotion is deprecated in favor of exposing a { createEmotion } import from the core package itself. This is the best practice as far as every other library I've seen/used, and it makes it easy for folks to understand the relationship.

• create-emotion-server is deprecated in favor of exposing a { createEmotionServer } from the @emotion/server package itself. Same idea.

You'd end up with a smaller set of understandable packages:

@emotion/core (or @emotion/css)
@emotion/react (or @emotion/jsx)
@emotion/styled
@emotion/styled-native
@emotion/server
@emotion/theme

---

I know some of these renames will be annoying to do once, but it will be seriously worth it for the long term. Right now the naming scheme is completely non-sensical and I'm positive it's driving off users. I can't recommend Emotion to beginners with the current setup because it's just too confusing.

Again, thanks for this library!

[FezVrasta]

emotion is framework agnostic while @emotion/core is for React. But I generally agree the package names are a bit confusing.

[Jarred-Sumner]

As someone who recently got started using emotion, I also found the package naming scheme confusing. I like emotion a lot though.

One thing that continues to trip me up is when to use emotion instead of @emotion/core. Empirically, it seems like the answer is:

"Whenever the thing in @emotion/core doesn't work, fall back to emotion

I also didn't know at first if I should import jsx from @emotion/core or @emotion/jsx. I'm using the babel preset now, so it's not an issue anymore though (sidenote: it would be great if the docs clarified when to use the babel plugin versus the preset)

[kevinSuttle]

I agree 100% with @ianstormtaylor.

Something else I noticed was that there is an emotion-theming package, and inside of @emotion/core there is a ThemeContext export.

emotion/packages/core/src/context.js

Line 11 in eec0e95

export let ThemeContext = React.createContext<Object>({})

[FezVrasta]

@Andarist is this something we could address with v11?

[Andarist]

Maybe - I’m planning to look at it. Gonna add it to v11 milestone

[emmatown]

I just opened #1635 with some proposed name changes that are very close to what is proposed here so I'm going to close this issue, keen to hear to what people think of the proposed changes.

Thanks for opening this issue @ianstormtaylor, I'm sorry it took so long to address.