Guide to creating a New Architecture app from template (#3056)

* Start new template guide

This is a first iteration. I want to get feedback on a few aspects, so
starting from here as a baseline.

* Update title

* Use tabs for target OS

Set up matching the style of "Getting Started", except I kept the
headers inside the tabs for now as it makes for a useful right-hand TOC.

* Capitalize New Architecture, simplify

* Preliminary section for Hermes

Add section for recommending enabling Hermes. Not sure of contents yet,
and still have to test.

* Reword to emphasize importance of Hermes usage

* Show new arch in use

* Add build speed article link

* Add pro tip for pod install alias

* Restructure, repeat less

Favor linking to original setup guide instead of repeating content.

* Note about Expo

* Include command on uninstalling global CLI

* How to learn more

* Remove headers in tabs

They don't work correctly with the righthand TOC.

* Make header more clear

* Use quote block less often

There was way too much yellow.

* Opt for instructions using XCode

Because `xcodebuild clean` already failed me once when XCode GUI clean
worked.

* Fix lint issue

* Improve wording

* Use product name

* Fix line wraps

* Reword based on feedback

* Note use of bundle install

* Pod removal instructions

Also standardize on using yarn scripts from template for commands, it's
a little confusing to see the mix of `npx` and `yarn` once we start
referring to `yarn pod-install`

* Convert quotes to admonitions

* Convert Note: to admonitions

* Feedback: Change admonitions to caution

* PR feedback

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.
@@ -91,7 +93,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
 
@@ -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.
+<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)