|
| 1 | +--- |
| 2 | +id: landing-page |
| 3 | +title: About the New Architecture |
| 4 | +--- |
| 5 | + |
| 6 | +Since 2018, the React Native team has been redesigning the core internals of React Native to enable developers to create higher-quality experiences. As of 2024, this version of React Native has been proven at scale and powers production apps by Meta. |
| 7 | + |
| 8 | +The term _New Architecture_ refers to both the new framework architecture and the work to bring it to open source. |
| 9 | + |
| 10 | +The New Architecture has been available for experimental opt-in as of [React Native 0.68](/blog/2022/03/30/version-068#opting-in-to-the-new-architecture) with continued improvements in every subsequent release. The team is now working to make this the default experience for the React Native open source ecosystem. |
| 11 | + |
| 12 | +## Why a New Architecture? |
| 13 | + |
| 14 | +After many years of building with React Native, the team identified a set of limitations that prevented developers from crafting certain experiences with a high polish. These limitations were fundamental to the existing design of the framework, so the New Architecture started as an investment in the future of React Native. |
| 15 | + |
| 16 | +The New Architecture unlocks capabilities and improvements that were impossible in the legacy architecture. |
| 17 | + |
| 18 | +### Synchronous Layout and Effects |
| 19 | + |
| 20 | +Building adaptive UI experiences often requires measuring the size and position of your views and adjusting layout. |
| 21 | + |
| 22 | +Today, you would use the [`onLayout`](/docs/view#onlayout) event to get the layout information of a view and make any adjustments. However, state updates within the `onLayout` callback may apply after painting the previous render. This means that users may see intermediate states or visual jumps between rendering the initial layout and responding to layout measurements. |
| 23 | + |
| 24 | +With the New Architecture, we can avoid this issue entirely with synchronous access to layout information and properly scheduled updates such that no intermediate state is visible to users. |
| 25 | + |
| 26 | +<details> |
| 27 | +<summary>Example: Rendering a Tooltip</summary> |
| 28 | + |
| 29 | +Measuring and placing a tooltip above a view allows us to showcase what synchronous rendering unlocks. The tooltip needs to know the position of its target view to determine where it should render. |
| 30 | + |
| 31 | +In the current architecture, we use `onLayout` to get the measurements of the view and then update the positioning of the tooltip based on where the view is. |
| 32 | + |
| 33 | +```jsx |
| 34 | +function ViewWithTooltip() { |
| 35 | + // ... |
| 36 | + |
| 37 | + // We get the layout information and pass to ToolTip to position itself |
| 38 | + const onLayout = React.useCallback(event => { |
| 39 | + targetRef.current?.measureInWindow((x, y, width, height) => { |
| 40 | + // This state update is not guaranteed to run in the same commit |
| 41 | + // This results in a visual "jump" as the ToolTip repositions itself |
| 42 | + setTargetRect({x, y, width, height}); |
| 43 | + }); |
| 44 | + }, []); |
| 45 | + |
| 46 | + return ( |
| 47 | + <> |
| 48 | + <View ref={targetRef} onLayout={onLayout}> |
| 49 | + <Text>Some content that renders a tooltip above</Text> |
| 50 | + </View> |
| 51 | + <Tooltip targetRect={targetRect} /> |
| 52 | + </> |
| 53 | + ); |
| 54 | +} |
| 55 | +``` |
| 56 | +
|
| 57 | +With the New Architecture, we can use [`useLayoutEffect`](https://react.dev/reference/react/useLayoutEffect) to synchronously measure and apply layout updates in a single commit, avoiding the visual "jump". |
| 58 | +
|
| 59 | +```jsx |
| 60 | +function ViewWithTooltip() { |
| 61 | + // ... |
| 62 | + |
| 63 | + useLayoutEffect(() => { |
| 64 | + // The measurement and state update for `targetRect` happens in a single commit |
| 65 | + // allowing ToolTip to position itself without intermediate paints |
| 66 | + targetRef.current?.measureInWindow((x, y, width, height) => { |
| 67 | + setTargetRect({x, y, width, height}); |
| 68 | + }); |
| 69 | + }, [setTargetRect]); |
| 70 | + |
| 71 | + return ( |
| 72 | + <> |
| 73 | + <View ref={targetRef}> |
| 74 | + <Text>Some content that renders a tooltip above</Text> |
| 75 | + </View> |
| 76 | + <Tooltip targetRect={targetRect} /> |
| 77 | + </> |
| 78 | + ); |
| 79 | +} |
| 80 | +``` |
| 81 | +
|
| 82 | +<div className="TwoColumns TwoFigures"> |
| 83 | + <figure> |
| 84 | + <img src="/img/new-architecture/async-on-layout.gif" alt="A view that is moving to the corners of the viewport and center with a tooltip rendered either above or below it. The tooltip is rendered after a short delay after the view moves" /> |
| 85 | + <figcaption>Asynchronous measurement and render of the ToolTip. [See code](https://gist.github.com/lunaleaps/eabd653d9864082ac1d3772dac217ab9).</figcaption> |
| 86 | +</figure> |
| 87 | +<figure> |
| 88 | + <img src="/img/new-architecture/sync-use-layout-effect.gif" alt="A view that is moving to the corners of the viewport and center with a tooltip rendered either above or below it. The view and tooltip move in unison." /> |
| 89 | + <figcaption>Synchronous measurement and render of the ToolTip. [See code](https://gist.github.com/lunaleaps/148756563999c83220887757f2e549a3).</figcaption> |
| 90 | +</figure> |
| 91 | +</div> |
| 92 | +
|
| 93 | +</details> |
| 94 | +
|
| 95 | +### Support for Concurrent Renderer and Features |
| 96 | +
|
| 97 | +The New Architecture supports concurrent rendering and features that have shipped in [React 18](https://react.dev/blog/2022/03/29/react-v18) and beyond. You can now use features like Suspense for data-fetching, Transitions, and other new React APIs in your React Native code, further conforming codebases and concepts between web and native React development. |
| 98 | +
|
| 99 | +The concurrent renderer also brings out-of-the-box improvements like automatic batching, which reduces re-renders in React. |
| 100 | +
|
| 101 | +<details> |
| 102 | +<summary>Example: Automatic Batching</summary> |
| 103 | +
|
| 104 | +With the New Architecture, you'll get automatic batching with the React 18 renderer. |
| 105 | +
|
| 106 | +In this example, a slider specifies how many tiles to render. Dragging the slider from 0 to 1000 will fire off a quick succession of state updates and re-renders. |
| 107 | +
|
| 108 | +In comparing the renderers for the [same code](https://gist.github.com/lunaleaps/79bb6f263404b12ba57db78e5f6f28b2), you can visually notice the renderer provides a smoother UI, with less intermediate UI updates. State updates from native event handlers, like this native Slider component, are now batched. |
| 109 | +
|
| 110 | +<div className="TwoColumns TwoFigures"> |
| 111 | + <figure> |
| 112 | + <img src="/img/new-architecture/legacy-renderer.gif" alt="A video demonstrating an app rendering many views according to a slider input. The slider value is adjusted from 0 to 1000 and the UI slowly catches up to rendering 1000 views." /> |
| 113 | + <figcaption>Rendering frequent state updates with legacy renderer.</figcaption> |
| 114 | +</figure> |
| 115 | +<figure> |
| 116 | + <img src="/img/new-architecture/react18-renderer.gif" alt="A video demonstrating an app rendering many views according to a slider input. The slider value is adjusted from 0 to 1000 and the UI resolves to 1000 views faster than the previous example, without as many intermediate states." /> |
| 117 | + <figcaption>Rendering frequent state updates with React 18 renderer.</figcaption> |
| 118 | +</figure> |
| 119 | +</div> |
| 120 | +</details> |
| 121 | +
|
| 122 | +New concurrent features, like [Transitions](https://react.dev/reference/react/useTransition), give you the power to express the priority of UI updates. Marking an update as lower priority tells React it can "interrupt" rendering the update to handle higher priority updates to ensure a responsive user experience where it matters. |
| 123 | +
|
| 124 | +<details> |
| 125 | +<summary>Example: Using `startTransition`</summary> |
| 126 | +
|
| 127 | +We can build on the previous example to showcase how transitions can interrupt in-progress rendering to handle a newer state update. |
| 128 | +
|
| 129 | +We wrap the tile number state update with `startTransition` to indicate that rendering the tiles can be interrupted. `startTransition` also provides a `isPending` flag to tell us when the transition is complete. |
| 130 | +
|
| 131 | +```jsx |
| 132 | +function TileSlider({value, onValueChange}) { |
| 133 | + const [isPending, startTransition] = useTransition(); |
| 134 | + |
| 135 | + return ( |
| 136 | + <> |
| 137 | + <View> |
| 138 | + <Text> |
| 139 | + Render {value} Tiles |
| 140 | + </Text> |
| 141 | + <ActivityIndicator animating={isPending} /> |
| 142 | + </View> |
| 143 | + <Slider |
| 144 | + value={1} |
| 145 | + minimumValue={1} |
| 146 | + maximumValue={1000} |
| 147 | + step={1} |
| 148 | + onValueChange={newValue => { |
| 149 | + startTransition(() => { |
| 150 | + onValueChange(newValue); |
| 151 | + }); |
| 152 | + }} |
| 153 | + /> |
| 154 | + </> |
| 155 | + ); |
| 156 | +} |
| 157 | + |
| 158 | +function ManyTiles() { |
| 159 | + const [value, setValue] = useState(1); |
| 160 | + const tiles = generateTileViews(value); |
| 161 | + return ( |
| 162 | + <TileSlider onValueChange={setValue} value={value} /> |
| 163 | + <View> |
| 164 | + {tiles} |
| 165 | + </View> |
| 166 | + ) |
| 167 | +} |
| 168 | +``` |
| 169 | +
|
| 170 | +You'll notice that with the frequent updates in a transition, React renders fewer intermediate states because it bails out of rendering the state as soon as it becomes stale. In comparison, without transitions, more intermediate states are rendered. Both examples still use automatic batching. Still, transitions give even more power to developers to batch in-progress renders. |
| 171 | +
|
| 172 | +<div className="TwoColumns TwoFigures"> |
| 173 | +<figure> |
| 174 | + <img src="/img/new-architecture/with-transitions.gif" alt="A video demonstrating an app rendering many views (tiles) according to a slider input. The views are rendered in batches as the slider is quickly adjusted from 0 to 1000. There are less batch renders in comparison to the next video." /> |
| 175 | + <figcaption>Rendering tiles with transitions to interrupt in-progress renders of stale state. [See code](https://gist.github.com/lunaleaps/eac391bf3fe4c85953cefeb74031bab0/revisions).</figcaption> |
| 176 | +</figure> |
| 177 | +<figure> |
| 178 | + <img src="/img/new-architecture/without-transitions.gif" alt="A video demonstrating an app rendering many views (tiles) according to a slider input. The views are rendered in batches as the slider is quickly adjusted from 0 to 1000." /> |
| 179 | + <figcaption>Rendering tiles without marking it as a transition. [See code](https://gist.github.com/lunaleaps/eac391bf3fe4c85953cefeb74031bab0/revisions).</figcaption> |
| 180 | +</figure> |
| 181 | +</div> |
| 182 | +</details> |
| 183 | +
|
| 184 | +### Fast JavaScript/Native Interfacing |
| 185 | +
|
| 186 | +The New Architecture removes the [asynchronous bridge](https://reactnative.dev/blog/2018/06/14/state-of-react-native-2018#architecture) between JavaScript and native and replaces it with JavaScript Interface (JSI). JSI is an interface that allows JavaScript to hold a reference to a C++ object and vice-versa. With a memory reference, you can directly invoke methods without serialization costs. |
| 187 | +
|
| 188 | +JSI enables [VisionCamera](https://github.com/mrousavy/react-native-vision-camera), a popular camera library for React Native, to process frames in real time. Typical frame buffers are 10 MB, which amounts to roughly 1 GB of data per second, depending on the frame rate. In comparison with the serialization costs of the bridge, JSI handles that amount of interfacing data with ease. JSI can expose other complex instance-based types such as databases, images, audio samples, etc. |
| 189 | +
|
| 190 | +JSI adoption in the New Architecture removes this class of serialization work from all native-JavaScript interop. This includes initializing and re-rendering native core components like `View` and `Text`. You can read more about our [investigation in rendering performance](https://github.com/reactwg/react-native-new-architecture/discussions/123) in the New Architecture and the improved benchmarks we measured. |
| 191 | +
|
| 192 | +## What can I expect from enabling the New Architecture? |
| 193 | +
|
| 194 | +While the New Architecture enables these features and improvements, enabling the New Architecture for your app or library may not immediately improve the performance or user experience. |
| 195 | +
|
| 196 | +For example, your code may need refactoring to leverage new capabilities like synchronous layout effects or concurrent features. Although JSI will minimize the overhead between JavaScript and native memory, data serialization may not have been a bottleneck for your app's performance. |
| 197 | +
|
| 198 | +Enabling the New Architecture in your app or library is opting into the future of React Native. |
| 199 | +
|
| 200 | +The team is actively researching and developing new capabilities the New Architecture unlocks. For example, web alignment is an active area of exploration at Meta that will ship to the React Native open source ecosystem. |
| 201 | +
|
| 202 | +- [Updates to the event loop model](https://github.com/react-native-community/discussions-and-proposals/blob/main/proposals/0744-well-defined-event-loop.md) |
| 203 | +- [Node and layout APIs](https://github.com/react-native-community/discussions-and-proposals/blob/main/proposals/0607-dom-traversal-and-layout-apis.md) |
| 204 | +- [Styling and layout conformance](https://github.com/facebook/yoga/releases/tag/v2.0.0) |
| 205 | +
|
| 206 | +You can follow along and contribute in our dedicated [discussions & proposals](https://github.com/react-native-community/discussions-and-proposals/discussions/651) repository. |
| 207 | +
|
| 208 | +## Should I use the New Architecture today? |
| 209 | +
|
| 210 | +With 0.76, The New Architecture is enabled by default in all the React Native projects. |
| 211 | +
|
| 212 | +If you find aything that is not working well, please open an issue using [this template](https://github.com/facebook/react-native/issues/new?assignees=&labels=Needs%3A+Triage+%3Amag%3A%2CType%3A+New+Architecture&projects=&template=new_architecture_bug_report.yml). |
| 213 | +
|
| 214 | +If, for any reasons, you can't use the New Architecture, you can still opt-out from it: |
| 215 | +
|
| 216 | +### Android |
| 217 | +
|
| 218 | +1. Open the `andorid/gradle.properties` file |
| 219 | +2. Toggle the `newArchEnabled` flag from `true` to `false` |
| 220 | +
|
| 221 | +```diff title="gradle.properties" |
| 222 | +# Use this property to enable support to the new architecture. |
| 223 | +# This will allow you to use TurboModules and the Fabric render in |
| 224 | +# your application. You should enable this flag either if you want |
| 225 | +# to write custom TurboModules/Fabric components OR use libraries that |
| 226 | +# are providing them. |
| 227 | +-newArchEnabled=true |
| 228 | ++newArchEnabled=false |
| 229 | +``` |
| 230 | +
|
| 231 | +### iOS |
| 232 | +
|
| 233 | +1. Install your CocoaPods dependencies with the command: |
| 234 | +
|
| 235 | +```shell |
| 236 | +RCT_NEW_ARCH_ENABLED=0 bundle exec pod install |
| 237 | +``` |
0 commit comments