search

emotion-js / emotion

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

RFC: Package renaming #1635

Closed emmatown closed 4 years ago

emmatown commented 4 years ago

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 commented 4 years ago

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

Andarist commented 4 years ago

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.

emmatown commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

Most of them seem like good changes to me!

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

emmatown commented 4 years ago

@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 commented 4 years ago

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:

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 commented 4 years ago

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

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

defusioner commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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

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

...and compose-able:

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

Container.tsx image

Container.css.ts image

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 commented 4 years ago

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 commented 4 years ago

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.