react-native-platform-override

Tools to manage "platform overrides" for out of tree React Native platforms. Facilities for inventorying changes and integrating new upstream changes are included.

Override Manifests

react-native-platform-override operates on a JSON "override manifest" placed at the root of an npm package. It is expected that these are named overrides.json.

An example override manifest

{
  "includePatterns": [
    "src/**"
  ],
  "excludePatterns": [
    "src/README.md"
  ],
  "baseVersion": "0.0.0-10b4b9505",
  "overrides": [
    {
      "type": "derived",
      "file": ".flowconfig",
      "baseFile": ".flowconfig",
      "baseVersion": "0.0.0-56cf99a96",
      "baseHash": "8eab29258f5ad573e478324f10f850b7ccfb49c7"
    },
  ]
}

| Name | Required | Description | Default | |-------------------|----------|-----------------------------------------------------------------|----------| | includePatterns | Optional | A list of globs of files to enforce are listed in the manifest. | ["**"] | | excludePatterns | Optional | Globs to be excluded from the above list. | [] | | baseVersion | Optional | The default react-native version of an override | | | overrides | Required | List of registered overrides, added by the tooling | |

Override Types

Overrides can be registered as different types, each with differing behavior.

| | | |----------|------------------------------------------------------------------------------------------------------------------| | Platform | Platform-specific logic that doesn't map to an upstream file | | Derived | An override derived from an upstream file. Changes to the original file will be merged into the override. | | Patch | An upstream file with changes made to it. Changes to the original file will be merged into the override. | | Copy | An exact copy of an upstream file or directory. Overrides of this type will remain identical to their originals. |

CLI

react-native-platform-override offers multiple commands to manipulate and verify the override manifest.

validate

Verifies that overrides are recorded and up-to-date.

| Option | Required | Description | Default | |---------------------|----------|----------------------------------------------------|---------------------------------| | --manifest <file> | Optional | Path to an override manifest to validate | Package root above cwd | | --version <v> | Optional | A version of React Native to check against | The currently installed version |

add <override>

Adds an override to the manifest, prompting for details.

| Option | Required | Description | |-------------------|----------|---------------------------| | <override> | Required | The override to add |

remove <override>

Removes an override to the manifest.

| Option | Required | Description | |-------------------|----------|---------------------------| | <override> | Required | The override to remove |

upgrade

Attempts to automatically merge new changes into out-of-date overrides.

| Option | Required | Description | Default | |---------------------|----------|------------------------------------------------------------|---------------------------------| | --manifest <file> | Optional | Path to an override manifest to validate | Package root above cwd | | --version <v> | Optional | A version of React Native to check against | The currently installed version | | --no-conflicts | Optional | Whether to allow upgraded files to contain conlict markers | --conflicts |

diff <override>

Diffs an override against its base file. It it compared to the base file of the override's current version, even if a newer verison of react-native is installed.

| Option | Required | Description | Default | |------------------------|----------|----------------------------------------------------------------------------------------------------------------|---------| | <override> | Required | The override to diff against | |

GitHub Tokens

react-native-platform-override makes requests to GitHub's API. An OAuth token may optionally be provided by using the --githubToken parameter or setting the PLATFORM_OVERRIDE_GITHUB_TOKEN environment variable.

Programmatic Use

react-native-platform-override offers a programmatic API with similar capabilities to the CLI. Take a look here for details.

E.g.

import {validateManifest} from 'react-native-platform-override';

const validationErrors = await validateManifest({manifestPath: 'src/overrides.json'});