Add docs about new JSX factories (#2063)

* Update @emotion/babel-preset-css-prop README to include info about automatic runtime * Explain how to use new JSX factories when explaining CSS prop used automatically with Babel * Add a note about CRA4 and the new jsxImportSource pragma to the docs * Update docs/css-prop.mdx Co-authored-by: Mitchell Hamilton <[email protected]>
emotion-js · Nov 1, 2020 · 6a64cad · 6a64cad
1 parent 71514b0
commit 6a64cad
Show file tree

Hide file tree

Showing 2 changed files with 19 additions and 5 deletions.
diff --git a/docs/css-prop.mdx b/docs/css-prop.mdx
@@ -13,7 +13,7 @@ There are 2 ways to get started with the `css` prop.
 
 Both methods result in the same compiled code.
 After adding the preset or setting the pragma as a comment, compiled jsx code will use emotion's `jsx` function instead of `React.createElement`.
-  
+
 | | Input | Output |
 | ------ | -------------------------- | --------------------------------------------------- |
 | Before | `<img src="avatar.png" />` | `React.createElement('img', { src: 'avatar.png' })` |
@@ -32,6 +32,16 @@ Use the [JSX Pragma](#jsx-pragma) method instead.
 }
 ```
 
+If you are using the compatible React version (`>=16.14.0`) and a compatible version of `@emotion/core` (`>=10.1.0`) then you can opt into using [the new JSX runtimes](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) by using such configuration:
+
+**.babelrc**
+
+```json
+{
+  "presets": [["@emotion/babel-preset-css-prop", { "runtime": "automatic" }]]
+}
+```
+
 > [Full `@emotion/babel-preset-css-prop` documentation](https://emotion.sh/docs/@emotion/babel-preset-css-prop)
 
 #### JSX Pragma
@@ -45,6 +55,8 @@ This option works best for testing out the `css` prop feature or in projects whe
 
 Similar to a comment containing linter configuration, this configures the [jsx babel plugin](https://babeljs.io/docs/en/babel-plugin-transform-react-jsx) to use the `jsx` function instead of `React.createElement`.
 
+If you are using a zero-config tool with automatic detection of which runtime (classic vs. automatic) should be used and you are already using a React version that has [the new JSX runtimes](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) (hence `runtime: 'automatic'` being configured automatically for you) such as Create React App 4 then `/** @jsx jsx */` pragma might not work and you should use `/** @jsxImportSource @emotion/core */` instead. Keep in mind that this also requires a compatible version of `@emotion/core` which is `^10.1.0`.
+
 > [JSX Pragma Babel Documentation](https://babeljs.io/docs/en/babel-plugin-transform-react-jsx#pragma)
 
 #### Import the `jsx` function from `@emotion/core`
@@ -247,4 +259,4 @@ Relying on the css spec's ["Order of Appearance"](https://www.w3.org/TR/css-casc
 
 ## Gotchas
 
-- If you include the plugin `babel-plugin-transform-react-inline-elements` in your `.babelrc` your styles will not be applied. The plugin is not compatible with the `css` prop.
+- If you include the plugin `babel-plugin-transform-react-inline-elements` in your `.babelrc` your styles will not be applied. The plugin is not compatible with the `css` prop.
diff --git a/packages/babel-preset-css-prop/README.md b/packages/babel-preset-css-prop/README.md
@@ -66,14 +66,14 @@ require('@babel/core').transform(code, {
 
 ## Features
 
-This preset enables the `css` prop for an entire project via a single entry to the babel configuration. After adding the preset, compiled jsx code will use emotion's `jsx` function instead of `React.createElement`.
+This preset enables the `css` prop for an entire project via a single entry to the babel configuration. After adding the preset, compiled JSX code will use Emotion's JSX factories instead of the ones provided by React.
 
 |        | Input                      | Output                                              |
 | ------ | -------------------------- | --------------------------------------------------- |
 | Before | `<img src="avatar.png" />` | `React.createElement('img', { src: 'avatar.png' })` |
 | After  | `<img src="avatar.png" />` | `jsx('img', { src: 'avatar.png' })`                 |
 
-`import { jsx } from '@emotion/core'` is automatically added to the top of files where required.
+Import to `@emotion/core`'s appropriate JSX factory is automatically added to the top of files where required.
 
 ## Example
 
@@ -127,7 +127,7 @@ const Link = props =>
   )
 ```
 
-_In addition to the custom pragma, this example includes `babel-plugin-emotion` transforms that are enabled by default._
+_In addition to the custom JSX factory, this example includes `babel-plugin-emotion` transforms that are enabled by default._
 
 ## Options
 
@@ -139,6 +139,8 @@ Options for both `babel-plugin-emotion` and `@babel/plugin-transform-react-jsx`
 >
 > - [`@babel/plugin-transform-react-jsx`](https://babeljs.io/docs/en/next/babel-plugin-transform-react-jsx)
 
+You can opt into [the new JSX runtimes](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) by configuring this preset with `{ runtime: 'automatic' }`. Keep in mind that you have to use compatible React version (`>=16.14.0`) to use this option and a compatible version of `@emotion/core` (`>=10.1.0`).
+
 ### Examples
 
 ```json