Emotion: RFC: Package renaming

[mitchellhamilton]

To reduce the current confusion, I’m proposing that we rename some packages as part of Emotion 11. Below is a summary of what the packages would look like with the renaming, this will likely be in the docs. At the bottom is a summary of the renames.

@emotion/react

Contains the react-specific version of Emotion. use this if you’re using React. Has different functionality and APIs from @emotion/css and doesn’t work the same way under the hood.
Depends on @emotion/cache

@emotion/styled

Contains the styled API, uses @emotion/react under the hood and wraps it with a different API.
Depends on @emotion/react

@emotion/css

Contains a framework agnostic version of Emotion. Has different functionality and APIs from @emotion/react and doesn’t work the same way under the hood.
Depends on @emotion/cache which which can be customised by creating a custom instance at @emotion/css/create-instance

@emotion/cache

A cache used by both of the main Emotion APIs. Can be used to provide a custom cache in @emotion/react with its CacheProvider. To customise the equivalent options for @emotion/css, @emotion/css/create-instance can create another instance of @emotion/css and it accepts
Depended upon by @emotion/react and @emotion/css

@emotion/babel-plugin

A Babel plugin to optimise for all Emotion packages

@emotion/eslint-plugin

ESLint rules for @emotion/css, @emotion/react and @emotion/styled

@emotion/server

Contains APIs for server rendering with @emotion/css. Can also work with @emotion/react if emotion’s cache is passed to @emotion/react’s CacheProvider
Has an optional peer dependency on @emotion/css for when @emotion/server is used directly but it’s an optional so that @emotion/server/create-instance can be used with any cache from @emotion/cache

@emotion/jest

Contains a Jest snapshot serializer and matchers for use with all Emotion packages
Depends on the behaviour of @emotion/cache so it therefore works with @emotion/react and @emotion/css

@emotion/native

Contains the styled API for React Native along with a css function similar to the ones from @emotion/css and @emotion/react except that it returns a React Native style object

@emotion/primitives

Contains the styled API for React Primitives along with a css function similar to the ones from @emotion/css and @emotion/react except that it returns a React Native style object.

@emotion/babel-preset-css-prop

A Babel preset to allow usage of the css prop everywhere without importing it
Uses @emotion/react and @emotion/babel-plugin

Renaming summary

Anything not mentioned here will stay as is:
@emotion/core → @emotion/react
emotion → @emotion/css
emotion-theming → into @emotion/react
emotion-server → @emotion/server
create-emotion → @emotion/css/create-instance
create-emotion-server → @emotion/server/create-instance
babel-plugin-emotion → @emotion/babel-plugin
eslint-plugin-emotion → @emotion/eslint-plugin
jest-emotion → @emotion/jest

[tkh44]

I like it! Should make it much easier to figure out which package to import and whats being imported at a glance.

[Andarist]

Really like it! I'd consider @emotion/vanilla-css in place of @emotion/css for a current emotion package, but I also don't have that much of a problem with @emotion/css.

We'd definitely need codemods for those to ease the migration.

[mitchellhamilton]

I'd consider @emotion/vanilla-css in place of @emotion/css for a current emotion package

I was considering @emotion/vanilla but ended up choosing @emotion/css because @emotion/vanilla kinda implies that it's specifically for vanilla js but it could also be used with another framework so vanilla isn't really correct.

We'd definitely need codemods for those to ease the migration.

💯

[Andarist]

I was considering @emotion/vanilla but ended up choosing @emotion/css because @emotion/vanilla kinda implies that it's specifically for vanilla js but it could also be used with another framework so vanilla isn't really correct.

It's not that it can't be used with any other framework, but rather than it works with everything because it just returns "vanilla" class names 😅 I'm just a little bit worried that people will still be a little bit confused about us having 2 css functions - however those proposed changes make it A LOT easier to understand what is supposed to be used when.

Also - cc @genevieveloreal @geddski - happy to accept your feedback regarding this.

[tkh44]

@Andarist my ultimate goal with v11 is to make @emotion/css and @emotion/react css calls the same and return classNames. @mitchellhamilton and I have been discussing the initial ways of doing this and I think this will ultimately clear up any confusion over naming choices.

The css call should return a className that can be used anywhere and used in composition as well (aka on css prop).

My thinking is that @emotion/css will be the bare bones implementation and that @emotion/react will include the necessary tools for css prop and other react specific features.

[ianstormtaylor]

Most of them seem like good changes to me!

The only two that still aren't clear enough I think are:

• @emotion/native being for the React Native bindings for the Styled Components API isn't clear. I think it should be @emotion/styled-native.

• @emotion/primitives I still don't understand what the package contains, even after reading the description for what it is. Seems it has to do with React Native, but it's not clear.

[mitchellhamilton]

@emotion/native being for the React Native bindings for the Styled Components API isn't clear. I think it should be @emotion/styled-native.

This isn't really true, it also has a css function like @emotion/css/@emotion/react

@emotion/primitives I still don't understand what the package contains, even after reading the description for what it is. Seems it has to do with React Native, but it's not clear.

It's essentially the same as @emotion/native but for react-primitives

[elektronik2k5]

Thanks for working on this! :) Here are some of my thoughts on this subject:

As an Emotion user (and proponent!) I think this calls for a chart/graph/table, because of the sheer amount (14 today and proposed 9 packages in the future!) and partial overlap between the different features, flavors and runtimes.
It's just too much information to represent in a flat textual manner. 🤯

I also think that the docs should mirror that graph and start from a single "get started" entry point, which guides the user according to the target platform/runtime to more specific "recipe" documentation pages. Example: "for RN + RNW, use @emotion/primitives and @emotion/jest. Here's a sample project [link to codesandbox/expo snack]".

In addition, in order to make each package/recipe docs page clearer we can include sections like:

• When to use x?
• What does x do?
• When to not use x?
• What doesn't x do?

As for the proposed names and descriptions themselves:

1. I don't think that the difference between @emotion/react and @emotion/styled is clear.
2. AFAIK, @emotion/babel-plugin doesn't only optimise, but does more than that. And I don't think that "for all Emotion packages" is correct.
3. I'm in favor of @emotion/css over "vanilla" or anything else.
4. Some of the descriptions mention @emotion/core, which doesn't exist in the new scheme.
5. Some of the descriptions mention differences from other packages, but don't actually state what those differences are: "Has different functionality and APIs from other/package and doesn’t work the same way under the hood.".

Thanks again for Emotion and it's continued improvement! :heart:

[FezVrasta]

Shouldn’t it be @emotion/react-styled?

Same for @emotion/native, shouldn't it be @emotion/react-native?

[defusioner]

@tkh44 Am I right when I'm saying that emotion and @emotion/core css functions are two different functions with different return types and if I want to use my component as I was using before (className={css.root}) with emotion, I need to perform some black magic?

P.S.
I see also that if I use emotion-theming package in this classname mode, then I should install @emotion/core separately as emotion-theming uses it and emotion drops it once the lib is in prod (core is the dev dependency)

[Andarist]

If u want to get string class names then just use emotion over @emotion/core. No black magic in that.

Could u specify what's the problem with theming? Preferably with a code sample?

[defusioner]

@Andarist I have a shared components library. Here is one component:

As you can see, I prefer exporting all my styles to a specific file - this makes the code MUCH cleaner...:

• I'm still using a simple css without camelCase css properties and no custom css prop
• This css is scoped that is genius

...and compose-able:

• lets me to use string classes with material-ui
• lets me to use classnames package.

So finally I have a concept mix of css modules but I write a simple css wrapper with css function.

Container.tsx

Container.css.ts

I have always a ThemeProvider that implements emotions theme provider.

It works until I build my lib (simple typescript command) and publish to our nexus repository.

Why?

emotion-theming uses @emotion/core as a dev dependency. From the application side I ask these peer dependencies: emotion, emotion-theming, but not core.

When I use one of my lib's components, I get @emotion/core is not resolved.

So actually I'm installing both core and emotion packages and it works.

Should it be like that?

[geddski]

I'm very glad to see this being discussed! I like the move of everything into @emotion/ namespace. I do think there are still too many packages though. GSAP library used to have this same problem - it wasn't obvious when to use TweenMax or TweenLite or TimelineMax etc. In v3 they simplified everything into a single gsap package.

Maybe emotion could do something similar? @emotion/react-native, @emotion/web. Just a thought. In any case I'm glad to see improvement here. Y'all rock.

[Andarist]

Renaming of packages got merged in v11 and newly named packages should be promptly available on npm as well. v11 has not been yet published as latest, but we are getting closer and closer to it.