diff --git a/src/components/MDX/ConsoleBlock.tsx b/src/components/MDX/ConsoleBlock.tsx index 5683d6dcf57..6e704b41715 100644 --- a/src/components/MDX/ConsoleBlock.tsx +++ b/src/components/MDX/ConsoleBlock.tsx @@ -15,6 +15,10 @@ interface ConsoleBlockProps { children: React.ReactNode; } +interface ConsoleBlockMultiProps { + children: React.ReactNode; +} + const Box = ({ width = '60px', height = '17px', @@ -29,7 +33,7 @@ const Box = ({
); -function ConsoleBlock({level = 'error', children}: ConsoleBlockProps) { +export function ConsoleBlock({level = 'error', children}: ConsoleBlockProps) { let message: React.ReactNode | null; if (typeof children === 'string') { message = children; @@ -38,7 +42,10 @@ function ConsoleBlock({level = 'error', children}: ConsoleBlockProps) { } return ( -
+
@@ -73,4 +80,72 @@ function ConsoleBlock({level = 'error', children}: ConsoleBlockProps) { ); } -export default ConsoleBlock; +export function ConsoleBlockMulti({children}: ConsoleBlockMultiProps) { + return ( +
+
+
+ +
+
+
+ Console +
+
+ + + +
+
+
+
+ {children} +
+
+ ); +} + +export function ConsoleLogLine({children, level}: ConsoleBlockProps) { + let message: React.ReactNode | null; + if (typeof children === 'string') { + message = children; + } else if (isValidElement(children)) { + message = children.props.children; + } else if (Array.isArray(children)) { + message = children.reduce((result, child) => { + if (typeof child === 'string') { + result += child; + } else if (isValidElement(child)) { + // @ts-ignore + result += child.props.children; + } + return result; + }, ''); + } + + return ( +
+ {level === 'error' && ( + + )} + {level === 'warning' && ( + + )} +
+ {message} +
+
+ ); +} diff --git a/src/components/MDX/MDXComponents.tsx b/src/components/MDX/MDXComponents.tsx index bdfd05a20c1..a89edf9c88a 100644 --- a/src/components/MDX/MDXComponents.tsx +++ b/src/components/MDX/MDXComponents.tsx @@ -8,7 +8,7 @@ import cn from 'classnames'; import CodeBlock from './CodeBlock'; import {CodeDiagram} from './CodeDiagram'; -import ConsoleBlock from './ConsoleBlock'; +import {ConsoleBlock, ConsoleLogLine, ConsoleBlockMulti} from './ConsoleBlock'; import ExpandableCallout from './ExpandableCallout'; import ExpandableExample from './ExpandableExample'; import {H1, H2, H3, H4, H5} from './Heading'; @@ -420,6 +420,8 @@ export const MDXComponents = { pre: CodeBlock, CodeDiagram, ConsoleBlock, + ConsoleBlockMulti, + ConsoleLogLine, DeepDive: (props: { children: React.ReactNode; title: string; diff --git a/src/content/blog/2024/04/25/react-19-upgrade-guide.md b/src/content/blog/2024/04/25/react-19-upgrade-guide.md new file mode 100644 index 00000000000..5e1b410b121 --- /dev/null +++ b/src/content/blog/2024/04/25/react-19-upgrade-guide.md @@ -0,0 +1,655 @@ +--- +title: "React 19 Beta Upgrade Guide" +--- + +April 25, 2024 by [Ricky Hanlon](https://twitter.com/rickhanlonii) + +--- + + + +This beta release is for libraries to prepare for React 19. App developers should upgrade to 18.3.0 and wait for React 19 stable as we work with libraries and make changes based on feedback. + + + + + + +The improvements added to React 19 require some breaking changes, but we've worked to make the upgrade as smooth as possible and we don't expect the changes to impact most apps. + +To help make the upgrade easier, today we are also publishing React 18.3. + + + + + +#### React 18.3 has also been published {/*react-18-3*/} + +To help make the upgrade to React 19 easier, we've published a `react@18.3` release that is identical to 18.2 but adds warnings for deprecated APIs and other changes that are needed for React 19. + +We recommend upgrading to React 18.3 first to help identify any issues before upgrading to React 19. + +For a list of changes in 18.3 see the [Release Notes](https://github.com/facebook/react/blob/main/CHANGELOG.md). + + + +In this post, we will guide you through the steps for upgrading libraries to React 19 beta: + +- [Installing](#installing) +- [Breaking Changes](#breaking-changes) +- [New Deprecations](#new-deprecations) +- [Notable Changes](#notable-changes) +- [TypeScript Changes](#typescript-changes) +- [Changelog](#changelog) + +If you'd like to help us test React 19, follow the steps in this upgrade guide and [report any issues](https://github.com/facebook/react/issues/new?assignees=&labels=React+19&projects=&template=19.md&title=%5BReact+19%5D) you encounter. For a list of new features added to React 19 beta, see the [React 19 release post](/blog/2024/04/25/react-19). + +--- +## Installing {/*installing*/} + + + +#### New JSX Transform is now required {/*new-jsx-transform-is-now-required*/} + +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. + +If the new transform is not enabled, you will see this warning: + + + + + +Your app (or one of its dependencies) is using an outdated JSX transform. Update to the modern JSX transform for faster performance: https://react.dev/link/new-jsx-transform + + + + + + +We expect most apps will not be affected 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). + + + + +To install the latest version of React and React DOM: + +```bash +npm install react@beta react-dom@beta +``` + +If you're using TypeScript, you also need to update the types. Once React 19 is released as stable, you can install the types as usual from `@types/react` and `@types/react-dom`. During the beta period, the types are available in different packages which need to be enforced in your `package.json`: + +```json +{ + "dependencies": { + "@types/react": "npm:types-react@alpha", + "@types/react-dom": "npm:types-react-dom@alpha" + }, + "overrides": { + "@types/react": "npm:types-react@alpha", + "@types/react-dom": "npm:types-react-dom@alpha" + } +} +``` + +We're also including a codemod for the most common replacements. See [Removed TypeScript Types](#removed-deprecated-typescript-types) below. + + +## Breaking Changes {/*breaking-changes*/} + +### Errors in render are not re-thrown {/*errors-in-render-are-not-re-thrown*/} + +In previous versions of React, errors thrown during render were caught and rethrown. In DEV, we would also log to `console.error`, resulting in duplicate error logs. + +In React 19, we've [improved how errors are handled](/blog/2024/04/25/react-19#error-handling) to reduce duplication by not re-throwing: + +- **Uncaught Errors**: Errors that are not caught by an Error Boundary are reported to `window.reportError`. +- **Caught Errors**: Errors that are caught by an Error Boundary are reported to `console.error`. + +This change should not impact most apps, but if your production error reporting relies on errors being re-thrown, you may need to update your error handling. To support this, we've added new methods to `createRoot` and `hydrateRoot` for custom error handling: + +```js [[1, 2, "onUncaughtError"], [2, 5, "onCaughtError"]] +const root = createRoot(container, { + onUncaughtError: (error, errorInfo) => { + // ... log error report + }, + onCaughtError: (error, errorInfo) => { + // ... log error report + } +}); +``` + +For more info, see the docs for [`createRoot`](https://react.dev/reference/react-dom/client/createRoot) and [`hydrateRoot`](https://react.dev/reference/react-dom/client/hydrateRoot). + + +### Removed deprecated React APIs {/*removed-deprecated-react-apis*/} + +#### Removed: `propTypes` and `defaultProps` for functions {/*removed-proptypes-and-defaultprops*/} +`PropTypes` were deprecated in [April 2017 (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` from function components in place of ES6 default parameters. Class components will continue to support `defaultProps` since there is no ES6 alternative. + +```js +// Before +import PropTypes from 'prop-types'; + +function Heading({text}) { + return

{text}

; +} +Heading.propTypes = { + text: PropTypes.string, +}; +Heading.defaultProps = { + text: 'Hello, world!', +}; +``` +```ts +// After +interface Props { + text?: string; +} +function Heading({text = 'Hello, world!'}: Props) { + return

{text}

; +} +``` + +#### Removed: Legacy Context using `contextTypes` and `getChildContext` {/*removed-removing-legacy-context*/} + +Legacy Context was deprecated in [October 2018 (v16.6.0)](https://legacy.reactjs.org/blog/2018/10/23/react-v-16-6.html). + +Legacy Context was only available in class components using the APIs `contextTypes` and `getChildContext`, and was replaced with `contextType` 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 ; + } +} + +class Child extends React.Component { + static contextTypes = { + foo: PropTypes.string.isRequired, + }; + + render() { + return
{this.context.foo}
; + } +} +``` + +```js +// After +const FooContext = React.createContext(); + +class Parent extends React.Component { + render() { + return ( + + + + ); + } +} + +class Child extends React.Component { + static contextType = FooContext; + + render() { + return
{this.context}
; + } +} +``` + +#### Removed: string refs {/*removed-string-refs*/} +String refs were deprecated in [March, 2018 (v16.3.0)](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html). + +Class components supported string refs before being replaced by ref callbacks due to [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 ; + } +} +``` + +```js +// After +class MyComponent extends React.Component { + componentDidMount() { + this.input.focus(); + } + + render() { + return this.input = input} />; + } +} +``` + + + +To help with the migration, we will be publishing a [react-codemod](https://github.com/reactjs/react-codemod/#string-refs) to automatically replace string refs with `ref` callbacks. Follow [this PR](https://github.com/reactjs/react-codemod/pull/309) for updates and to try it out. + + + +#### Removed: Module pattern factories {/*removed-module-pattern-factories*/} +Module pattern factories were deprecated in [August 2019 (v16.9.0)](https://legacy.reactjs.org/blog/2019/08/08/react-v16.9.0.html#deprecating-module-pattern-factories). + +This pattern was 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
; } } +} +``` + +```js +// After +function FactoryComponent() { + return
; +} +``` + +#### Removed: `React.createFactory` {/*removed-createfactory*/} +`createFactory` was deprecated in [February 2020 (v16.13.0)](https://legacy.reactjs.org/blog/2020/02/26/react-v16.13.0.html#deprecating-createfactory). + +Using `createFactory` was common before broad support for JSX, but it's rarely used today and can be replaced with 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 = + {error &&

{error}

} +
+ ); +} +``` + +In React 19, we're adding support for using async functions in transitions to handle pending states, errors, forms, and optimistic updates automatically. + +For example, you can use `useTransition` to handle the pending state for you: + +```js +// Using pending state from Actions +function UpdateName({}) { + const [name, setName] = useState(""); + const [error, setError] = useState(null); + const [isPending, startTransition] = useTransition(); + + const handleSubmit = async () => { + startTransition(async () => { + const error = await updateName(name); + if (error) { + setError(error); + return; + } + redirect("/path"); + }) + }; + + return ( +
+ setName(event.target.value)} /> + + {error &&

{error}

} +
+ ); +} +``` + +The async transition will immediately set the `isPending` state to true, make the async request(s), and switch `isPending` to false after any transitions. This allows you to keep the current UI responsive and interactive while the data is changing. + + + +#### By convention, functions that use async transitions are called "Actions". {/*by-convention-functions-that-use-async-transitions-are-called-actions*/} + +Actions automatically manage submitting data for you: + +- **Pending state**: Actions provide a pending state that starts at the beginning of a request and automatically resets when the final state update is committed. +- **Optimistic updates**: Actions support the new [`useOptimistic`](#new-feature-optimistic-updates) hook so you can show users instant feedback while the requests are submitting. +- **Error handling**: Actions provide error handling so you can and display Error Boundaries when a request fails, and revert optimistic updates to their original value automatically. +- **Forms**: `
` elements now support passing functions to the `action` and `formAction` props. Passing functions to the `action` props use Actions by default and reset the form automatically after submission. + + + +Building on top of Actions, we're also introducing [`` Actions](#form-actions) to manage forms automatically, [`useOptimistic`](#new-hook-optimistic-updates) to manage optimistic updates, and new hooks [`useActionState`](#new-hook-useactionstate), [`useFormStatus`](#new-hook-useformstatus) hooks to support the common cases for Actions and Forms. + +In React 19, the above example can be simplified to: + +```js +// Using Actions and useActionState +function ChangeName({ name, setName }) { + const [error, submitAction, isPending] = useActionState( + async (previousState, formData) => { + const error = await updateName(formData.get("name")); + if (error) { + return error; + } + redirect("/path"); + } + ); + + return ( + + + + {error &&

{error}

} +
+ ); +} +``` + +In the next section, we'll break down each of the new Action features in React 19. + +### New Hook: `useActionState` {/*new-hook-useactionstate*/} + +To make the common cases easier for Actions, we've added a new hook called `useActionState`: + +```js +const [error, submitAction, isPending] = useActionState(async (previousState, newName) => { + const {error} = await updateName(newName); + if (!error) { + // You can return any result of the action. + // Here, we return only the error. + return error; + } + + // handle success +}); +``` + +`useActionState` accepts a function (the "Action"), and returns a wrapped Action to call. This works because Actions compose. When the wrapped Action is called, `useActionState` will return the last result of the Action as `data`, and the pending state of the Action as `pending`. + + + +`React.useActionState` was previously called `ReactDOM.useFormState` in the Canary releases, but we've renamed it and deprecated `useFormState`. + +See [#28491](https://github.com/facebook/react/pull/28491) for more info. + + + +For more information, see the docs for [`useActionState`](/reference/react/useActionState). + +### `
` Actions {/*form-actions*/} + +Actions are also integrated with React 19's new `` features. We've added support for passing functions as the `action` and `formAction` props of ``, ``, and `