@apexnative/navigation 1.0.0-alpha.1 → 1.0.0-alpha.10

package/cli/doctor/checks/app.js

@@ -11,8 +11,10 @@ const {
   reactNativeVersion,
   usesExpo,
 } = require('../../app');
+const { mainActivity } = require('../../links/native');
 const { findProject } = require('../../project');
 const { codeOf } = require('../../setup/source');
+const { loadsReactNativeItself } = require('../../setup/steps/mainApplication');
 const { planCodegen } = require('../../codegen');
 const { readConfig } = require('../../config');
 const { planProject } = require('../../setup');
@@ -27,6 +29,16 @@ const { splashChecks } = require('./splash');
 const SETUP = { label: 'npx apex-navigation setup', run: /** @type {const} */ ('setup') };
 const GENERATED = ['ApexNavigation.generated.swift', 'ApexNavigationGenerated.kt'];
 const CODEGEN = { label: 'npx apex-navigation codegen', run: /** @type {const} */ ('codegen') };
+// The changes the main activity must handle itself; the template's value has them all.
+const CONFIG_CHANGES = [
+  'orientation',
+  'screenSize',
+  'smallestScreenSize',
+  'screenLayout',
+  'uiMode',
+];
+const TEMPLATE_CONFIG_CHANGES =
+  'keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode';
 
 /**
  * React Native, the navigation, and the files setup sets up.
@@ -88,11 +100,12 @@ function appChecks({ root, run }) {
   const project = findProject(root, run);
   const plans = planProject(project);
   const app = plans.find(({ file }) => file !== undefined && file === project.app);
+  const metro = plans.find(({ file }) => file !== undefined && file === project.metroConfig);
   const manifest = plans.find(({ file }) => file !== undefined && file === project.manifest);
   const native = plans.filter((plan) => plan.platform !== 'js' && plan !== manifest);
   const types = plans.filter(({ name }) => name === ENV_FILE || name === 'tsconfig.json');
   const entry = plans.filter(
-    (plan) => plan.platform === 'js' && plan !== app && !types.includes(plan)
+    (plan) => plan.platform === 'js' && plan !== app && plan !== metro && !types.includes(plan)
   );
   checks.push(filesCheck('Native files', native), filesCheck('Entry point', entry));
   const typed = typesCheck(root, types);
@@ -108,6 +121,20 @@ function appChecks({ root, run }) {
     });
   }
 
+  // Without the navigation's Metro setup an edit that isn't a boundary of Fast Refresh reloads the app.
+  if (metro && metro.status !== 'done') {
+    checks.push({
+      group: 'app',
+      title: 'Fast Refresh',
+      status: 'warn',
+      detail: `${metro.name} doesn't use withApexNavigation: some edits reload the app`,
+      fix:
+        metro.status === 'manual'
+          ? { label: 'Wrap the config metro.config.js exports in withApexNavigation' }
+          : SETUP,
+    });
+  }
+
   // Predictive back is optional: without it the navigation works, and Android plays no back animation of its own.
   if (manifest && manifest.status !== 'done') {
     checks.push({
@@ -122,28 +149,64 @@ function appChecks({ root, run }) {
     });
   }
 
+  const configChanges = configChangesCheck(project.manifest);
+  if (configChanges) checks.push(configChanges);
+
   checks.push(...splashChecks(root, project), ...iconChecks(root, project));
 
-  // A second load of React Native crashes the app on start: the most common slip of a setup by hand.
+  // NavigationApplication leaves the load of React Native to the template's call: without it the app closes on start,
+  // and so it does with a second load of the app's own next to it.
   const application = project.mainApplication && fs.readFileSync(project.mainApplication, 'utf8');
-  if (
-    application &&
-    /:\s*NavigationApplication\(\)/.test(application) &&
-    /\bloadReactNative\s*\(/.test(codeOf(application))
-  ) {
-    checks.push({
-      group: 'app',
-      title: 'React Native loads twice',
-      status: 'error',
-      detail: 'MainApplication.kt calls loadReactNative(this), NavigationApplication loads it too',
-      fix: { label: 'Remove loadReactNative(this) from MainApplication.kt' },
-    });
+  if (application && /:\s*NavigationApplication\(/.test(application)) {
+    const loads = /\bloadReactNative\s*\(/.test(codeOf(application));
+    if (!loads) {
+      checks.push({
+        group: 'app',
+        title: 'React Native not loaded',
+        status: 'error',
+        detail: "MainApplication.kt doesn't call loadReactNative(this) in onCreate",
+        fix: SETUP,
+      });
+    } else if (loadsReactNativeItself(application)) {
+      checks.push({
+        group: 'app',
+        title: 'React Native loads twice',
+        status: 'error',
+        detail:
+          'MainApplication.kt loads React Native itself (SoLoader.init or the New Architecture entry point) next to loadReactNative(this)',
+        fix: SETUP,
+      });
+    }
   }
   const generated = generatedCheck(root, run);
   if (generated) checks.push(generated);
   return checks;
 }
 
+/**
+ * Whether the main activity handles the changes of its window itself, as the React Native template has it. Without
+ * one of them Android recreates the activity on a rotation, a resize, a fold or a light/dark switch: every screen goes
+ * with it and the navigation starts again from its root. Nothing without a manifest or a main activity.
+ * @param {string | undefined} manifest
+ * @returns {Check | undefined}
+ */
+function configChangesCheck(manifest) {
+  if (!manifest || !fs.existsSync(manifest)) return undefined;
+  const activity = mainActivity(fs.readFileSync(manifest, 'utf8'));
+  if (!activity) return undefined;
+  const value = /android:configChanges\s*=\s*(?:"([^"]*)"|'([^']*)')/.exec(activity.text);
+  const declared = (value?.[1] ?? value?.[2] ?? '').split('|').map((change) => change.trim());
+  const missing = CONFIG_CHANGES.filter((change) => !declared.includes(change));
+  if (missing.length === 0) return undefined;
+  return {
+    group: 'app',
+    title: 'Config changes',
+    status: 'warn',
+    detail: `the main activity doesn't handle ${missing.join(', ')}: Android recreates it, and every screen with it`,
+    fix: { label: `Set android:configChanges="${TEMPLATE_CONFIG_CHANGES}" on the main activity` },
+  };
+}
+
 /**
  * One line for a few files: set up, or which need setup or a change by hand.
  * @param {string} title

package/cli/doctor/checks/splash.js

@@ -17,34 +17,16 @@ const CIRCLE = 192;
 const LOGO_HEIGHT = /<dimen name="apex_navigation_splash_logo_height">([\d.]+)dp<\/dimen>/;
 
 /**
- * The native splash: made from its settings in package.json on both platforms, its logo whole on Android 12+; without
- * settings, a launch screen the navigation can't keep on screen until the first screen draws.
+ * The native splash: made from its settings in package.json on both platforms, its logo whole on Android 12+. Without
+ * settings there is nothing to check: the navigation keeps a copy of a storyboard and of `UILaunchScreen` alike.
  * @param {string} root
  * @param {Project} project
  * @returns {Check[]}
  */
 function splashChecks(root, project) {
-  const plist = project.infoPlist && fs.readFileSync(project.infoPlist, 'utf8');
   const saved = readConfig(root).splash;
-  if (!saved) {
-    // UILaunchScreen alone: iOS shows it, but the navigation keeps only a storyboard while the first screen renders.
-    if (
-      plist?.includes('<key>UILaunchScreen</key>') &&
-      !plist.includes('<key>UILaunchStoryboardName</key>')
-    ) {
-      return [
-        {
-          group: 'app',
-          title: 'Launch screen',
-          status: 'warn',
-          detail:
-            'UILaunchScreen in Info.plist: an empty window shows between it and the first screen',
-          fix: SPLASH,
-        },
-      ];
-    }
-    return [];
-  }
+  if (!saved) return [];
+  const plist = project.infoPlist && fs.readFileSync(project.infoPlist, 'utf8');
   const resolved = resolveSettings(root, {}, saved);
   if ('errors' in resolved) {
     return [

package/cli/migrate/native.js

@@ -3,6 +3,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { withReactNativeLoaded } = require('../setup/steps/mainApplication');
 
 /** @typedef {import('../changes').FileChange} FileChange */
 /** @typedef {import('./report').ReportItem} ReportItem */
@@ -158,6 +159,23 @@ function planNative(project) {
     const before = fs.readFileSync(file, 'utf8');
     let next = before;
     for (const [pattern, replacement] of rewrite.rules) next = next.replace(pattern, replacement);
+    // react-native-navigation loaded React Native itself; the navigation's application leaves it to the template's
+    // loadReactNative(this), which such an app doesn't have.
+    if (file === project.mainApplication && /:\s*NavigationApplication\(/.test(next)) {
+      const loaded = withReactNativeLoaded(next);
+      if (loaded !== undefined) next = loaded;
+      else {
+        report.push({
+          file: path.relative(root, file),
+          line: 1,
+          step: 'native',
+          before: 'onCreate',
+          after: 'super.onCreate() then loadReactNative(this), and no load of its own',
+          what: 'React Native loads through loadReactNative(this) in onCreate: add it by hand',
+          docs: `${DOCS}#native`,
+        });
+      }
+    }
     if (next !== before) {
       changes.push({
         name: path.basename(file),

package/cli/project.js

@@ -8,8 +8,9 @@ const { exec } = require('./exec');
 /**
  * The files of the app the CLI sets up, checks and adds to, where the app has them; `undefined` for one it couldn't
  * find. `styles` is the file of the app's Android theme, `styles.xml` or `themes.xml`; `manifest` its
- * `AndroidManifest.xml`. `xcodeProject` is the app's `project.pbxproj`; `androidPackage` the package of its Kotlin code (the `namespace`
- * of `android/app/build.gradle`), and `androidSources` the folder it is in.
+ * `AndroidManifest.xml`. `sceneDelegate` is the `SceneDelegate.swift` next to `AppDelegate.swift`, which apps made
+ * from React Native 0.88's template have. `xcodeProject` is the app's `project.pbxproj`; `androidPackage` the package
+ * of its Kotlin code (the `namespace` of `android/app/build.gradle`), and `androidSources` the folder it is in.
  * @typedef {{
  *   root: string;
  *   mainApplication?: string;
@@ -17,9 +18,11 @@ const { exec } = require('./exec');
  *   styles?: string;
  *   manifest?: string;
  *   appDelegate?: string;
+ *   sceneDelegate?: string;
  *   infoPlist?: string;
  *   entry?: string;
  *   app?: string;
+ *   metroConfig?: string;
  *   typescript: boolean;
  *   xcodeProject?: string;
  *   androidPackage?: string;
@@ -64,6 +67,8 @@ function findProject(root, run = exec) {
       existing(path.join(androidMain, 'res', 'values', 'themes.xml')),
     manifest: existing(path.join(androidMain, 'AndroidManifest.xml')),
     appDelegate,
+    sceneDelegate:
+      appDelegate && existing(path.join(path.dirname(appDelegate), 'SceneDelegate.swift')),
     infoPlist: appDelegate && existing(path.join(path.dirname(appDelegate), 'Info.plist')),
     entry: ['index.js', 'index.ts', 'index.tsx']
       .map((name) => path.join(root, name))
@@ -71,6 +76,9 @@ function findProject(root, run = exec) {
     app: ['App.tsx', 'App.ts', 'App.jsx', 'App.js']
       .map((name) => path.join(root, name))
       .find((file) => fs.existsSync(file)),
+    metroConfig: ['metro.config.js', 'metro.config.cjs']
+      .map((name) => path.join(root, name))
+      .find((file) => fs.existsSync(file)),
     typescript: ['App.tsx', 'App.ts', 'tsconfig.json'].some((name) =>
       fs.existsSync(path.join(root, name))
     ),

package/cli/setup/index.js

@@ -16,6 +16,8 @@ const { planEntry, navigationFile, HOW_TO: ENTRY_HOW_TO } = require('./steps/ent
 const { planEnv, targetOf } = require('./steps/env');
 const { planInfoPlist } = require('./steps/infoPlist');
 const { planMainActivity } = require('./steps/mainActivity');
+const { planMetro } = require('./steps/metro');
+const { planSceneDelegate } = require('./steps/sceneDelegate');
 const { planMainApplication } = require('./steps/mainApplication');
 const { planManifest } = require('./steps/manifest');
 const { planStyles } = require('./steps/styles');
@@ -83,6 +85,18 @@ function planProject(project) {
       planAppDelegate,
       notFound('AppDelegate.swift')
     ),
+    // React Native 0.88's template starts React Native in its scene delegate; the earlier templates have none.
+    ...(project.sceneDelegate
+      ? [
+          planFile(
+            'SceneDelegate.swift',
+            'ios',
+            project.sceneDelegate,
+            planSceneDelegate,
+            notFound('SceneDelegate.swift')
+          ),
+        ]
+      : []),
     planFile('Info.plist', 'ios', project.infoPlist, planInfoPlist, notFound('Info.plist')),
     planFile('index.js', 'js', project.entry, planEntry, ENTRY_HOW_TO),
   ];
@@ -121,6 +135,10 @@ function planProject(project) {
   plans.push(...planEnv(project.root, navigation, ts));
   // The template's App renders React Native's status bar; one moved elsewhere or written anew has nothing to change.
   if (project.app) plans.push(planFile('App.tsx', 'js', project.app, planApp, APP_HOW_TO));
+  // Fast Refresh for every edit; an app without a Metro config of its own has nothing to change.
+  if (project.metroConfig) {
+    plans.push(planFile('metro.config.js', 'js', project.metroConfig, planMetro, ''));
+  }
   return plans;
 }
 

package/cli/setup/source.js

@@ -35,7 +35,8 @@ function removeUnusedImports(text, names) {
   for (const name of names) {
     const line = new RegExp(`^import\\s+${escape(name)}[ \\t]*\\r?\\n`, 'm');
     const simple = name.slice(name.lastIndexOf('.') + 1);
-    const code = result.replace(/^import\s.*$/gm, '');
+    // A name in a comment is no use of the import.
+    const code = codeOf(result).replace(/^import\s.*$/gm, '');
     if (line.test(result) && !new RegExp(`\\b${escape(simple)}\\b`).test(code))
       result = result.replace(line, '');
   }

package/cli/setup/steps/appDelegate.js

@@ -19,7 +19,10 @@ its delegate (the bundle URL) before calling super.
       self.reactNativeDelegate = ReactNativeDelegate()
       return super.application(application, didFinishLaunchingWithOptions: launchOptions)
     }
-  }`;
+  }
+
+ReactNativeDelegate is the app's RCTDefaultReactNativeFactoryDelegate, which gives the bundle URL (bundleURL()); in
+React Native 0.88's template that method is in SceneDelegate.`;
 
 // Lines of the template's launch: ANNAppDelegate does all of it.
 const TEMPLATE_LINES = [
@@ -42,6 +45,20 @@ const LAUNCH_OVERRIDE =
 const DELEGATE = /^([ \t]*)let\s+delegate\s*=\s*ReactNativeDelegate\(\)[ \t]*$/m;
 const RETURN_TRUE = /^([ \t]*)return\s+true[ \t]*$/m;
 
+// React Native 0.88's template starts React Native in its scene delegate: the app delegate only returns true. The
+// bundle URL moves into a delegate of React Native's factory, as the earlier templates had it.
+const REACT_NATIVE_DELEGATE = `class ReactNativeDelegate: RCTDefaultReactNativeFactoryDelegate {
+  override func bundleURL() -> URL? {
+    #if DEBUG
+    RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
+    #else
+    Bundle.main.url(forResource: "main", withExtension: "jsbundle")
+    #endif
+  }
+}
+`;
+const RETURN_TRUE_OR_TRUE = /^([ \t]*)(?:return\s+)?true[ \t]*$/m;
+
 /**
  * AppDelegate.swift: the app delegate becomes an ANNAppDelegate.
  * @param {string} text
@@ -55,13 +72,30 @@ function planAppDelegate(text) {
     note: 'changed by hand, see below',
     howTo: HOW_TO,
   });
-  if (!HEADER.test(text) || !LAUNCH.test(text) || !DELEGATE.test(text)) return manual;
+  if (!HEADER.test(text) || !LAUNCH.test(text)) return manual;
+  let next = DELEGATE.test(text) ? fromFactoryLaunch(text) : fromSceneLaunch(text);
+  if (next === undefined) return manual;
 
+  // The dependency provider is ANNAppDelegate's now.
+  if (!/\bRCTAppDependencyProvider\b/.test(next)) {
+    next = next.replace(/^import\s+ReactAppDependencyProvider[ \t]*\n/m, '');
+  }
+  next = addImport(next, 'import ApexNavigation', { sorted: false });
+  return { status: 'change', next, note: 'ANNAppDelegate' };
+}
+
+/**
+ * The app delegate of the templates before React Native 0.88, which makes React Native's factory and window in its
+ * launch; undefined when the launch has code of the app's own that uses them.
+ * @param {string} text
+ * @returns {string | undefined}
+ */
+function fromFactoryLaunch(text) {
   let next = text
     .replace(HEADER, 'class $1: ANNAppDelegate {')
     .replace(LAUNCH, '$1override func$2');
   for (const line of TEMPLATE_LINES) {
-    if (!line.test(next)) return manual;
+    if (!line.test(next)) return undefined;
     next = next.replace(line, '');
   }
   next = next.replace(DELEGATE, '$1self.reactNativeDelegate = ReactNativeDelegate()');
@@ -69,10 +103,10 @@ function planAppDelegate(text) {
   // The launch now ends in super's, which starts React Native.
   const launchAt = next.search(LAUNCH_OVERRIDE);
   const returnAt = next.slice(launchAt).search(RETURN_TRUE);
-  if (returnAt < 0) return manual;
+  if (returnAt < 0) return undefined;
   const body = next.slice(launchAt, launchAt + returnAt).replace(/self\.reactNativeDelegate/g, '');
   // Code of the app's own that used the template's factory, delegate or window: it has to move by hand.
-  if (/\b(factory|delegate|window)\b/.test(body)) return manual;
+  if (/\b(factory|delegate|window)\b/.test(body)) return undefined;
   const rest = next
     .slice(launchAt + returnAt)
     .replace(
@@ -82,17 +116,38 @@ function planAppDelegate(text) {
   next = next.slice(0, launchAt + returnAt) + rest;
 
   // The blank lines the template's launch leaves behind.
-  next = next
+  return next
     .replace(/(class\s+\w+:\s*ANNAppDelegate\s*\{\n)(?:[ \t]*\n)+/, '$1')
     .replace(/(self\.reactNativeDelegate = ReactNativeDelegate\(\)\n)(?:[ \t]*\n)+/, '$1')
     .replace(/\n(?:[ \t]*\n)+([ \t]*return super\.application\()/, '\n$1');
+}
 
-  // The dependency provider is ANNAppDelegate's now.
-  if (!/\bRCTAppDependencyProvider\b/.test(next)) {
-    next = next.replace(/^import\s+ReactAppDependencyProvider[ \t]*\n/m, '');
+/**
+ * The app delegate of React Native 0.88's template, whose launch only returns true; undefined when the app delegate
+ * makes React Native or a window of its own.
+ * @param {string} text
+ * @returns {string | undefined}
+ */
+function fromSceneLaunch(text) {
+  if (/\b(RCTReactNativeFactory|ReactNativeDelegate|window)\b/.test(text)) return undefined;
+  let next = text
+    .replace(HEADER, 'class $1: ANNAppDelegate {')
+    .replace(LAUNCH, '$1override func$2');
+  const launchAt = next.search(LAUNCH_OVERRIDE);
+  const returnAt = next.slice(launchAt).search(RETURN_TRUE_OR_TRUE);
+  if (returnAt < 0) return undefined;
+  const rest = next
+    .slice(launchAt + returnAt)
+    .replace(
+      RETURN_TRUE_OR_TRUE,
+      '$1self.reactNativeDelegate = ReactNativeDelegate()\n' +
+        '$1return super.application(application, didFinishLaunchingWithOptions: launchOptions)'
+    );
+  next = `${next.slice(0, launchAt + returnAt)}${rest.trimEnd()}\n\n${REACT_NATIVE_DELEGATE}`;
+  for (const module of ['React', 'React_RCTAppDelegate']) {
+    next = addImport(next, `import ${module}`, { sorted: false });
   }
-  next = addImport(next, 'import ApexNavigation', { sorted: false });
-  return { status: 'change', next, note: 'ANNAppDelegate' };
+  return next;
 }
 
 module.exports = { planAppDelegate };

package/cli/setup/steps/mainApplication.js

@@ -5,24 +5,51 @@ const { addImport, codeOf, removeUnusedImports } = require('../source');
 
 /** @typedef {import('./types').StepResult} StepResult */
 
-const HOW_TO = `Extend NavigationApplication. It loads React Native itself, so loadReactNative(this) goes:
-calling it again crashes the app on start.
+const HOW_TO = `Extend NavigationApplication and keep the template's loadReactNative(this) in onCreate: it loads
+React Native as the app's Gradle files say, and the navigation makes its React host after it.
 
+  import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative
   import dev.apexnative.navigation.NavigationApplication
 
   class MainApplication : NavigationApplication() {
     override val reactHost: ReactHost by lazy { ... }   // as it is
+
+    override fun onCreate() {
+      super.onCreate()
+      loadReactNative(this)
+    }
   }`;
 
+const LOAD_IMPORT = 'import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative';
+
 // Imports of the template that the change leaves unused.
-const TEMPLATE_IMPORTS = [
-  'android.app.Application',
-  'com.facebook.react.ReactApplication',
-  'com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative',
+const TEMPLATE_IMPORTS = ['android.app.Application', 'com.facebook.react.ReactApplication'];
+
+// A load of React Native of the app's own, next to loadReactNative(this) a second one that crashes the app at start:
+// the New Architecture's entry point (react-native-navigation's apps call it in onCreate) and SoLoader.
+// A bare `load()` is the entry point's only where the file imports it. A form these don't take out (`load` with
+// arguments, an `if` without braces) is left to the app's author.
+const OWN_LOAD = [
+  /^[ \t]*if\s*\(\s*BuildConfig\.IS_NEW_ARCHITECTURE_ENABLED\s*\)\s*\{(?:\s*\/\/[^\n]*)*\s*DefaultNewArchitectureEntryPoint\.load\(\)\s*\}[ \t]*\r?\n/gm,
+  /^[ \t]*DefaultNewArchitectureEntryPoint\.load\(\)[ \t]*\r?\n/gm,
+  /^[ \t]*SoLoader\.init\([^\n]*\)[ \t]*\r?\n/gm,
+];
+const BARE_LOAD = [
+  /^[ \t]*if\s*\(\s*BuildConfig\.IS_NEW_ARCHITECTURE_ENABLED\s*\)\s*\{(?:\s*\/\/[^\n]*)*\s*load\(\)\s*\}[ \t]*\r?\n/gm,
+  /^[ \t]*load\(\)[ \t]*\r?\n/gm,
+];
+const BARE_LOAD_IMPORT =
+  /^import\s+com\.facebook\.react\.defaults\.DefaultNewArchitectureEntryPoint\.load\b/m;
+const OWN_LOAD_IMPORTS = [
+  'com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.load',
+  'com.facebook.react.defaults.DefaultNewArchitectureEntryPoint',
+  'com.facebook.soloader.SoLoader',
+  'com.facebook.react.soloader.OpenSourceMergedSoMapping',
 ];
 
 /**
- * MainApplication.kt: the application becomes a NavigationApplication.
+ * MainApplication.kt: the application becomes a NavigationApplication, and loads React Native in its onCreate as the
+ * template does.
  * @param {string} text
  * @returns {StepResult}
  */
@@ -32,21 +59,20 @@ function planMainApplication(text) {
     note: 'changed by hand, see below',
     howTo: HOW_TO,
   });
-  if (/:\s*NavigationApplication\(\)/.test(text)) {
-    return /\bloadReactNative\s*\(/.test(codeOf(text))
+  if (/:\s*NavigationApplication\(/.test(text)) {
+    if (loadsReactNative(text) && !loadsReactNativeItself(text)) {
+      return { status: 'done', note: 'already set up' };
+    }
+    const next = withReactNativeLoaded(text);
+    return next === undefined
       ? manual
-      : { status: 'done', note: 'already set up' };
+      : { status: 'change', next, note: 'loadReactNative(this) in onCreate' };
   }
   const header = /class\s+(\w+)\s*:\s*Application\(\)\s*,\s*ReactApplication\b/;
   if (!header.test(text)) return manual;
-  let next = text.replace(header, 'class $1 : NavigationApplication()');
-  // The template's onCreate only loads React Native, so it goes; another one keeps the rest of its code.
-  next = next.replace(
-    /\n\n?[ \t]*override\s+fun\s+onCreate\(\)\s*\{\s*super\.onCreate\(\)\s*loadReactNative\(this\)\s*\}/,
-    ''
-  );
-  next = next.replace(/^[ \t]*loadReactNative\(this\)[ \t]*\r?\n/m, '');
-  if (/\bloadReactNative\s*\(/.test(codeOf(next))) return manual;
+  // The template's onCreate stays: its loadReactNative(this) loads React Native for the navigation too.
+  let next = withReactNativeLoaded(text.replace(header, 'class $1 : NavigationApplication()'));
+  if (next === undefined) return manual;
   // Added first: with the template's imports gone the file would have none to sort it among.
   next = addImport(next, 'import dev.apexnative.navigation.NavigationApplication', {
     sorted: true,
@@ -55,4 +81,93 @@ function planMainApplication(text) {
   return { status: 'change', next, note: 'NavigationApplication' };
 }
 
-module.exports = { planMainApplication };
+/**
+ * Whether the code of the file, not a comment, calls loadReactNative.
+ * @param {string} text
+ */
+function loadsReactNative(text) {
+  return /\bloadReactNative\s*\(/.test(codeOf(text));
+}
+
+/**
+ * Whether the code of the file loads React Native on its own as well: the New Architecture's entry point or SoLoader.
+ * @param {string} text
+ */
+function loadsReactNativeItself(text) {
+  const code = codeOf(text);
+  return (
+    /\bSoLoader\.init\s*\(/.test(code) ||
+    /\bDefaultNewArchitectureEntryPoint\.load\s*\(/.test(code) ||
+    (BARE_LOAD_IMPORT.test(text) && /(?<![\w.])load\s*\(/.test(code))
+  );
+}
+
+/**
+ * The application with `loadReactNative(this)` in its onCreate, after `super.onCreate()`: as it is when it has the
+ * call, with an onCreate of the template's when it has none. Undefined for an onCreate that doesn't call
+ * `super.onCreate()`, whose order only its author knows.
+ * @param {string} text
+ * @returns {string | undefined}
+ */
+function withReactNativeLoaded(text) {
+  let without = text;
+  const patterns = BARE_LOAD_IMPORT.test(text) ? [...OWN_LOAD, ...BARE_LOAD] : OWN_LOAD;
+  for (const pattern of patterns) without = without.replace(pattern, '');
+  without = removeUnusedImports(without, OWN_LOAD_IMPORTS);
+  if (loadsReactNativeItself(without)) return undefined;
+  if (loadsReactNative(without)) return without;
+  return withLoadCall(without);
+}
+
+/**
+ * @param {string} text an application without a load of React Native
+ * @returns {string | undefined}
+ */
+function withLoadCall(text) {
+  let next;
+  const superCall = /^([ \t]*)super\.onCreate\(\)[ \t]*\r?\n/m;
+  if (/\boverride\s+fun\s+onCreate\s*\(/.test(text)) {
+    if (!superCall.test(text)) return undefined;
+    next = text.replace(superCall, (line, indent) => `${line}${indent}loadReactNative(this)\n`);
+  } else {
+    const close = classEnd(text);
+    if (close === undefined) return undefined;
+    const indent = /^([ \t]+)override\b/m.exec(text)?.[1] ?? '  ';
+    const body = text.slice(0, close).replace(/\s*$/, '');
+    const onCreate = [
+      '',
+      `${indent}override fun onCreate() {`,
+      `${indent}${indent}super.onCreate()`,
+      `${indent}${indent}loadReactNative(this)`,
+      `${indent}}`,
+    ].join('\n');
+    next = `${body}\n${onCreate}\n${text.slice(close)}`;
+  }
+  return addImport(next, LOAD_IMPORT, { sorted: true });
+}
+
+/**
+ * The index of the closing brace of the file's application class: its braces counted from the class's own, past any
+ * declaration or comment after it. Undefined when the braces don't close.
+ * @param {string} text
+ * @returns {number | undefined}
+ */
+function classEnd(text) {
+  // The comments and the string and character literals blanked out, so that an index in it is one in the text and a
+  // brace in a literal doesn't count.
+  const blank = (/** @type {string} */ part) => part.replace(/[^\n]/g, ' ');
+  const code = text
+    .replace(/\/\*[\s\S]*?\*\//g, blank)
+    .replace(/\/\/.*$/gm, blank)
+    .replace(/"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'/g, blank);
+  const header = /\bclass\s+\w+\s*:[^{]*\{/.exec(code);
+  if (!header) return undefined;
+  let depth = 0;
+  for (let index = header.index + header[0].length - 1; index < code.length; index++) {
+    if (code[index] === '{') depth++;
+    else if (code[index] === '}' && --depth === 0) return index;
+  }
+  return undefined;
+}
+
+module.exports = { planMainApplication, withReactNativeLoaded, loadsReactNativeItself };

package/cli/setup/steps/metro.js

@@ -0,0 +1,46 @@
+// @ts-check
+'use strict';
+
+/** @typedef {import('./types').StepResult} StepResult */
+
+const REQUIRE = "const { withApexNavigation } = require('@apexnative/navigation/metro');";
+
+// The config the file exports: `module.exports = …;`, its last statement.
+const EXPORT = /^module\.exports\s*=\s*([\s\S]+?);?\s*$/m;
+
+const HOW_TO = `Wrap the config metro.config.js exports, so an edit updates the app by Fast Refresh instead of
+reloading it:
+
+  ${REQUIRE}
+
+  module.exports = withApexNavigation(mergeConfig(getDefaultConfig(__dirname), config));`;
+
+/**
+ * metro.config.js: the config it exports goes through withApexNavigation, which puts the navigation's Babel
+ * transformer in front of the app's own.
+ * @param {string} text
+ * @returns {StepResult}
+ */
+function planMetro(text) {
+  if (text.includes('withApexNavigation')) return { status: 'done', note: 'already set up' };
+  const found = EXPORT.exec(text);
+  // Only an export that ends the file: one in the middle may be changed by what comes after it.
+  if (!found || text.slice(found.index + found[0].length).trim() !== '') {
+    return { status: 'manual', note: 'changed by hand, see below', howTo: HOW_TO };
+  }
+  const exported = found[1].trim();
+  const before = text.slice(0, found.index);
+  const requires = [...before.matchAll(/^.*require\(.*\);?$/gm)];
+  const last = requires[requires.length - 1];
+  const head =
+    last === undefined
+      ? `${REQUIRE}\n\n${before}`
+      : `${before.slice(0, last.index + last[0].length)}\n${REQUIRE}${before.slice(last.index + last[0].length)}`;
+  return {
+    status: 'change',
+    next: `${head}module.exports = withApexNavigation(${exported});\n`,
+    note: 'Fast Refresh for every edit',
+  };
+}
+
+module.exports = { planMetro, HOW_TO };