Guide to creating a New Architecture app from template

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
 
 <h2>Creating a new application</h2>
 
-> If you previously installed a global `react-native-cli` package, please remove it as it may cause unexpected issues.
+<RemoveGlobalCLI />
 
 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":
 

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.
@@ -89,7 +91,7 @@ React Native has a built-in command line interface. Rather than install and mana
 
 <h2>Creating a new application</h2>
 
-> If you previously installed a global `react-native-cli` package, please remove it as it may cause unexpected issues.
+<RemoveGlobalCLI />
 
 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":
 

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
 
@@ -55,7 +55,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.
+<RemoveGlobalCLI />
 
 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":
 

docs/_getting-started-windows-android.md

@@ -1,3 +1,5 @@
+import RemoveGlobalCLI from './\_remove-global-cli.md';
+
 <h2>Installing dependencies</h2>
 
 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
 
 <h2>Creating a new application</h2>
 
-> If you previously installed a global `react-native-cli` package, please remove it as it may cause unexpected issues.
+<RemoveGlobalCLI />
 
 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":
 

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
+> ```

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
+
+<RemoveGlobalCLI />
+
+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
+
+<Tabs groupId="platform" defaultValue={constants.defaultPlatform} values={constants.platforms} className="pill-tabs">
+<TabItem value="ios">
+
+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`
+
+</TabItem>
+<TabItem value="android">
+
+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).
+:::
+
+</TabItem>
+</Tabs>
+
+### 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:
+
+<img src="/docs/assets/metro-new-arch.png" alt="Metro shows fabric: true" width="600" />
+
+### 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)