{"componentChunkName":"component---src-templates-blog-js","path":"/blog/2020/09/22/introducing-the-new-jsx-transform.html","result":{"data":{"markdownRemark":{"html":"

Although React 17 doesn’t contain new features, it will provide support for a new version of the JSX transform. In this post, we will describe what it is and how to try it.

\n

What’s a JSX Transform?

\n

Browsers don’t understand JSX out of the box, so most React users rely on a compiler like Babel or TypeScript to transform JSX code into regular JavaScript. Many preconfigured toolkits like Create React App or Next.js also include a JSX transform under the hood.

\n

Together with the React 17 release, we’ve wanted to make a few improvements to the JSX transform, but we didn’t want to break existing setups. This is why we worked with Babel to offer a new, rewritten version of the JSX transform for people who would like to upgrade.

\n

Upgrading to the new transform is completely optional, but it has a few benefits:

\n\n

This upgrade will not change the JSX syntax and is not required. The old JSX transform will keep working as usual, and there are no plans to remove the support for it.

\n

React 17 RC already includes support for the new transform, so go give it a try! To make it easier to adopt, after React 17 is released, we also plan to backport its support to React 16.x, React 15.x, and React 0.14.x. You can find the upgrade instructions for different tools below.

\n

Now let’s take a closer look at the differences between the old and the new transform.

\n

What’s Different in the New Transform?

\n

When you use JSX, the compiler transforms it into React function calls that the browser can understand. The old JSX transform turned JSX into React.createElement(...) calls.

\n

For example, let’s say your source code looks like this:

\n
import React from 'react';\n\nfunction App() {\n  return <h1>Hello World</h1>;\n}
\n

Under the hood, the old JSX transform turns it into regular JavaScript:

\n
import React from 'react';\n\nfunction App() {\n  return React.createElement('h1', null, 'Hello world');\n}
\n
\n

Note

\n

Your source code doesn’t need to change in any way. We’re describing how the JSX transform turns your JSX source code into the JavaScript code a browser can understand.

\n
\n

However, this is not perfect:

\n\n

To solve these issues, React 17 introduces two new entry points to the React package that are intended to only be used by compilers like Babel and TypeScript. Instead of transforming JSX to React.createElement, the new JSX transform automatically imports special functions from those new entry points in the React package and calls them.

\n

Let’s say that your source code looks like this:

\n
function App() {\n  return <h1>Hello World</h1>;\n}
\n

This is what the new JSX transform compiles it to:

\n
// Inserted by a compiler (don't import it yourself!)\nimport {jsx as _jsx} from 'react/jsx-runtime';\n\nfunction App() {\n  return _jsx('h1', { children: 'Hello world' });\n}
\n

Note how our original code did not need to import React to use JSX anymore! (But we would still need to import React in order to use Hooks or other exports that React provides.)

\n

This change is fully compatible with all of the existing JSX code, so you won’t have to change your components. If you’re curious, you can check out the technical RFC for more details about how the new transform works.

\n
\n

Note

\n

The functions inside react/jsx-runtime and react/jsx-dev-runtime must only be used by the compiler transform. If you need to manually create elements in your code, you should keep using React.createElement. It will continue to work and is not going away.

\n
\n

How to Upgrade to the New JSX Transform

\n

If you aren’t ready to upgrade to the new JSX transform or if you are using JSX for another library, don’t worry. The old transform will not be removed and will continue to be supported.

\n

If you want to upgrade, you will need two things:

\n\n

Since the new JSX transform doesn’t require React to be in scope, we’ve also prepared an automated script that will remove the unnecessary imports from your codebase.

\n

Create React App

\n

Create React App support has been added and will be available in the upcoming v4.0 release which is currently in beta testing.

\n

Next.js

\n

Next.js v9.5.3+ uses the new transform for compatible React versions.

\n

Gatsby

\n

Gatsby v2.24.5+ uses the new transform for compatible React versions.

\n
\n

Note

\n

If you get this Gatsby error after upgrading to React 17.0.0-rc.2, run npm update to fix it.

\n
\n

Manual Babel Setup

\n

Support for the new JSX transform is available in Babel v7.9.0 and above.

\n

First, you’ll need to update to the latest Babel and plugin transform.

\n

If you are using @babel/plugin-transform-react-jsx:

\n
# for npm users\nnpm update @babel/core @babel/plugin-transform-react-jsx
\n
# for yarn users\nyarn upgrade @babel/core @babel/plugin-transform-react-jsx
\n

If you are using @babel/preset-react:

\n
# for npm users\nnpm update @babel/core @babel/preset-react
\n
# for yarn users\nyarn upgrade @babel/core @babel/preset-react
\n

Currently, the old transform ("runtime": "classic") is the default option. To enable the new transform, you can pass {"runtime": "automatic"} as an option to @babel/plugin-transform-react-jsx or @babel/preset-react:

\n
// If you are using @babel/preset-react\n{\n  \"presets\": [\n    [\"@babel/preset-react\", {\n      \"runtime\": \"automatic\"\n    }]\n  ]\n}
\n
// If you're using @babel/plugin-transform-react-jsx\n{\n  \"plugins\": [\n    [\"@babel/plugin-transform-react-jsx\", {\n      \"runtime\": \"automatic\"\n    }]\n  ]\n}
\n

Starting from Babel 8, "automatic" will be the default runtime for both plugins. For more information, check out the Babel documentation for @babel/plugin-transform-react-jsx and @babel/preset-react.

\n
\n

Note

\n

If you use JSX with a library other than React, you can use the importSource option to import from that library instead — as long as it provides the necessary entry points. Alternatively, you can keep using the classic transform which will continue to be supported.

\n
\n

ESLint

\n

If you are using eslint-plugin-react, the react/jsx-uses-react and react/react-in-jsx-scope rules are no longer necessary and can be turned off or removed.

\n
{\n  // ...\n  \"rules\": {\n    // ...\n    \"react/jsx-uses-react\": \"off\",\n    \"react/react-in-jsx-scope\": \"off\"\n  }\n}
\n

TypeScript

\n

TypeScript supports the JSX transform in v4.1 beta.

\n

Flow

\n

Flow supports the new JSX transform in v0.126.0 and up.

\n

Removing Unused React Imports

\n

Because the new JSX transform will automatically import the necessary react/jsx-runtime functions, React will no longer need to be in scope when you use JSX. This might lead to unused React imports in your code. It doesn’t hurt to keep them, but if you’d like to remove them, we recommend running a “codemod” script to remove them automatically:

\n
cd your_project\nnpx react-codemod update-react-imports
\n
\n

Note

\n

If you’re getting errors when running the codemod, try specifying a different JavaScript dialect when npx react-codemod update-react-imports asks you to choose one. In particular, at this moment the “JavaScript with Flow” setting supports newer syntax than the “JavaScript” setting even if you don’t use Flow. File an issue if you run into problems.

\n

Keep in mind that the codemod output will not always match your project’s coding style, so you might want to run Prettier after the codemod finishes for consistent formatting.

\n
\n

Running this codemod will:

\n\n

For example,

\n
import React from 'react';\n\nfunction App() {\n  return <h1>Hello World</h1>;\n}
\n

will be replaced with

\n
function App() {\n  return <h1>Hello World</h1>;\n}
\n

If you use some other import from React — for example, a Hook — then the codemod will convert it to a named import.

\n

For example,

\n
import React from 'react';\n\nfunction App() {\n  const [text, setText] = React.useState('Hello World');\n  return <h1>{text}</h1>;\n}
\n

will be replaced with

\n
import { useState } from 'react';\n\nfunction App() {\n  const [text, setText] = useState('Hello World');\n  return <h1>{text}</h1>;\n}
\n

In addition to cleaning up unused imports, this will also help you prepare for a future major version of React (not React 17) which will support ES Modules and not have a default export.

\n

Thanks

\n

We’d like to thank Babel, TypeScript, Create React App, Next.js, Gatsby, ESLint, and Flow maintainers for their help implementing and integrating the new JSX transform. We also want to thank the React community for their feedback and discussion on the related technical RFC.

","excerpt":"Although React 17 doesn’t contain new features, it will provide support for a new version of the JSX transform. In this post, we will describe what it is and how to try it. What’s a JSX Transform? Browsers don’t understand JSX out of the box, so most React users rely on a compiler like Babel or TypeScript to transform JSX code into regular JavaScript. Many preconfigured toolkits like Create React App or Next.js also include a JSX transform under the hood. Together with the React 17 release, we…","frontmatter":{"title":"Introducing the New JSX Transform","next":null,"prev":null,"author":[{"frontmatter":{"name":"Luna Ruan","url":"https://twitter.com/lunaruan"}}]},"fields":{"date":"September 22, 2020","path":"content/blog/2020-09-22-introducing-the-new-jsx-transform.md","slug":"/blog/2020/09/22/introducing-the-new-jsx-transform.html"}},"allMarkdownRemark":{"edges":[{"node":{"frontmatter":{"title":"Introducing the New JSX Transform"},"fields":{"slug":"/blog/2020/09/22/introducing-the-new-jsx-transform.html"}}},{"node":{"frontmatter":{"title":"React v17.0 Release Candidate: No New Features"},"fields":{"slug":"/blog/2020/08/10/react-v17-rc.html"}}},{"node":{"frontmatter":{"title":"React v16.13.0"},"fields":{"slug":"/blog/2020/02/26/react-v16.13.0.html"}}},{"node":{"frontmatter":{"title":"Building Great User Experiences with Concurrent Mode and Suspense"},"fields":{"slug":"/blog/2019/11/06/building-great-user-experiences-with-concurrent-mode-and-suspense.html"}}},{"node":{"frontmatter":{"title":"Preparing for the Future with React Prereleases"},"fields":{"slug":"/blog/2019/10/22/react-release-channels.html"}}},{"node":{"frontmatter":{"title":"Introducing the New React DevTools"},"fields":{"slug":"/blog/2019/08/15/new-react-devtools.html"}}},{"node":{"frontmatter":{"title":"React v16.9.0 and the Roadmap Update"},"fields":{"slug":"/blog/2019/08/08/react-v16.9.0.html"}}},{"node":{"frontmatter":{"title":"Is React Translated Yet? ¡Sí! Sim! はい！"},"fields":{"slug":"/blog/2019/02/23/is-react-translated-yet.html"}}},{"node":{"frontmatter":{"title":"React v16.8: The One With Hooks"},"fields":{"slug":"/blog/2019/02/06/react-v16.8.0.html"}}},{"node":{"frontmatter":{"title":"React v16.7: No, This Is Not the One With Hooks"},"fields":{"slug":"/blog/2018/12/19/react-v-16-7.html"}}}]}},"pageContext":{"slug":"/blog/2020/09/22/introducing-the-new-jsx-transform.html"}},"staticQueryHashes":[]}