diff --git a/docs/_getting-started-linux-android.md b/docs/_getting-started-linux-android.md index 0f45f1bf05b..839c6882c65 100644 --- a/docs/_getting-started-linux-android.md +++ b/docs/_getting-started-linux-android.md @@ -1,3 +1,5 @@ +import RemoveGlobalCLI from './\_remove-global-cli.md'; + ## Installing dependencies You will need Node, the React Native command line interface, a JDK, and Android Studio. @@ -77,7 +79,7 @@ React Native has a built-in command line interface. Rather than install and mana

Creating a new application

-> If you previously installed a global `react-native-cli` package, please remove it as it may cause unexpected issues. + React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using `npx`, which ships with Node.js. Let's create a new React Native project called "AwesomeProject": diff --git a/docs/_getting-started-macos-android.md b/docs/_getting-started-macos-android.md index 2d1d724a971..b5e1cdd134b 100644 --- a/docs/_getting-started-macos-android.md +++ b/docs/_getting-started-macos-android.md @@ -1,3 +1,5 @@ +import RemoveGlobalCLI from './\_remove-global-cli.md'; + ## Installing dependencies You will need Node, Watchman, the React Native command line interface, a JDK, and Android Studio. @@ -91,7 +93,7 @@ React Native has a built-in command line interface. Rather than install and mana

Creating a new application

-> If you previously installed a global `react-native-cli` package, please remove it as it may cause unexpected issues. + React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using `npx`, which ships with Node.js. Let's create a new React Native project called "AwesomeProject": diff --git a/docs/_getting-started-macos-ios.md b/docs/_getting-started-macos-ios.md index 285f0fbb7eb..9860a4cc4ba 100644 --- a/docs/_getting-started-macos-ios.md +++ b/docs/_getting-started-macos-ios.md @@ -1,4 +1,4 @@ -import M1Cocoapods from './\_markdown-m1-cocoapods.mdx'; +import M1Cocoapods from './\_markdown-m1-cocoapods.mdx'; import RemoveGlobalCLI from './\_remove-global-cli.md'; ## Installing dependencies @@ -57,7 +57,7 @@ React Native has a built-in command line interface. Rather than install and mana ## Creating a new application -> If you previously installed a global `react-native-cli` package, please remove it as it may cause unexpected issues. + You can use React Native's built-in command line interface to generate a new project. Let's create a new React Native project called "AwesomeProject": diff --git a/docs/_getting-started-windows-android.md b/docs/_getting-started-windows-android.md index d284ff3a9a2..7aa2b03f1d0 100644 --- a/docs/_getting-started-windows-android.md +++ b/docs/_getting-started-windows-android.md @@ -1,3 +1,5 @@ +import RemoveGlobalCLI from './\_remove-global-cli.md'; +

Installing dependencies

You will need Node, the React Native command line interface, a JDK, and Android Studio. @@ -108,7 +110,7 @@ React Native has a built-in command line interface. Rather than install and mana

Creating a new application

-> If you previously installed a global `react-native-cli` package, please remove it as it may cause unexpected issues. + React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using `npx`, which ships with Node.js. Let's create a new React Native project called "AwesomeProject": diff --git a/docs/_remove-global-cli.md b/docs/_remove-global-cli.md new file mode 100644 index 00000000000..08d0d9ba3c1 --- /dev/null +++ b/docs/_remove-global-cli.md @@ -0,0 +1,5 @@ +> If you previously installed a global `react-native-cli` package, please remove it as it may cause unexpected issues: +> +> ```shell +> npm uninstall -g react-native-cli @react-native-community/cli +> ``` diff --git a/docs/the-new-architecture/use-app-template.md b/docs/the-new-architecture/use-app-template.md index d575081f322..49b1c1d02c0 100644 --- a/docs/the-new-architecture/use-app-template.md +++ b/docs/the-new-architecture/use-app-template.md @@ -1,7 +1,130 @@ --- id: use-app-template -title: Using the New App Template +title: Creating a New Architecture App --- -This section describes the new app template generated by the React Native CLI and how to use it properly. -It should explain how to create a new app, which command should be issued to install the dependencies and to run it on the different platforms. +import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants'; + +import RemoveGlobalCLI from '.././\_remove-global-cli.md'; + +This page will help you create a new React Native app that uses the New Architecture. + +## Development environment + +Before continuing, make sure you've followed all the steps in [Setting up the development environment](getting-started.md), under the **React Native CLI Quickstart** tab. + +If following the setup guide, stop when you reach the section **Running your React Native Application**, and resume following this guide. + +:::caution +If you're using Expo, you can't enable the New Architecture at the moment, and will have to wait for a future release of the Expo SDK. +::: + +## Creating a new application + + + +If you already have your development environment set up, create a new React Native project from the template: + +```shell +npx react-native init AwesomeProject +``` + +:::caution +The New Architecture is available in React Native version 0.68 or later. +::: + +## Configuration + +Follow the steps below to enable the New Architecture and build the app. + +### Enable Hermes + +Hermes is an open-source JavaScript engine optimized for React Native. [Hermes will be the default engine in the future](/~https://github.com/reactwg/react-native-new-architecture/discussions/4), and we highly recommend you use it. + +Please [follow the instructions on the React Native website](hermes.md) in order to enable Hermes in your application. + +### Enable the New Architecture + +#### Target OS + + + + +Navigate to the `ios` directory and run the following: + +```shell +# from `ios` directory +bundle install && RCT_NEW_ARCH_ENABLED=1 bundle exec pod install +``` + +Then build and run the app as usual: + +```shell +yarn ios +``` + +:::note +You will need to run `pod install` each time a dependency with native code changes. Make this command easier to run by adding it to `scripts` to your project's `package.json` file: + +``` +"scripts": { + "pod-install": "RCT_NEW_ARCH_ENABLED=1 bundle exec pod install" +} +``` + +and run it with `yarn pod-install`. Note that `bundle install` does not need to run a second time, as long as the Gemfile has not changed. +::: + +#### Troubleshooting + +##### `react-native run-ios` fails + +If you see a build failure from `react-native run-ios`, there may be cached files from a previous build with the old architecture. Clean the build cache and try again: + +1. Open the project `ios/project.xcworkspace` in Xcode +2. In XCode, choose Product > Clean Build Folder +3. In the project directory, remove the `ios/Podfile.lock` file and `ios/Pods` directory: `rm -rf ios/Podfile.lock ios/Pods` +4. Re-run `yarn pod-install` and `yarn ios` + + + + +Set the `newArchEnabled` property to `true` by **either**: + +- Changing the corresponding line in `android/gradle.properties` +- Setting the environment variable `ORG_GRADLE_PROJECT_newArchEnabled=true` + +Then build and run the app as usual: + +```shell +yarn android +``` + +:::note +You may notice longer build times with the New Architecture, due to additional step of C++ compilation with the Android NDK. To improve your build time, see [Speeding Up Your Build Phase](docs/build-speed.md). +::: + + + + +### Confirming the New Architecture is in use + +After you build and run the app, when Metro serves the JavaScript bundle, you should see `"fabric": true` in the Metro logs: + +Metro shows fabric: true + +### Want to know more? + +If you'd like to view the code changes relevant for the New Architecture, take a look at the [upgrade helper from version 0.67.4 to 0.68.0](https://react-native-community.github.io/upgrade-helper/?from=0.67.4&to=0.68.0). Files that were added for the New Architecture are marked with a yellow banner. + +For further explanations of what each file is doing, check out these guides to walk through the changes step-by-step: + +#### Android + +- [Enabling TurboModules on Android](new-architecture-app-modules-android.md) +- [Enabling Fabric on Android](new-architecture-app-renderer-android.md) + +#### iOS + +- [Enabling TurboModules on iOS](new-architecture-app-modules-ios.md) +- [Enabling Fabric on iOS](new-architecture-app-renderer-ios.md) diff --git a/website/static/docs/assets/metro-new-arch.png b/website/static/docs/assets/metro-new-arch.png new file mode 100644 index 00000000000..b37d74b36b6 Binary files /dev/null and b/website/static/docs/assets/metro-new-arch.png differ