feat: add deeplinks to our documentation

These changes will only start to work once our documentation is updated to support this feature: - facebook/react-native-website#3618 - facebook/react-native-website#3619 - facebook/react-native-website#3620
blakef · Mar 20, 2023 · bde1e1f · bde1e1f
1 parent f3218c3
commit bde1e1f
Show file tree

Hide file tree

Showing 19 changed files with 258 additions and 13 deletions.
diff --git a/__e2e__/__snapshots__/config.test.ts.snap b/__e2e__/__snapshots__/config.test.ts.snap
@@ -4,6 +4,7 @@ exports[`shows up current config without unnecessary output 1`] = `
 {
   "root": "<<REPLACED_ROOT>>/TestProject",
   "reactNativePath": "<<REPLACED_ROOT>>/TestProject/node_modules/react-native",
+  "reactNativeVersion": "0.71",
   "dependencies": {},
   "commands": [
     {

diff --git a/babel.config.js b/babel.config.js
@@ -18,6 +18,7 @@ module.exports = {
   ],
   plugins: [
     [require.resolve('@babel/plugin-transform-modules-commonjs'), {lazy: true}],
+    '@babel/plugin-proposal-export-namespace-from',
   ],
   sourceMaps: true,
 };
diff --git a/package.json b/package.json
@@ -23,6 +23,7 @@
   },
   "devDependencies": {
     "@babel/core": "^7.0.0",
+    "@babel/plugin-proposal-export-namespace-from": "^7.18.9",
     "@babel/plugin-transform-modules-commonjs": "^7.2.0",
     "@babel/plugin-transform-runtime": "^7.6.2",
     "@babel/preset-env": "^7.0.0",

diff --git a/packages/cli-config/src/__tests__/__snapshots__/index-test.ts.snap b/packages/cli-config/src/__tests__/__snapshots__/index-test.ts.snap
@@ -25,6 +25,7 @@ Object {
   "platforms": Object {},
   "project": Object {},
   "reactNativePath": "<<REPLACED>>",
+  "reactNativeVersion": "unknown",
   "root": "<<REPLACED>>",
 }
 `;

diff --git a/packages/cli-config/src/loadConfig.ts b/packages/cli-config/src/loadConfig.ts
@@ -1,4 +1,6 @@
 import path from 'path';
+import fs from 'fs';
+import semver from 'semver';
 import {
   UserDependencyConfig,
   ProjectConfig,
@@ -65,6 +67,7 @@ function loadConfig(projectRoot: string = findProjectRoot()): Config {
         ? path.resolve(projectRoot, userConfig.reactNativePath)
         : resolveReactNativePath(projectRoot);
     },
+    reactNativeVersion: 'unknown',
     dependencies: userConfig.dependencies,
     commands: userConfig.commands,
     healthChecks: [],
@@ -89,6 +92,25 @@ function loadConfig(projectRoot: string = findProjectRoot()): Config {
     },
   };
 
+  // Try our best to figure out what version of React Native we're running. This is
+  // currently being used to get our deeplinks working, so it's only worried with
+  // the major and minor version.
+  try {
+    const {version} = JSON.parse(
+      fs.readFileSync(
+        path.join(initialConfig.reactNativePath, 'package.json'),
+        {encoding: 'utf8'},
+      ),
+    );
+    const out = semver.parse(version);
+    if (out) {
+      // Retain only these version, since they correspond with our documentation.
+      initialConfig.reactNativeVersion = `${out.major}.${out.minor}`;
+    }
+  } catch (_) {
+    // We don't seem to be in a well formed project, give up quietly.
+  }
+
   const finalConfig = Array.from(
     new Set([
       ...Object.keys(userConfig.dependencies),

diff --git a/packages/cli-doctor/src/tools/healthchecks/androidSDK.ts b/packages/cli-doctor/src/tools/healthchecks/androidSDK.ts
@@ -1,4 +1,4 @@
-import {findProjectRoot, logger} from '@react-native-community/cli-tools';
+import {findProjectRoot, logger, link} from '@react-native-community/cli-tools';
 import chalk from 'chalk';
 import fs from 'fs';
 import path from 'path';
@@ -182,7 +182,11 @@ export default {
 
     return logManualInstallation({
       healthcheck: 'Android SDK',
-      url: 'https://reactnative.dev/docs/environment-setup',
+      url: link.docs('environment-setup', {
+        hash: 'android-sdk',
+        guide: 'native',
+        platform: 'android',
+      }),
     });
   },
 } as HealthCheckInterface;
diff --git a/packages/cli-doctor/src/tools/healthchecks/androidStudio.ts b/packages/cli-doctor/src/tools/healthchecks/androidStudio.ts
@@ -1,5 +1,7 @@
 import {join} from 'path';
 
+import {link} from '@react-native-community/cli-tools';
+
 import {HealthCheckInterface} from '../../types';
 
 import {downloadAndUnzip} from '../downloadAndUnzip';
@@ -74,7 +76,11 @@ export default {
 
     return logManualInstallation({
       healthcheck: 'Android Studio',
-      url: 'https://reactnative.dev/docs/environment-setup',
+      url: link.docs('environment-setup', {
+        hash: 'android-studio',
+        guide: 'native',
+        platform: 'android',
+      }),
     });
   },
 } as HealthCheckInterface;
diff --git a/packages/cli-doctor/src/tools/healthchecks/jdk.ts b/packages/cli-doctor/src/tools/healthchecks/jdk.ts
@@ -1,4 +1,7 @@
 import {join} from 'path';
+
+import {link} from '@react-native-community/cli-tools';
+
 import versionRanges from '../versionRanges';
 import {doesSoftwareNeedToBeFixed} from '../checkInstallation';
 import {HealthCheckInterface} from '../../types';
@@ -58,7 +61,11 @@ export default {
     loader.fail();
     logManualInstallation({
       healthcheck: 'JDK',
-      url: 'https://reactnative.dev/docs/environment-setup',
+      url: link.docs('environment-setup', {
+        hash: 'jdk-studio',
+        guide: 'native',
+        platform: 'android',
+      }),
     });
   },
 } as HealthCheckInterface;
diff --git a/packages/cli-doctor/src/tools/healthchecks/ruby.ts b/packages/cli-doctor/src/tools/healthchecks/ruby.ts
@@ -1,7 +1,7 @@
 import execa from 'execa';
 import chalk from 'chalk';
 
-import {logger, findProjectRoot} from '@react-native-community/cli-tools';
+import {logger, findProjectRoot, link} from '@react-native-community/cli-tools';
 
 import versionRanges from '../versionRanges';
 import {doesSoftwareNeedToBeFixed} from '../checkInstallation';
@@ -174,7 +174,11 @@ export default {
 
     logManualInstallation({
       healthcheck: 'Ruby',
-      url: 'https://reactnative.dev/docs/environment-setup#ruby',
+      url: link.docs('environment-setup', {
+        hash: 'ruby',
+        guide: 'native',
+        platform: 'ios',
+      }),
     });
   },
 } as HealthCheckInterface;
diff --git a/packages/cli-doctor/src/tools/installPods.ts b/packages/cli-doctor/src/tools/installPods.ts
@@ -1,7 +1,7 @@
 import fs from 'fs';
 import execa from 'execa';
 import chalk from 'chalk';
-import {logger, NoopLoader} from '@react-native-community/cli-tools';
+import {logger, NoopLoader, link} from '@react-native-community/cli-tools';
 import sudo from 'sudo-prompt';
 import runBundleInstall from './runBundleInstall';
 import {Loader} from '../types';
@@ -38,7 +38,9 @@ async function runPodInstall(
       logger.error(stderr);
 
       throw new Error(
-        'Looks like your iOS environment is not properly set. Please go to https://reactnative.dev/docs/next/environment-setup and follow the React Native CLI QuickStart guide for macOS and iOS.',
+        `Looks like your iOS environment is not properly set. Please go to ${link.docs(
+          'environment-setup',
+        )} and follow the React Native CLI QuickStart guide for macOS and iOS.`,
       );
     }
   }

diff --git a/packages/cli-doctor/src/tools/runBundleInstall.ts b/packages/cli-doctor/src/tools/runBundleInstall.ts
@@ -1,5 +1,5 @@
 import execa from 'execa';
-import {CLIError, logger} from '@react-native-community/cli-tools';
+import {CLIError, logger, link} from '@react-native-community/cli-tools';
 
 import {Loader} from '../types';
 
@@ -12,7 +12,9 @@ async function runBundleInstall(loader: Loader) {
     loader.fail();
     logger.error((error as any).stderr || (error as any).stdout);
     throw new CLIError(
-      'Looks like your iOS environment is not properly set. Please go to https://reactnative.dev/docs/next/environment-setup and follow the React Native CLI QuickStart guide for macOS and iOS.',
+      `Looks like your iOS environment is not properly set. Please go to ${link.docs(
+        'environment-setup',
+      )} and follow the React Native CLI QuickStart guide for macOS and iOS.`,
     );
   }
 

diff --git a/packages/cli-platform-android/src/commands/runAndroid/index.ts b/packages/cli-platform-android/src/commands/runAndroid/index.ts
@@ -13,7 +13,7 @@ import tryRunAdbReverse from './tryRunAdbReverse';
 import tryLaunchAppOnDevice from './tryLaunchAppOnDevice';
 import tryInstallAppOnDevice from './tryInstallAppOnDevice';
 import getAdbPath from './getAdbPath';
-import {logger, CLIError} from '@react-native-community/cli-tools';
+import {logger, CLIError, link} from '@react-native-community/cli-tools';
 import {getAndroidProject} from '../../config/getAndroidProject';
 import listAndroidDevices from './listAndroidDevices';
 import tryLaunchEmulator from './tryLaunchEmulator';
@@ -38,6 +38,12 @@ export type AndroidProject = NonNullable<Config['project']['android']>;
  * Starts the app on a connected Android emulator or device.
  */
 async function runAndroid(_argv: Array<string>, config: Config, args: Flags) {
+  link.setPlatform('android');
+
+  if (config.reactNativeVersion !== 'unknown') {
+    link.setVersion(config.reactNativeVersion);
+  }
+
   if (args.binaryPath) {
     if (args.tasks) {
       throw new CLIError(

diff --git a/packages/cli-platform-ios/src/commands/runIOS/index.ts b/packages/cli-platform-ios/src/commands/runIOS/index.ts
@@ -12,7 +12,7 @@ import fs from 'fs';
 import chalk from 'chalk';
 import {Config, IOSProjectInfo} from '@react-native-community/cli-types';
 import {getDestinationSimulator} from '../../tools/getDestinationSimulator';
-import {logger, CLIError} from '@react-native-community/cli-tools';
+import {logger, CLIError, link} from '@react-native-community/cli-tools';
 import {BuildFlags, buildProject} from '../buildIOS/buildProject';
 import {iosBuildOptions} from '../buildIOS';
 import {Device} from '../../types';
@@ -35,6 +35,12 @@ export interface FlagsT extends BuildFlags {
 }
 
 async function runIOS(_: Array<string>, ctx: Config, args: FlagsT) {
+  link.setPlatform('ios');
+
+  if (ctx.reactNativeVersion !== 'unknown') {
+    link.setVersion(ctx.reactNativeVersion);
+  }
+
   if (!ctx.project.ios) {
     throw new CLIError(
       'iOS project folder not found. Are you sure this is a React Native project?',

diff --git a/packages/cli-tools/src/__tests__/doclink.test.ts b/packages/cli-tools/src/__tests__/doclink.test.ts
@@ -0,0 +1,56 @@
+import * as link from '../doclink';
+
+const mockPlatform = jest.fn().mockReturnValue('darwin');
+jest.mock('os', () => ({
+  platform: mockPlatform,
+}));
+
+describe('link', () => {
+  it('builds a link with the platform and os defined', () => {
+    mockPlatform.mockReturnValueOnce('darwin');
+    link.setPlatform('android');
+
+    const url = new URL(link.docs('environment-setup')).toString();
+    expect(url).toMatch(/os=macos/);
+    expect(url).toMatch(/platform=android/);
+    expect(url).toEqual(
+      expect.stringContaining('https://reactnative.dev/docs/environment-setup'),
+    );
+
+    // Handles a change of os
+    mockPlatform.mockReturnValueOnce('win32');
+    expect(link.docs('environment-setup')).toMatch(/os=windows/);
+
+    // Handles a change of platform
+    link.setPlatform('ios');
+    expect(link.docs('environment-setup')).toMatch(/platform=ios/);
+  });
+
+  it('preserves anchor-links', () => {
+    expect(link.docs('environment-setup', 'ruby')).toMatch(/#ruby/);
+  });
+
+  describe('overrides', () => {
+    afterAll(() => link.setVersion(null));
+    it.each([
+      [{hash: 'ruby'}, /#ruby/],
+      [{hash: 'ruby', os: 'linux'}, /os=linux/],
+      [{platform: 'ios'}, /platform=ios/],
+      [{'extra stuff': 'here?ok'}, /extra\+stuff=here%3Fok/],
+    ])("link.doc('environment-setup, %o) -> %o", (param, re) => {
+      expect(link.docs('environment-setup', param)).toMatch(re);
+    });
+  });
+
+  describe('versions', () => {
+    afterAll(() => link.setVersion(null));
+    it('supports linking to a specific version of React Native', () => {
+      link.setVersion('0.71');
+      expect(link.docs('environment-setup', 'ruby')).toEqual(
+        expect.stringContaining(
+          'https://reactnative.dev/docs/0.71/environment-setup',
+        ),
+      );
+    });
+  });
+});