Migrate an Existing Test App

Contents

1. Before We Start
2. Initialize a New Test App
3. Copy Files from Existing Test App
4. Configure the Test App
5. Building the Test App
6. Further Reading
7. Known Issues

Before We Start

This easiest way to migrate an existing test app is to generate a new one with react-native-test-app, and move your code over one file at a time. To make this a little easier to follow, we'll be using react-native-webview as an example.

If you prefer to skip right to the end, you can find the full PR here: react-native-webview/react-native-webview#2148.

Initialize a New Test App

Starting with a fresh clone of react-native-webview:

1. First, we need to move the current example app out of the way

   mv example example-prev

2. Add react-native-test-app as a dev dependency

   yarn add react-native-test-app --dev

3. Initialize a new test app

   yarn init-test-app
   # ✔ What is the name of your test app? … WebviewExample
   # ✔ Which platforms do you need test apps for? › Android, iOS, macOS, Windows
   # ✔ Where should we create the new project? … example

   Here you should pick the platforms that you do support. You can always add more platform later using configure-test-app.

Copy Files from Existing Test App

This is going to vary from project to project. For react-native-webview, we needed the following files:

rm App.js
cp -R ../example-prev/App.tsx .
cp -R ../example-prev/assets .
cp -R ../example-prev/examples .

Configure the Test App

First, make sure that your component is added to package.json. The easiest way to do that is to add a file reference. If you're using workspaces, you can use workspace ranges instead.

     "react": "16.11.0",
     "react-native": "0.62.3",
     "react-native-macos": "^0.62.0",
+    "react-native-webview": "../",
     "react-native-windows": "^0.62.0"
   },
   "devDependencies": {

Next, we need to open app.json and declare all the components that are available.

   "name": "WebviewExample",
   "displayName": "WebviewExample",
   "components": [
+    {
+      "appKey": "WebviewExample",
+      "displayName": "WebviewExample"
+    }
   ],
   "resources": {
     "android": [

appKey is the first argument you pass to AppRegistry.registerComponent("WebviewExample", ...). Adding an entry for every AppRegistry.registerComponent() call you have is a good start. You can also add the same app key, but with different initial properties. You can read more about that and other things you can configure in Manifest (app.json).

You might also need to modify the new example app react-native.config.js file to add extra logic to ensure that the react-native CLI will correctly identify the project:

+ const project = (() => {
+   try {
+     const {
+       androidManifestPath,
+       iosProjectPath,
+     } = require('react-native-test-app');
+     const iosProject = iosProjectPath('ios');
+     return {
+       android: {
+         sourceDir: 'android',
+         manifestPath: androidManifestPath(path.join(__dirname, 'android')),
+       },
+ 
+       ...(iosProject ? { ios: { project: iosProject } } : undefined),
+     };
+   } catch (_) {
+     return undefined;
+   }
+ })();

module.exports = {
+  ...(project ? { project } : undefined),
  dependencies: {

On top of this, remember to add any other native-side build configuration settings that were present in the example-prev, such as extra references in the android/build.gradle, as we had to do when migrating @react-native-community/blur in this PR (we needed to add maven { url 'https://www.jitpack.io/' } to ingest one non-standard dependency).

Building the Test App

Now we should be good to go:

1. Install npm dependencies

   yarn

2. Build and run the test app

   pod install --project-directory=ios
   yarn ios

3. While the app is building, you should start the dev server in a new terminal

   yarn start

If you want to start the test app for other platforms, have a look at Quick Start.

Further Reading

All configuration of the test app is done via app.json (otherwise known as the manifest). You can learn more about that in Manifest (app.json).

Additionally, you can find platform specific documentation below:

• Android
• iOS/macOS
• Windows

Known Issues

For a list of known issues and workarounds, please see Troubleshooting.