Add more to upgrade guide

2026-02-23 20:23:08 +00:00 · 2024-04-22 01:18:30 -04:00
parent b9d528e3db
commit 7dd208c7b8
1 changed files with 223 additions and 32 deletions
--- a/src/content/blog/2024/04/01/react-19-upgrade-guide.md
+++ b/src/content/blog/2024/04/01/react-19-upgrade-guide.md
@@ -14,6 +14,8 @@ If you'd like to help us test React 19, follow the steps in this upgrade guide a

 </Intro>

+<InlineToc />
+
 <Note>

 React Conf 2024 is scheduled for May 15–16 in Henderson, Nevada!
@@ -36,52 +38,243 @@ Or if you’re using yarn:
 ```bash
 yarn add react react-dom
 ```
+<Note>
+#### New JSX Transform is now required {/*new-jsx-transform-is-now-required*/}

-TODO: Note about jsx transform?
+We introduced a [new JSX transform](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) in 2020 to improve bundle size and use JSX without importing React. In React 19, we're adding additional improvements like using ref as a prop and JSX speed improvements that require the new transform.


-## New JSX Transform {/*new-jsx-transform*/}
+If you haven't already, you will need to enable the new transform in your project. We expect most apps will not be effected since the transform is enabled in most environments already. For manual instructions on how to upgrade, please see the [announcement post](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html).

-TODO: new jsx transform now required
+</Note>
+
+## Removing deprecated React APIs {/*removing-deprecated-react-apis*/}
+
+### Removing PropTypes and DefaultProps {/*removing-proptypes-and-defaultprops*/}
+`PropTypes` were been [deprecated in v15.5.0](https://legacy.reactjs.org/blog/2017/04/07/react-v15.5.0.html#new-deprecation-warnings). 
+
+In React 19, we're removing the PropType checks from the React package, and using them will be silently ignored. If you're using PropTypes, we recommend migrating to TypeScript or another type-checking solution. We're also removing `defaultProps` in place of ES6 default parameters.
+
+```js
+// Before
+import PropTypes from 'prop-types';
+
+function Heading({text}) {
+  return <h1>{text}</h1>;
+}
+Heading.propTypes = {
+  text: PropTypes.string,
+};
+Heading.defaultProps = {
+  text: 'Hello, world!',
+};
+```
+```ts
+// After
+interface Props {
+  text?: string;
+}
+function Heading({text = 'Hello, world!'}: Props) {
+  return <h1>{text}</h1>;
+}
+```
+
+### Removing Legacy Context {/*removing-legacy-context*/}
+
+Legacy Context using `contextTypes` and `getChildContext` was [deprecated in v16.6.0](https://legacy.reactjs.org/blog/2018/10/23/react-v-16-6.html) due to subtle bugs that were easy to miss. In React 19, we're removing Legacy Context to make React slightly smaller and faster.
+
+If you're still using Legacy Context in class components, you'll need to migrate to the new `contextType` API:
+
+```js
+// Before
+import PropTypes from 'prop-types';
+
+class Parent extends React.Component {
+  static childContextTypes = {
+    foo: PropTypes.string.isRequired,
+  };
+
+  getChildContext() {
+    return { foo: 'bar' };
+  }
+
+  render() {
+    return <Child />;
+  }
+}
+
+class Child extends React.Component {
+  static contextTypes = {
+    foo: PropTypes.string.isRequired,
+  };
+
+  render() {
+    return <div>{this.context.foo}</div>;
+  }
+}
+```
+
+```js
+// After
+const FooContext = React.createContext();
+
+class Parent extends React.Component {
+  render() {
+    return (
+      <FooContext value='bar'>
+        <Child />
+      </FooContext>
+    );
+  }
+}
+
+class Child extends React.Component {
+  static contextType = FooContext;
+
+  render() {
+    return <div>{this.context}</div>;
+  }
+}
+```
+
+### Removing string refs {/*removing-string-refs*/}
+String refs were [deprecated in v16.3.0](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html) because they had [multiple downsides](https://github.com/facebook/react/issues/1373). In React 19, we're removing string refs to make React simpler and easier to understand.
+
+If you're still using string refs in class components, you'll need to migrate to ref callbacks:
+
+```js
+// Before
+class MyComponent extends React.Component {
+  componentDidMount() {
+    this.refs['input'].focus();
+  }
+
+  render() {
+    return <input ref='input' />;
+  }
+}
+```
+
+```js
+// After
+// Before
+class MyComponent extends React.Component {
+  componentDidMount() {
+    this.input.focus();
+  }
+
+  render() {
+    return <input ref={input => this.input = input} />;
+  }
+}
+```
+
+<Note>
+
+To help with the migration, we've created a [react-codemod](/todo) that will automatically update your code to use ref callbacks.
+
+TODO: instructions.
+
+</Note>
+
+### Removing module pattern factories {/*removing-module-pattern-factories*/}
+Module pattern factories were [deprecated in v16.9.0](https://legacy.reactjs.org/blog/2019/08/08/react-v16.9.0.html#deprecating-module-pattern-factories) because they were rarely used and supporting it causes React to be slightly larger and slower than necessary. In React 19, we're removing support for module pattern factories, and you'll need to migrate to regular functions:
+
+```js
+// Before
+function FactoryComponent() {
+  return { render() { return <div />; } }
+}
+```
+
+```js
+// After
+function FactoryComponent() {
+  return <div />;
+}
+```
+
+### Removing `createFactory` {/*removing-createfactory*/}
+`createFactory` was [deprecated in v16.13.0](https://legacy.reactjs.org/blog/2020/02/26/react-v16.13.0.html#deprecating-createfactory) because it was rarely used and is replaced by JSX. In React 19, we're removing `createFactory` and you'll need to migrate to JSX:
+
+```js
+// Before
+import { createFactory } from 'react';
+
+const button = createFactory('button');
+```
+
+```js
+// After
+const button = <button />;
+```
+
+## Removing deprecated React DOM APIs {/*removing-deprecated-react-dom-apis*/}


-## Removed APIs {/*removed-apis*/}
-
-In this release we're removing many long-time deprecated APIs:
-
-### React {/*removed-apis-react*/}
- PropTypes 15.5.0
- Legacy context 15.5.0
- Module pattern factories 16.9.0
- String Refs 16.13.0
- createFactory 16.13.0
-
-### React DOM {/*removed-apis-react-dom*/}
- render 18.0.0  
- hydrate 18.0.0   
- unmountComponentAtNode 18.0.0   
- findDOMNode 18.0.0   
- createFactory 16.13.0  
- test-utils 18.3.0   
-
-### react-test-renderer {/*react-test-renderer*/}
+### Removing `ReactDOM.render` {/*removing-reactdom-render*/}

 TODO

-### UMD builds {/*umd-builds*/}
+### Removing `ReactDOM.hydrate` {/*removing-reactdom-hydrate*/}

 TODO

-## Deprecations {/*deprecations*/}
+### Removing `unmountComponentAtNode` {/*removing-unmountcomponentatnode*/}
+
+TODO
+
+### Removing `ReactDOM.findDOMNode` {/*removing-reactdom-finddomnode*/}
+`ReactDOM.findDOMNode` was [deprecated in v16.3.0](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html) because it was a legacy escape hatch that was slow to execute, fragile to refactoring, only returned the first child, and broke abstraction levels (see more [here](https://legacy.reactjs.org/docs/strict-mode.html#warning-about-deprecated-finddomnode-usage)). In React 19, we're removing `ReactDOM.findDOMNode` and you'll need to migrate to using refs:
+
+```js
+// Before
+import {findDOMNode} from 'react-dom';
+
+function AutoselectingInput() {
+  useEffect(() => {
+    const input = findDOMNode(this);
+    input.select()
+  }, []);
+
+  return <input defaultValue="Hello" />;
+}
+```
+
+```js
+// After
+function AutoselectingInput() {
+  const ref = useRef(null);
+  useEffect(() => {
+    ref.current.select();
+  }, []);
+
+  return <input ref={ref} defaultValue="Hello" />
+}
+```
+
+## Removing react-test-renderer and test-utils {/*react-test-renderer-and-test-utils*/}
+
+TODO
+
+<Note>
+
+TODO: note about React Native.
+
+</Note>
+
+## Removing UMD builds {/*umd-builds*/}
+
+TODO
+
+
+## New Deprecations {/*new-deprecations*/}

 - react: Warn when using defaultProps in functions, memo, lazy, and forwardRef (TODO)
 - react: Warn when spreading “key” as part of props in DEV  (TODO)
- react-dom: Moved createPortal and (TODO) to `react-dom/client` (TODO)
- react: Warn when calling setState during initial render  (TODO)

 ## Other Breaking Changes {/*breaking-changes*/}

- New JSX Transform: React now requires using the “new” jsx transform.  (TODO)
 - react-dom: Remove errorInfo.digest with warning (TODO)
 - react-dom: Removed unstable_renderSubtreeIntoContainer (TODO)
 - react-dom: Warn and don’t set empty string attributes for src/href (TODO: land)
@@ -89,13 +282,11 @@ TODO

 ## Other notable changes {/*other-notable-changes*/}

-### React {/*other-notable-changes-react*/}
+#### React {/*other-notable-changes-react*/}
 - act moved to top-level React package (TODO)
 - unstable_batchedUpdates is a noop (TODO).
 - Transitions in popstate are now synchronous.

-### React DOM {/*other-notable-changes-react-dom*/}
+#### React DOM {/*other-notable-changes-react-dom*/}
 - Removed layout effect warning during SSR.
 - Removed workaround for IE style sorting hydration errors (TODO: land)
- Revert to client render in more cases (TODO: status)
- APIs moved to react-dom/client