Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 13 additions & 11 deletions docsite/docs/dependencies.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,11 +55,11 @@ release of React Native:
```typescript
const reactNative: Package = {
name: "react-native",
version: "^0.67.0-0",
version: "^0.68.0",
capabilities: ["react"],
};

const profile_0_67: Profile = {
const profile_0_68: Profile = {
react: {
name: "react",
version: "17.0.2",
Expand Down Expand Up @@ -108,15 +108,17 @@ package require?
{
"rnx-kit": {
"kitType": "app",
"reactNativeVersion": "^0.66 || ^0.67",
"capabilities": [
"core-android",
"core-ios",
"core-macos",
"core-windows",
"react",
"test-app"
]
"alignDeps": {
"requirements": ["react-native@0.68"],
"capabilities": [
"core-android",
"core-ios",
"core-macos",
"core-windows",
"react",
"test-app"
]
}
}
}
```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,33 +5,33 @@ import TabItem from "@theme/TabItem";
<TabItem value="yarn" label="Yarn" default>

```sh
yarn rnx-dep-check --init app
yarn rnx-align-deps --init app
```

```sh
yarn rnx-dep-check --init library
yarn rnx-align-deps --init library
```

</TabItem>
<TabItem value="pnpm" label="pnpm">

```sh
pnpm rnx-dep-check --init app
pnpm rnx-align-deps --init app
```

```sh
pnpm rnx-dep-check --init library
pnpm rnx-align-deps --init library
```

</TabItem>
<TabItem value="npm" label="npm">

```sh
npx rnx-dep-check --init app
npx rnx-align-deps --init app
```

```sh
npx rnx-dep-check --init library
npx rnx-align-deps --init library
```

</TabItem>
Expand Down
137 changes: 78 additions & 59 deletions docsite/docs/guides/dependency-management.mdx
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import DepCheckInit from "./_dep-check-init.mdx";
import AlignDepsInit from "./_align-deps-init.mdx";
import PackageCommand from "./_package-command.mdx";
import PackageRunCommand from "./_package-run-command.mdx";
import AmplifyCallout from "../_amplify-callout.mdx";
Expand All @@ -25,26 +25,26 @@ done all at once, or gradually over multiple PRs.
First, add the dependency manager to your package.

<PackageCommand
yarnArgs="add @rnx-kit/dep-check --dev"
pnpmArgs="add -D @rnx-kit/dep-check"
npmArgs="add --save-dev @rnx-kit/dep-check"
yarnArgs="add @rnx-kit/align-deps --dev"
pnpmArgs="add -D @rnx-kit/align-deps"
npmArgs="add --save-dev @rnx-kit/align-deps"
/>

Add new script commands for convenience. We'll use these later.

```json title="package.json"
{
"scripts": {
"check-dependencies": "rnx-dep-check",
"fix-dependencies": "rnx-dep-check --write"
"check-dependencies": "rnx-align-deps",
"fix-dependencies": "rnx-align-deps --write"
}
}
```

Next, generate the dependency manager configuration for your package. If your
package produces a bundle, it's an `app`. Otherwise, it's a `library`.

<DepCheckInit />
<AlignDepsInit />

Fix any React Native package versions that might have compatibility issues.

Expand Down Expand Up @@ -99,17 +99,17 @@ every package in your repo.
Add the dependency manager to your repo's root package.json.

<PackageCommand
yarnArgs="add @rnx-kit/dep-check --dev -W"
pnpmArgs="add -D @rnx-kit/dep-check"
npmArgs="add --save-dev @rnx-kit/dep-check"
yarnArgs="add @rnx-kit/align-deps --dev -W"
pnpmArgs="add -D @rnx-kit/align-deps"
npmArgs="add --save-dev @rnx-kit/align-deps"
/>

Next, add this command to your PR loop. It runs the dependency manager from the
root of the repo, scanning all packages. This include packages which haven't
onboarded yet. For those, `--vigilant [version]` controls the target React
Native release to use when checking compatibility.
onboarded yet. For those, `--requirements react-native@[version]` controls the
target React Native release to use when checking compatibility.

<PackageRunCommand args="rnx-dep-check --vigilant 0.66" />
<PackageRunCommand args="rnx-align-deps --requirements react-native@0.66" />

When a compatibility problem is found, the command fails with a non-zero exit
code, which causes the PR loop to fail. This protects the repo from risky
Expand All @@ -119,7 +119,7 @@ In the PR logs, you'll see a detailed report, in `diff` format, explaining what
went wrong.

```diff
error Found 3 violation(s) in @rnts/app:
error Found 3 violation(s) in 'packages/app/package.json':
react-native "^0.66.0" -> "^0.66.0-0" (dependencies)
react-native-macos "^0.66.0" -> "^0.66.0-0" (dependencies)
react-native-windows "^0.66.0" -> "^0.66.0-0" (dependencies)
Expand All @@ -141,7 +141,7 @@ error Found 3 violation(s) in @rnts/app:
"devDependencies": {
"@microsoft/api-extractor": "^7.19.4",
"@office-iss/react-native-win32": "^0.66.0",
"@rnx-kit/dep-check": "^1.12.9",
"@rnx-kit/align-deps": "^2.0.0",
"@types/react-native": "^0.66.0",
- "rimraf": "^3.0.2",
"react": "17.0.2",
Expand All @@ -155,17 +155,20 @@ error Found 3 violation(s) in @rnts/app:
"typescript": "^4.5.5"
},
"rnx-kit": {
"reactNativeVersion": "^0.66",
"reactNativeDevVersion": "^0.66.0",
"kitType": "library",
"capabilities": [
"core",
"core-android",
"core-ios",
"core-macos",
"core-windows",
"react"
]
"alignDeps": {
"requirements": {
"development": ["react-native@0.66"],
"production": ["react-native@0.66"]
},
"capabilities": [
"core-android",
"core-ios",
"core-macos",
"core-windows",
"react"
]
}
+ },
+ "peerDependencies": {
+ "react": "17.0.2",
Expand All @@ -174,23 +177,23 @@ error Found 3 violation(s) in @rnts/app:
+ "react-native-windows": "^0.66.0-0"
}
}
error Changes are needed to satisfy all requirements. Re-run with `--write` to have dep-check apply them.
info Visit https://aka.ms/dep-check for more information about dep-check.
error 'packages/button/package.json': Changes are needed to satisfy all requirements. Re-run with `--write` to apply them.
info Visit https://aka.ms/align-deps information about align-deps.
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
```

Fixing problems is automated, too! From your development terminal, run the same
command with a `--write` parameter.

<PackageRunCommand args="rnx-dep-check --vigilant 0.66 --write" />
<PackageRunCommand args="rnx-align-deps --requirements react-native@0.66 --write" />

**Review** and **test** the fixes before pushing them to your PR.

### Dependency Manager Updates

The dependency manager comes with a
[built-in list](https://github.com/microsoft/rnx-kit/tree/main/packages/dep-check#capabilities)
[built-in list](https://github.com/microsoft/rnx-kit/tree/main/packages/align-deps#capabilities)
of known/good React Native package versions and releases. Keeping the dependency
manager up-to-date gives you the latest compatibility data.

Expand All @@ -206,7 +209,7 @@ response.
Run this command from the root of your repo. It uses the dependency manager to
make the fixes automatically.

<PackageRunCommand args="rnx-dep-check --write" />
<PackageRunCommand args="rnx-align-deps --write" />

**Review** and **test** the fixes before pushing them to the PR with the
dependency manager update.
Expand All @@ -217,24 +220,24 @@ When you're ready to upgrade to a new release of React Native (or downgrade to
an old release), you can use the dependency manager to help you out.

First, update your PR loop definition. Find the
`rnx-dep-check --vigilant [version]` command and change the target React Native
version.
`rnx-align-deps --requirements react-native@[version]` command and change the
target React Native version.

Then, run these commands from the root of your repo to change your React Native
version and adjust all React Native dependencies to be compatible. Replace
`[version]` with your target React Native version in `major.minor` format, such
as "0.66" or "0.68".

<PackageRunCommand args="rnx-dep-check --set-version [version]" />
<PackageRunCommand args="rnx-align-deps --set-version [version]" />

<PackageRunCommand args="rnx-dep-check --vigilant [version] --write" />
<PackageRunCommand args="rnx-align-deps --requirements react-native@[version] --write" />

**Review** and **test** your packages thoroughly before merging these changes.

## Customization

Did you know that you can add your own packages to the dependency manager's
[built-in list](https://github.com/microsoft/rnx-kit/tree/main/packages/dep-check#capabilities)?
[built-in list](https://github.com/microsoft/rnx-kit/tree/main/packages/align-deps#capabilities)?

If your repo uses React Native packages that aren't known to the dependency
manager, add them to the list! Or if you want to align other dependencies
Expand All @@ -246,16 +249,16 @@ module, a `.json` file, or a module name.

```json title="dependency-profile.json"
{
"@types/node": {
"name": "@types/node",
"version": "^16.0.0",
"devOnly": true
},
"chalk": {
"name": "chalk",
"version": "^4.1.0"
},
"0.63": {
"0.66": {
"@types/node": {
"name": "@types/node",
"version": "^16.0.0",
"devOnly": true
},
"chalk": {
"name": "chalk",
"version": "^4.1.0"
},
"native-base": {
"name": "native-base",
"version": "^3.3.11",
Expand All @@ -267,35 +270,51 @@ module, a `.json` file, or a module name.

:::note

Look at `native-base` in the example above. It's wrapped in a `0.63` version
tag. That means it only applies to React Native 0.63 and above.
Look at `native-base` in the example above. It's wrapped in a `0.66` version
tag. That means it only applies to React Native 0.66.

:::

Next, configure each of your onboarded React Native packages to use the list.

```json title="package.json"
{
"rnx-kit": {
"customProfiles": "path/to/dependency-profile.json"
}
}
```diff title="package.json"
{
"rnx-kit": {
"alignDeps": {
+ "presets": [
+ "microsoft/react-native",
+ "path/to/dependency-profile.json"
+ ],
"requirements": {
"development": ["react-native@0.66"],
"production": ["react-native@0.66"]
},
"capabilities": [
"core-android",
"core-ios",
"core-macos",
"core-windows",
"react"
]
}
}
}
```

Now its time to use the list. Run the dependency manager to update all of your
Now it's time to use the list. Run the dependency manager to update all of your
packages.

<PackageRunCommand args="rnx-dep-check --vigilant 0.66 --customProfiles path/to/dependency-profile.json --write" />
<PackageRunCommand args="rnx-align-deps --requirements react-native@0.66 --presets microsoft/react-native,path/to/dependency-profile.json --write" />

**Review** and **test** the changes before continuing.

The last step is updating the automation. Each command needs an extra
`--customProfiles [path]` parameter.
`--presets [paths]` parameter.

- Pull Requests: Change the `rnx-dep-check --vigilant [version]` command
- Dependency Manager Updates: Change the `rnx-dep-check --write` command
- Pull Requests: Change the `rnx-align-deps --requirements react-native@[version]` command
- Dependency Manager Updates: Change the `rnx-align-deps --write` command
- Upgrading React Native: Change the
`rnx-dep-check --vigilant [version] --write` command
`rnx-align-deps --requirements react-native@[version] --write` command

## Finish Line

Expand Down
12 changes: 6 additions & 6 deletions docsite/docs/guides/getting-started.mdx
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import DepCheckInit from "./_dep-check-init.mdx";
import AlignDepsInit from "./_align-deps-init.mdx";
import PackageCommand from "./_package-command.mdx";
import PackageRunCommand from "./_package-run-command.mdx";

Expand All @@ -21,19 +21,19 @@ If you want to learn more about this project before jumping in, head to the
Start by adding the dependency manager to your package.

<PackageCommand
yarnArgs="add @rnx-kit/dep-check --dev"
pnpmArgs="add -D @rnx-kit/dep-check"
npmArgs="add --save-dev @rnx-kit/dep-check"
yarnArgs="add @rnx-kit/align-deps --dev"
pnpmArgs="add -D @rnx-kit/align-deps"
npmArgs="add --save-dev @rnx-kit/align-deps"
/>

Next, generate the dependency manager configuration for your package. If your
package produces a bundle, it's an `app`. Otherwise, it's a `library`.

<DepCheckInit />
<AlignDepsInit />

Fix any React Native package versions that might have compatibility issues.

<PackageRunCommand args="rnx-dep-check --write" />
<PackageRunCommand args="rnx-align-deps --write" />

Review the changes. They should be limited to package.json and your Yarn / npm /
pnpm lock file.
Expand Down
Loading