diff --git a/docs/babel.md b/docs/babel.md index 21262b531..d69756c81 100644 --- a/docs/babel.md +++ b/docs/babel.md @@ -26,6 +26,10 @@ Uglifyjs will use the injected `/*#__PURE__*/` flag comments to mark your `css` Generated CSS that is eligible for extraction can be moved to an external css file. +> Note: +> +> extractStatic is deprecated and will be removed in emotion@10. We recommend disabling extractStatic or using other libraries like [linaria](https://github.com/callstack-io/linaria) or [css-literal-loader](https://github.com/4Catalyzer/css-literal-loader) + ### Source Maps When enabled, navigate directly to the style declaration in your javascript file. diff --git a/docs/extract-static.md b/docs/extract-static.md index e7daaee90..6a5c12e77 100644 --- a/docs/extract-static.md +++ b/docs/extract-static.md @@ -4,7 +4,15 @@ title: "Extract Static" ###### [requires babel plugin](/docs/babel.md) -The `extractStatic` option to `babel-plugin-emotion` allows you to extract styles with no interpolations into external css files. **`extractStatic` is not recommended** because it **breaks [composition](/docs/composition.md)** and other powerful patterns from libraries like [facepaint](https://github.com/emotion-js/facepaint). It is primarily available for historical reasons. It does not work with object styles. +## DEPRECATED + +extractStatic is deprecated and will be removed in emotion@10. We recommend disabling extractStatic or using other libraries like [linaria](https://github.com/callstack-io/linaria) or [css-literal-loader](https://github.com/4Catalyzer/css-literal-loader). + +### Why is extractStatic being deprecated? + +Static extraction was made for earlier versions of emotion which had a very different architecture to the architecture emotion has today. As emotion has gotten more performant and features such as [composition](/docs/composition.md) have been added, static extraction has become less important. Because most of the community is leveraging the composition and `extractStatic` is rarely used, the time spent maintaining `extractStatic` is much higher than the benefits we get from it. Libraries such as [linaria](https://github.com/callstack-io/linaria) and [css-literal-loader](https://github.com/4Catalyzer/css-literal-loader) do static extraction well and the people working on them are focused on this specific problem. As a team, we believe that projects like [prepack](https://github.com/facebook/prepack), when they are ready, will provide a better and more powerful way to pre-compile styles. + +The `extractStatic` option to `babel-plugin-emotion` allows you to extract styles with no interpolations into external css files. **`extractStatic` is not recommended** because it **breaks [composition](/docs/composition.md)** and other powerful patterns from libraries like [facepaint](https://github.com/emotion-js/facepaint). **If you want to use dynamic values you must use css variables.** diff --git a/packages/babel-plugin-emotion/README.md b/packages/babel-plugin-emotion/README.md index cf87a965e..c3885f0c2 100644 --- a/packages/babel-plugin-emotion/README.md +++ b/packages/babel-plugin-emotion/README.md @@ -60,7 +60,7 @@ above of `emotion`. Uglifyjs will use the injected /*#__PURE__*/ flag comments to mark your css and styled blocks as candidates for dead code elimination. - Static Extraction + Static Extraction (deprecated) ✅ Generated CSS that is eligible for extraction can be moved to an external css file. @@ -351,6 +351,10 @@ const Profile = () => { `boolean`, defaults to `false`. +> Note: +> +> extractStatic is deprecated and will be removed in emotion@10. We recommend disabling extractStatic or using other libraries like [linaria](https://github.com/callstack-io/linaria) or [css-literal-loader](https://github.com/4Catalyzer/css-literal-loader) + This option enables the following: * Extract static styles into CSS files. diff --git a/packages/babel-plugin-emotion/src/index.js b/packages/babel-plugin-emotion/src/index.js index 02ab76ae8..ad7dd5908 100644 --- a/packages/babel-plugin-emotion/src/index.js +++ b/packages/babel-plugin-emotion/src/index.js @@ -410,6 +410,8 @@ function getInstancePathToCompare(instancePath: string, rootPath: string) { return absolutePath } +let warnedAboutExtractStatic = false + export default function(babel: Babel) { const { types: t } = babel @@ -517,6 +519,15 @@ export default function(babel: Babel) { } }) state.cssPropIdentifiers = [] + if (state.opts.extractStatic && !warnedAboutExtractStatic) { + console.warn( + 'extractStatic is deprecated and will be removed in emotion@10. We recommend disabling extractStatic or using other libraries like linaria or css-literal-loader' + ) + // lots of cli tools write to the same line so + // this moves to the next line so the warning doesn't get removed + console.log('') + warnedAboutExtractStatic = true + } state.extractStatic = // path.hub.file.opts.filename !== 'unknown' || state.opts.extractStatic diff --git a/packages/create-emotion-styled/src/index.js b/packages/create-emotion-styled/src/index.js index acab14b0e..264edc832 100644 --- a/packages/create-emotion-styled/src/index.js +++ b/packages/create-emotion-styled/src/index.js @@ -12,6 +12,8 @@ import { setTheme } from './utils' +let warnedAboutExtractStatic = false + function createEmotionStyled(emotion: Emotion, view: ReactType) { let createStyled: CreateStyled = (tag, options) => { if (process.env.NODE_ENV !== 'production') { @@ -71,6 +73,14 @@ function createEmotionStyled(emotion: Emotion, view: ReactType) { styles.push(args[i], args[0][i]) } } + } else if ( + process.env.NODE_ENV !== 'production' && + !warnedAboutExtractStatic + ) { + console.warn( + 'extractStatic is deprecated and will be removed in emotion@10. We recommend disabling extractStatic or using other libraries like linaria or css-literal-loader' + ) + warnedAboutExtractStatic = true } class Styled extends view.Component<*, { theme: Object }> {