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
   # OR: npm add react-native-test-app --save-dev

3. Initialize a new test app

   yarn init-test-app 
   # OR: npx 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.

   Keep in mind that during this generation, the script will go look for pre-existing references of the React Native version used in your repository (ex. in your lock file) and use that as the version of React Native to use for RNTA. You can easily change it afterwards if you'd rather have your example app on a different version, or latest.

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": {

If you are using the relative path as shown in the code snippet above, you will very likely also need to change your metro.config.js to add this to the config:

+const path = require('path');
 const { makeMetroConfig } = require('@rnx-kit/metro-config');
 
 module.exports = makeMetroConfig({
   transformer: {
     getTransformOptions: async () => ({
       transform: {
         experimentalImportSupport: false,
         inlineRequires: false,
       },
     }),
   },
+  watchFolders: [path.join(__dirname, 'node_modules', 'react-native-webview')],
 });

Next, we need to open app.json and make sure that the WebviewExample component object is present:

  "name": "WebviewExample",
  "displayName": "WebviewExample",
  "components": [
   {
     "appKey": "WebviewExample",      // ╲ 
     "displayName": "WebviewExample"  // ╱▔▔ THIS PART HERE
   }
  ],
  "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 - if you have more than one. 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).

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
   # OR: npm i

2. Build and run the test app

   pod install --project-directory=ios
   yarn ios
   # OR: npm run ios
   yarn android
   # OR: npm run android

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

   yarn start
   # OR: npm run 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.