@rnx-kit/dep-check v1.14.0

@rnx-kit/dep-check has been renamed to @rnx-kit/align-deps

For more details, read the RFC: https://github.com/microsoft/rnx-kit/pull/1757

@rnx-kit/dep-check

@rnx-kit/dep-check manages React Native dependencies for a package, based on its needs and requirements.

If you want to learn how dep-check is used at Microsoft, and see a demo of how it works in a monorepo - you can watch the "Improve all the repos – exploring Microsoft’s DevExp" talk by @kelset and @tido64 from React Native Europe 2021.

Installation

yarn add @rnx-kit/dep-check --dev

or if you're using npm

npm add --save-dev @rnx-kit/dep-check

Usage

yarn rnx-dep-check [options] [packages...]

Listing paths to packages that should be checked is optional. If omitted, dep-check will look for the closest package.json using Node module resolution. If the target package is a root package defining workspaces, they will all be included.

Examples:

• Ensure dependencies are compatible with react-native 0.64 without a config:

  yarn rnx-dep-check --vigilant 0.64

• Initialize a config for your app (or library):

  yarn rnx-dep-check --init app
  # or specify `library` for a library

• Apply changes suggested by dep-check:

  yarn rnx-dep-check --write

• Interactively update supported react-native versions (or bump version used for development):

  yarn rnx-dep-check --set-version

--custom-profiles <module>

Path to custom profiles. This can be a path to a JSON file, a .js file, or a module name. The module must default export an object similar to the one below:

module.exports = {
  0.63: {
    "my-capability": {
      name: "my-module",
      version: "1.0.0",
    },
  },
  0.64: {
    "my-capability": {
      name: "my-module",
      version: "1.1.0",
    },
  },
};

For a more complete example, have a look at the default profiles.

Note

This specific flag may only be used with --vigilant. You can specify custom profiles in normal mode by adding customProfiles to your package configuration.

--exclude-packages

Comma-separated list of package names to exclude from inspection.

Note

--exclude-packages will only exclude packages that do not have a configuration. Packages that have a configuration, will still be checked. This flag may only be used with --vigilant.

--init <app | library>

When integrating @rnx-kit/dep-check for the first time, it may be a cumbersome to manually add all capabilities yourself. You can run this tool with --init, and it will try to add a sensible configuration based on what is currently defined in the specified package.json.

--set-version

Sets reactNativeVersion and reactNativeDevVersion for any configured package. The value should be a comma-separated list of react-native versions to set. The first number specifies the development version. For example, 0.64,0.63 will set the following values:

{
  "rnx-kit": {
    "reactNativeVersion": "^0.63.0 || ^0.64.0",
    "reactNativeDevVersion": "^0.64.0"
  }
}

If the version numbers are omitted, an interactive prompt will appear.

Note

A rnx-dep-check --write run will be invoked right after changes have been made. As such, this flag will fail if changes are needed before making any modifications.

--vigilant

Also inspect packages that are not configured. Specify a comma-separated list of profile versions to compare against, e.g. 0.63,0.64. The first number specifies the target version.

--write

Writes all proposed changes to the specified package.json.

Configure

@rnx-kit/dep-check must first be configured before it can be used. It uses @rnx-kit/config to retrieve your kit configuration. Your configuration can be specified either in a file, rnx-kit.config.js, or in an "rnx-kit" section of your package.json.

Capabilities

The following table contains the currently supported capabilities and what they resolve to:

To add new capabilities, first add it to /packages/config/src/kitConfig.ts, then update the profiles. For an example, have a look at how the hermes capability was added.

If you're looking to update capabilities to a more recent version, run yarn update-profile to help determine whether we need to bump any packages.

Custom Profiles

A custom profile is a list of capabilities that map to specific versions of packages. It can be a JSON file, or a JS file that default exports it. Custom profiles are consumed via the --custom-profiles flag.

For example, this custom profile adds my-capability to profile versions 0.63 and 0.64:

module.exports = {
  0.63: {
    "my-capability": {
      name: "my-module",
      version: "1.0.0",
    },
  },
  0.64: {
    "my-capability": {
      name: "my-module",
      version: "1.1.0",
    },
  },
};

If you have capabilities that should be the same across all versions, you can declare them at the root level like below:

module.exports = {
  "my-capability": {
    name: "my-module",
    version: "1.0.0",
  },
  0.64: {
    // This entry will override the common version
    "my-capability": {
      name: "my-module",
      version: "1.1.0",
    },
  },
};

For a more complete example, have a look at the default profiles.

Custom Capabilities

Normally, a capability resolves to a version of a package. For instance, core is a capability that resolves to react-native:

{
  "core": {
    name: "react-native",
    version: "0.0.0",
  },
}

A capability can depend on other capabilities. For example, we can ensure that react-native gets installed along with react-native-windows by declaring that core-windows depends on core:

{
  "core-windows": {
    name: "react-native-windows",
    version: "0.0.0",
    capabilities: ["core"],
  },
}

You can also create capabilities that don't resolve to a package, but to a list of capabilities instead:

{
  "core/all": {
    name: "#meta",
    capabilities: [
      "core-android",
      "core-ios",
      "core-macos",
      "core-windows",
    ],
  },
}

We call these meta capabilities. To make it easier to identify them (both for humans and machines), the name field must be set to #meta, and the capabilities field must be a non-empty array of other capabilities. The version field is no longer used and can be dropped. To use a meta capability in your rnx-kit configuration, there's nothing specific to be done — for instance:

 {
   "name": "my-package",
   ...
   "rnx-kit": {
     "reactNativeVersion": "0.64",
     "capabilities": [
+      "core/all"
     ],
     "customProfiles": "my-custom-profiles"
   }
 }

Terminology

Contribution

Updating an Existing Profile

Updating an existing profile is unfortunately a manual process.

We have a script that fetches the latest version of all capabilities and presents them in a table together with the current versions.

yarn update-profile

Outputs something like:

| Capability   | Name          | Version   | Latest | Homepage                                        |
| ------------ | ------------- | --------- | ------ | ----------------------------------------------- |
| core         | react-native  | ^0.68.0-0 | 0.68.2 | https://github.com/facebook/react-native#readme |
| core-android | react-native  | ^0.68.0-0 | 0.68.2 | https://github.com/facebook/react-native#readme |
| core-ios     | react-native  | ^0.68.0-0 | 0.68.2 | https://github.com/facebook/react-native#readme |
| hermes       | hermes-engine | ~0.11.0   | =      |                                                 |
| react        | react         | 17.0.2    | 18.1.0 | https://reactjs.org/                            |
| ...                                                                                                 |

With this information, we can see which packages have been updated since the last profile, and scan their change logs for interesting changes that may affect compatibility.

Adding a Profile for a New Version of react-native

The update-profile script can also be used to add a profile. For instance, to add a profile for react-native 0.69, run:

yarn update-profile 0.69

The script will try to figure out what version of react, metro, etc. should be set to, and write to src/profiles/profile-0.69.ts. Please verify that this profile looks correct before checking it in.