@rnx-kit/cli 0.12.5 → 0.14.0

package/react-native.config.js

@@ -2,6 +2,7 @@ const { parsePlatform } = require("@rnx-kit/tools-react-native/platform");
 const path = require("path");
 const {
   parseBoolean,
+  parseTransformProfile,
   rnxBundle,
   rnxCopyAssetsCommand,
   rnxStart,
@@ -15,83 +16,87 @@ module.exports = {
   commands: [
     {
       name: "rnx-bundle",
-      description: "Bundle your react-native experience for offline use",
+      description:
+        "Bundle your rnx-kit package for offline use. See https://aka.ms/rnx-kit.",
       func: rnxBundle,
       options: [
         {
           name: "--id [id]",
           description:
-            "Target bundle definition. This is only needed when the kit configuration has multiple bundle definitions.",
+            "Target bundle definition. This is only needed when the rnx-kit configuration has multiple bundle definitions.",
         },
         {
-          name: "--platform [ios|android|windows|win32|macos]",
+          name: "--entry-file [path]",
           description:
-            "Target platform. When not given, all platforms in the kit configuration are bundled.",
-          parse: parsePlatform,
+            "Path to the root JavaScript or TypeScript file, either absolute or relative to the package.",
         },
         {
-          name: "--entry-path [file]",
+          name: "--platform [ios|android|windows|win32|macos]",
           description:
-            "Path to the root JavaScript file, either absolute or relative to the kit package.",
+            "Target platform. When not given, all platforms in the rnx-kit configuration are bundled.",
+          parse: parsePlatform,
         },
         {
-          name: "--dist-path [path]",
+          name: "--dev [boolean]",
           description:
-            "Path where the bundle is written, either absolute or relative to the kit package.",
+            "If false, warnings are disabled and the bundle is minified.",
+          default: true,
+          parse: parseBoolean,
         },
         {
-          name: "--assets-path [path]",
+          name: "--minify [boolean]",
           description:
-            "Path where bundle assets like images are written, either absolute or relative to the kit package.",
+            "Controls whether or not the bundle is minified. Disabling minification is useful for test builds.",
+          parse: parseBoolean,
         },
         {
-          name: "--bundle-prefix [prefix]",
+          name: "--bundle-output [string]",
           description:
-            "Bundle file prefix. This is followed by the platform and bundle file extension.",
+            "Path to the output bundle file, either absolute or relative to the package.",
         },
         {
           name: "--bundle-encoding [utf8|utf16le|ascii]",
           description:
             "Character encoding to use when writing the bundle file.",
+          default: "utf8",
         },
         {
-          name: "--dev [boolean]",
+          name: "--max-workers [number]",
           description:
-            "If false, warnings are disabled and the bundle is minified.",
-          default: true,
-          parse: parseBoolean,
+            "Specifies the maximum number of parallel worker threads to use for transforming files. This defaults to the number of cores available on your machine.",
+          parse: parseInt,
         },
         {
-          name: "--minify [boolean]",
+          name: "--sourcemap-output [string]",
           description:
-            "Controls whether or not the bundle is minified. Disabling minification is useful for test builds.",
-          parse: parseBoolean,
+            "Path where the bundle source map is written, either absolute or relative to the package.",
         },
         {
-          name: "--experimental-tree-shake [boolean]",
-          description: "Deprecated. Use --tree-shake [boolean] instead.",
-          parse: parseBoolean,
+          name: "--sourcemap-sources-root [string]",
+          description:
+            "Path to use when relativizing file entries in the bundle source map.",
         },
         {
-          name: "--tree-shake [boolean]",
-          description: "Enable tree shaking.",
-          parse: parseBoolean,
+          name: "--sourcemap-use-absolute-path",
+          description: "Report SourceMapURL using its full path",
         },
         {
-          name: "--max-workers [number]",
+          name: "--assets-dest [path]",
           description:
-            "Specifies the maximum number of parallel worker threads to use for transforming files. This defaults to the number of cores available on your machine.",
-          parse: parseInt,
+            "Path where bundle assets like images are written, either absolute or relative to the package. If not given, assets are ignored.",
         },
         {
-          name: "--sourcemap-output [string]",
+          name: "--tree-shake [boolean]",
           description:
-            "Path where the bundle source map is written, either absolute or relative to the dist-path.",
+            "Enable tree shaking to remove unused code and reduce the bundle size.",
+          parse: parseBoolean,
+          default: false,
         },
         {
-          name: "--sourcemap-sources-root [string]",
+          name: "--unstable-transform-profile [string]",
           description:
-            "Path to use when relativizing file entries in the bundle source map.",
+            "Experimental, transform JS for a specific JS engine. Currently supported: hermes, hermes-canary, default",
+          parse: parseTransformProfile,
         },
         {
           name: "--reset-cache",
@@ -109,12 +114,6 @@ module.exports = {
       description:
         "Start a bundle-server to host your react-native experience during development",
       options: [
-        {
-          name: "--host [string]",
-          description:
-            "Host name or address to bind when listening for incoming server requests. When not given, requests from all addresses are accepted.",
-          default: "",
-        },
         {
           name: "--port [number]",
           description:
@@ -123,25 +122,31 @@ module.exports = {
           default: 8081,
         },
         {
-          name: "--project-root [path]",
+          name: "--host [string]",
           description:
-            "Path to the root of your react-native experience project. The bundle server uses this root path to resolve all web requests.",
+            "Host name or address to bind when listening for incoming server requests. When not given, requests from all addresses are accepted.",
+          default: "",
+        },
+        {
+          name: "--projectRoot [path]",
+          description:
+            "Path to the root of your react-native project. The bundle server uses this root path to resolve all web requests.",
           parse: (val) => path.resolve(val),
         },
         {
-          name: "--watch-folders [paths]",
+          name: "--watchFolders [paths]",
           description:
-            "Additional folders which will be added to the file-watch list. Comma-separated. By default, Metro watches all project files, and triggers a bundle-reload when anything changes.",
+            "Additional folders which will be added to the file-watch list. Comma-separated. By default, Metro watches all project files.",
           parse: (val) => val.split(",").map((folder) => path.resolve(folder)),
         },
         {
-          name: "--asset-plugins [list]",
+          name: "--assetPlugins [list]",
           description:
-            "Additional asset plugins to be used by the Metro Babel transformer. Comma-separated list containing plugin modules and/or absolute paths to plugin packages.",
+            "Additional asset plugins to be used by the Metro Babel transformer. Comma-separated list containing plugin module names or absolute paths to plugin packages.",
           parse: (val) => val.split(","),
         },
         {
-          name: "--source-exts [list]",
+          name: "--sourceExts [list]",
           description:
             "Additional source-file extensions to include when generating bundles. Comma-separated list, excluding the leading dot.",
           parse: (val) => val.split(","),
@@ -152,6 +157,10 @@ module.exports = {
             "Specifies the maximum number of parallel worker threads to use for transforming files. This defaults to the number of cores available on your machine.",
           parse: parseInt,
         },
+        {
+          name: "--reset-cache",
+          description: "Reset the Metro cache.",
+        },
         {
           name: "--custom-log-reporter-path [string]",
           description:
@@ -172,10 +181,6 @@ module.exports = {
           description:
             "Path to a custom SSL certificate file to use for secure (https) communication.",
         },
-        {
-          name: "--reset-cache",
-          description: "Reset the Metro cache.",
-        },
         {
           name: "--config [string]",
           description: "Path to the Metro configuration file.",
@@ -198,41 +203,43 @@ module.exports = {
         {
           name: "--root-path <path>",
           description:
-            "The root of the repo where to start resolving modules from.",
+            "The root of the repo. This is the starting point for finding each module in the source map dependency graph.",
         },
         {
           name: "--source-map-file <file>",
-          description: "The sourceMap file to generate licence contents for.",
+          description:
+            "The source map file associated with the package's entry file. This source map eventually leads to all package dependencies and their licenses.",
         },
         {
           name: "--json",
-          description: "Output license information as a JSON",
+          description:
+            "Format the 3rd-party notice file as JSON instead of text.",
           default: false,
           parse: parseBoolean,
         },
         {
           name: "--output-file [file]",
-          description: "The output file to write the licence file to.",
+          description:
+            "The path to use when writing the 3rd-party notice file.",
         },
         {
           name: "--ignore-scopes [string]",
           description:
-            "Comma separated list of npm scopes to ignore and not emit licence information for",
+            "Comma-separated list of `npm` scopes to ignore when traversing the source map dependency graph.",
         },
         {
           name: "--ignore-modules [string]",
           description:
-            "Comma separated list of modules (js packages) to not emit licence information for ",
+            "Comma-separated list of modules to ignore when traversing the source map dependency graph.",
         },
         {
           name: "--preamble-text [string]",
           description:
-            "A string to prepend at the start of the generated licence file.",
+            "A string to prepend to the start of the 3rd-party notice.",
         },
         {
           name: "--additional-text [path]",
-          description:
-            "A string to append at the end of the generated licence file.",
+          description: "A string to append to the end of the 3rd-party notice.",
         },
       ],
     },

package/src/bundle/kit-config.ts

@@ -1,49 +1,11 @@
-import type { BundleDefinitionWithRequiredParameters } from "@rnx-kit/config";
 import {
-  getBundleDefinition,
-  getBundlePlatformDefinition,
+  getBundleConfig,
+  getPlatformBundleConfig,
   getKitConfig,
 } from "@rnx-kit/config";
-import { warn } from "@rnx-kit/console";
 import type { AllPlatforms } from "@rnx-kit/tools-react-native/platform";
-import chalk from "chalk";
-import type { KitBundleConfig } from "./types";
-
-/**
- * Get a bundle definition from the kit configuration.
- *
- * @param id Optional bundle definition id. Only needed when the kit config has more than one definition.
- * @returns Bundle definition matching the id (if given), or the first bundle definition found. `undefined` if bundling is disabled or not supported for the kit.
- */
-export function getKitBundleDefinition(
-  id?: string
-): BundleDefinitionWithRequiredParameters | undefined {
-  const kitConfig = getKitConfig();
-  if (!kitConfig) {
-    throw new Error(
-      "No kit configuration found for this react-native experience"
-    );
-  }
-
-  if (kitConfig.bundle === null || kitConfig.bundle === undefined) {
-    warn(
-      chalk.yellow(
-        "No bundle configuration found for this react-native experience -- skipping bundling"
-      )
-    );
-    return undefined;
-  } else if (!kitConfig.bundle) {
-    warn(
-      chalk.yellow(
-        "Bundling is disabled for this react-native experience -- skipping"
-      )
-    );
-    return undefined;
-  }
-
-  // get the bundle definition
-  return getBundleDefinition(kitConfig.bundle, id);
-}
+import type { CliPlatformBundleConfig } from "./types";
+import { getDefaultBundlerPlugins } from "../bundler-plugin-defaults";
 
 /**
  * Get the list of target platforms for bundling.
@@ -63,36 +25,56 @@ export function getTargetPlatforms(
     return targetPlatforms;
   }
   throw new Error(
-    "No target platforms given. Update the kit configuration to include a target platform, or provide a target platform on the command-line."
+    "No target platforms given. Update the rnx-kit configuration to include a target platform, or provide a target platform on the command-line."
   );
 }
 
+function getDefaultBundleParameters(platform: string) {
+  const extension =
+    platform === "ios" || platform === "macos" ? "jsbundle" : "bundle";
+
+  return {
+    entryFile: "index.js",
+    bundleOutput: `index.${platform}.${extension}`,
+    sourcemapUseAbsolutePath: false,
+  };
+}
+
 /**
- * Get bundle configuration and target platform(s) from kit config. Create
- * one config per platform, applying any platform-specific customizations in
- * the kit config.
+ * Get the bundle configuration and target platform(s) from the rnx-kit
+ * configuration. Use them to create an array of platform-specific
+ * bundle configurations.
+ *
+ * If an id is given, search for the matching bundle definition. Otherwise, use the first bundle definition.
  *
- * @param id Optional bundle definition id. Only needed when the kit config has more than one definition.
+ * @param id Optional identity of the target bundle definition to return
  * @param overridePlatform Override platform, typically from the command-line. When given, this overrides the list of target platforms.
- * @returns Arrary of kit bundle configurations, one per target platform, or `undefined` if bundling is disabled
+ * @returns Arrary of platform-specific bundle configurations
  */
-export function getKitBundleConfigs(
+export function getCliPlatformBundleConfigs(
   id?: string,
   overridePlatform?: AllPlatforms
-): KitBundleConfig[] | undefined {
-  const bundleDefinition = getKitBundleDefinition(id);
-  if (!bundleDefinition) {
-    return undefined;
-  }
+): CliPlatformBundleConfig[] {
+  const kitConfig = getKitConfig();
+  const maybeBundleConfig = kitConfig
+    ? getBundleConfig(kitConfig, id)
+    : undefined;
+  const bundleConfig = maybeBundleConfig ?? {};
 
-  const platforms = getTargetPlatforms(
-    overridePlatform,
-    bundleDefinition.targets
-  );
+  const platforms = getTargetPlatforms(overridePlatform, bundleConfig.targets);
+
+  return platforms.map<CliPlatformBundleConfig>((platform) => {
+    const platformBundleConfig = getPlatformBundleConfig(
+      bundleConfig,
+      platform
+    );
+
+    // apply defaults to fill in any required props that are missing
 
-  return platforms.map<KitBundleConfig>((platform) => {
     return {
-      ...getBundlePlatformDefinition(bundleDefinition, platform),
+      ...getDefaultBundlerPlugins(),
+      ...getDefaultBundleParameters(platform),
+      ...platformBundleConfig,
       platform,
     };
   });

package/src/bundle/metro.ts

@@ -4,81 +4,40 @@ import { createDirectory } from "@rnx-kit/tools-node/fs";
 import type { ConfigT } from "metro-config";
 import path from "path";
 import { customizeMetroConfig } from "../metro-config";
-import type { BundleConfig } from "./types";
-import type { TypeScriptValidationOptions } from "../types";
-
-/**
- * Create Metro bundler arguments from a bundle configuration.
- *
- * @param bundleConfig Bundle configuration
- * @returns Metro bundle arguments
- */
-export function createMetroBundleArgs({
-  entryPath: entryFile,
-  distPath,
-  assetsPath: assetsDest,
-  bundlePrefix,
-  bundleEncoding,
-  sourceMapPath: sourcemapOutput,
-  sourceMapSourceRootPath: sourcemapSourcesRoot,
-  platform,
-  dev,
-  minify,
-}: BundleConfig): MetroBundleArgs {
-  //  assemble the full path to the bundle file
-  const bundleExtension =
-    platform === "ios" || platform === "macos" ? "jsbundle" : "bundle";
-  const bundleFile = `${bundlePrefix}.${platform}.${bundleExtension}`;
-  const bundlePath = path.join(distPath, bundleFile);
-
-  //  always create a source-map in dev mode
-  if (dev) {
-    sourcemapOutput = sourcemapOutput ?? bundleFile + ".map";
-  }
-
-  //  use an absolute path for the source map file
-  if (sourcemapOutput) {
-    sourcemapOutput = path.join(distPath, sourcemapOutput);
-  }
-
-  return {
-    assetsDest,
-    entryFile,
-    minify,
-    platform,
-    dev,
-    bundleOutput: bundlePath,
-    bundleEncoding,
-    sourcemapOutput,
-    sourcemapSourcesRoot,
-  };
-}
+import type { CliPlatformBundleConfig } from "./types";
 
 /**
  * Run the Metro bundler.
  *
- * @param tsservice TypeScript service to use for type-checking (when enabled)
  * @param metroConfig Metro configuration
  * @param bundleConfig Bundle configuration
+ * @param dev Choose whether or not this will be a "developer" bundle. The alternative is a "production" bundle.
+ *            When `true`, warnings are enabled, and the bundle is not minified by default.
+ *            Further, optimizations like constant folding are disabled.
+ *            When `false`, warnings are disabled and the bundle is minified by default.
+ * @param minify Optionally choose whether or not the bundle is minified. When not set, minification is controlled by the `dev` property.
  */
 export async function metroBundle(
   metroConfig: ConfigT,
-  bundleConfig: BundleConfig
+  bundleConfig: CliPlatformBundleConfig,
+  dev: boolean,
+  minify?: boolean
 ): Promise<void> {
   info(`Bundling ${bundleConfig.platform}...`);
 
-  const typescriptValidationOptions: TypeScriptValidationOptions = {
-    throwOnError: true,
-  };
   customizeMetroConfig(
     metroConfig,
     bundleConfig.detectCyclicDependencies,
     bundleConfig.detectDuplicateDependencies,
-    bundleConfig.typescriptValidation ? typescriptValidationOptions : false,
+    bundleConfig.typescriptValidation,
     bundleConfig.treeShake
   );
 
-  const metroBundleArgs = createMetroBundleArgs(bundleConfig);
+  const metroBundleArgs: MetroBundleArgs = {
+    ...bundleConfig,
+    dev,
+    minify,
+  };
 
   // ensure all output directories exist
   createDirectory(path.dirname(metroBundleArgs.bundleOutput));

package/src/bundle/overrides.ts

@@ -1,51 +1,41 @@
+import type { TransformProfile } from "metro-babel-transformer";
 import type { BundleArgs } from "@rnx-kit/metro-service";
 import { pickValues } from "@rnx-kit/tools-language/properties";
-import type { KitBundleConfig } from "./types";
+import type { CliPlatformBundleConfig } from "./types";
 
-export type KitBundleConfigOverrides = {
-  entryPath?: string;
-  distPath?: string;
-  assetsPath?: string;
-  bundlePrefix?: string;
+export type BundleConfigOverrides = {
+  entryFile?: string;
+  bundleOutput?: string;
   bundleEncoding?: BundleArgs["bundleEncoding"];
   sourcemapOutput?: string;
   sourcemapSourcesRoot?: string;
+  sourcemapUseAbsolutePath?: boolean;
+  assetsDest?: string;
   treeShake?: boolean;
+  unstableTransformProfile?: TransformProfile;
 };
 
 /**
- * Apply overrides, if any, to each kit bundle config. Overrides are applied in-place.
+ * Apply overrides, if any, to each rnx-kit bundle configuration. Overrides are applied in-place.
  *
  * @param overrides Optional overrides to apply
- * @param configs Array of kit bundle configurations to override. This is modified if any overrides are applied.
+ * @param configs Array of platform-specific bundle configurations. This is modified if any overrides are applied.
  */
-export function applyKitBundleConfigOverrides(
-  overrides: KitBundleConfigOverrides,
-  configs: KitBundleConfig[]
+export function applyBundleConfigOverrides(
+  overrides: BundleConfigOverrides,
+  configs: CliPlatformBundleConfig[]
 ): void {
-  const overridesToApply = pickValues(
-    overrides,
-    [
-      "entryPath",
-      "distPath",
-      "assetsPath",
-      "bundlePrefix",
-      "bundleEncoding",
-      "sourcemapOutput",
-      "sourcemapSourcesRoot",
-      "treeShake",
-    ],
-    [
-      "entryPath",
-      "distPath",
-      "assetsPath",
-      "bundlePrefix",
-      "bundleEncoding",
-      "sourcemapOutput",
-      "sourcemapSourcesRoot",
-      "treeShake",
-    ]
-  );
+  const overridesToApply = pickValues(overrides, [
+    "entryFile",
+    "bundleOutput",
+    "bundleEncoding",
+    "sourcemapOutput",
+    "sourcemapSourcesRoot",
+    "sourcemapUseAbsolutePath",
+    "assetsDest",
+    "treeShake",
+    "unstableTransformProfile",
+  ]);
   if (overridesToApply) {
     for (const config of configs) {
       Object.assign(config, overridesToApply);

package/src/bundle/types.ts

@@ -1,30 +1,24 @@
-import type {
-  BundleParameters,
-  BundleRequiredParameters,
-} from "@rnx-kit/config";
+import type { TransformProfile } from "metro-babel-transformer";
+import type { BundleParameters } from "@rnx-kit/config";
 import type { AllPlatforms } from "@rnx-kit/tools-react-native/platform";
 
-export type KitBundleConfig = BundleParameters &
-  BundleRequiredParameters & {
+export type CliPlatformBundleConfig = BundleParameters &
+  Required<
+    Pick<
+      BundleParameters,
+      | "entryFile"
+      | "bundleOutput"
+      | "sourcemapUseAbsolutePath"
+      | "detectCyclicDependencies"
+      | "detectDuplicateDependencies"
+      | "typescriptValidation"
+      | "treeShake"
+    >
+  > & {
+    unstableTransformProfile?: TransformProfile;
+
     /**
      * Target platform for the bundle
      */
     platform: AllPlatforms;
   };
-
-export type BundleConfig = KitBundleConfig & {
-  /**
-   * Choose whether or not this will be a "developer" bundle. The alternative is a "production" bundle.
-   *
-   * When `true`, warnings are enabled, and the bundle is not minified by default.
-   * Further, optimizations like constant folding are disabled.
-   *
-   * When `false`, warnings are disabled and the bundle is minified by default.
-   */
-  dev: boolean;
-
-  /**
-   * Optionally choose whether or not the bundle is minified. When not set, minification is controlled by the `dev` property.
-   */
-  minify?: boolean;
-};