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'});

Package detail