Skip to content

Commit 053b3d6

Browse files
satya164satya164
committed
Add list of changes in 7.x
1 parent 5c8065c commit 053b3d6

File tree

1 file changed

+185
-0
lines changed

1 file changed

+185
-0
lines changed

‎versioned_docs/version-7.x/upgrading-from-6.x.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,189 @@ title: Upgrading from 6.x
44
sidebar_label: Upgrading from 6.x
55
---
66

7+
React Navigation 7 focuses on streamlining the API to avoid patterns that can cause bugs. This means deprecating some of the legacy behavior kept for backward compatibility reasons.
8+
9+
This guides lists all the breaking changes and new features in React Navigation 7 that you need to be aware of when upgrading from React Navigation 6.
10+
11+
## Minimum Requirements
12+
13+
TODO
14+
15+
## Breaking changes
16+
17+
### The `navigate` method no longer navigates to screen in a nested child navigator
18+
19+
Due to backward compatibility reasons, React Navigation 5 and 6 support navigating to a screen in a nested child navigator with `navigation.navigate(ScreenName)` syntax. But this is problematic:
20+
21+
- It only works if the navigator is already mounted - making navigation coupled to other logic.
22+
- It doesn't work with the TypeScript types.
23+
24+
Due to these issues, we have a special API to navigate to a nested screen (`navigation.navigate(ParentScreenName, { screen: ScreenName })`).
25+
26+
From these release, this is no longer the default behavior. If you're relying on this behavior in your app, you can pass the `navigationInChildEnabled` prop to `NavigationContainer` to keep the behavior until you are able to migrate:
27+
28+
```js
29+
<NavigationContainer navigationInChildEnabled>
30+
{/* ... */}
31+
</NavigationContainer>
32+
```
33+
34+
The `navigationInChildEnabled` prop will be removed in the next major.
35+
36+
### The `navigate` method no longer goes back, use `popTo` instead
37+
38+
Previously, `navigate` method navigated back if the screen already exists in the stack. We have seen many people get confused by this behavior.
39+
40+
To avoid this confusion, we have removed the going back behavior from `navigate` and added a new method `popTo` to explicitly go back to a specific screen in the stack:
41+
42+
```diff
43+
- navigation.navigate('PreviousScreen', { foo: 42 });
44+
+ navigation.popTo('PreviousScreen', { foo: 42 });
45+
```
46+
47+
The methods now behave as follows:
48+
49+
- `navigate(screenName)` will stay on the current screen if the screen is already focused, otherwise push a new screen to the stack.
50+
- `popTo(screenName)` will go back to the screen if it exists in the stack, otherwise pop the current screen and add this screen to the stack.
51+
52+
To achieve a behavior similar to before with `navigate`, you can use the [`getId`](screen.md#getid) prop in which case it'll go to the screen with the matching ID and push or pop screens accordingly.
53+
54+
To help with the migration, we have added a new method called `navigateDeprecated` which will behave like the old `navigate` method. You can replace your current `navigate` calls with `navigateDeprecated` to gradually migrate to the new behavior:
55+
56+
```diff
57+
- navigation.navigate('SomeScreen');
58+
+ navigation.navigateDeprecated('SomeScreen');
59+
```
60+
61+
The `navigateDeprecated` method will be removed in the next major.
62+
63+
### The `navigate` method no longer accepts a `key` option
64+
65+
Previously, you could specify a route `key` to navigate to, e.g.:
66+
67+
```js
68+
navigation.navigate({ key: 'someuniquekey' })`
69+
```
70+
71+
It's problematic since:
72+
73+
- `key` is an internal implementation detail and created by the library internally - which makes it weird to use.
74+
- None of the other actions support such usage.
75+
- Specifying a `key` is not type-safe, making it easy to cause bugs.
76+
77+
In React Navigation 5, we added the [`getId`](screen.md#getid) prop which can be used for similar use cases - and gives users full control since they provide the ID and it's not autogenerated by the
78+
library.
79+
80+
So the `key` option is now being removed from the `navigate` action.
81+
82+
### The `onReady` callback on `NavigationContainer` now fires only when there are navigators rendered
83+
84+
Previously, the `onReady` prop and `navigationRef.isReady()` worked slightly differently:
85+
86+
- The `onReady` callback fired when `NavigationContainer` finishes mounting and deep links is resolved.
87+
- The `navigationRef.isReady()` method additionally checks if there are any navigators rendered - which may not be true if the user is rendering their navigators conditionally inside a `NavigationContainer`.
88+
89+
This is important to know since if no navigator is rendered, we can't dispatch any navigation actions as there's no navigator to handle them. But the inconsistency between `onReady` and `navigationRef.isReady()` made it easy to cause issues and confusion.
90+
91+
This changes `onReady` to work similar to `navigationRef.isReady()`. The `onReady` callback will now fire only when there are navigators rendered - reflecting the value of `navigationRef.isReady()`.
92+
93+
This change is not breaking for most users, so you may not need to do anything.
94+
95+
### The `independent` prop on `NavigationContainer` is removed in favor of `NavigationIndependentTree` component
96+
97+
The `independent` prop on `NavigationContainer` was added to support rendering navigators in a separate tree from the rest of the app. This is useful for use cases such as miniapps.
98+
99+
However, there are issues with this approach:
100+
101+
- When building a miniapp, the responsibility of adding this prop was on the miniapp developer, which isn't ideal since forgetting it can cause problems.
102+
- A lot of beginners mistakenly added this prop and were confused why navigation wasn't working.
103+
104+
So we've removed this prop instead of a `NavigationIndependentTree` component which you can use to wrap the navigation container:
105+
106+
```diff
107+
-<NavigationContainer independent>
108+
- {/* ... */}
109+
-</NavigationContainer>
110+
+<NavigationIndependentTree>
111+
+ <NavigationContainer>
112+
+ {/* ... */}
113+
+ </NavigationContainer>
114+
+</NavigationIndependentTree>
115+
```
116+
117+
This way, the responsibility no longer lies on the miniapp developer, but on the parent app. It's also harder for beginners to accidentally add this.
118+
119+
### The `Link` component and `useLinkProps` hook now use screen names instead of paths
120+
121+
Previously, the `Link` component and `useLinkProps` hook were designed to work with path strings via the `to` prop. But it had few issues:
122+
123+
- The path strings are not type-safe, making it easy to cause typos and bugs after refactor
124+
- The API made navigating via screen name more inconvenient, even if that's the preferred approach
125+
126+
Now, instead of the `to` prop that took a path string, they now accept `screen` and `params` props, as well as an optional `href` prop to use instead of the generated path:
127+
128+
```diff
129+
-<Link to="/details?foo=42">Go to Details</Link>
130+
+<Link screen="Details" params={{ foo: 42 }}>Go to Details</Link>
131+
```
132+
133+
or
134+
135+
```diff
136+
-const props = useLinkProps({ to: '/details?foo=42' });
137+
+const props = useLinkProps({ screen: 'Details', params: { foo: 42 } });
138+
```
139+
140+
With this change, you'd now have full type-safety when using the `Link` component given that you have [configured the global type](typescript.md#specifying-default-types-for-usenavigation-link-ref-etc).
141+
142+
### The `useLinkTo` and `useLinkBuilder` hooks are merged into `useLinkTools`
143+
144+
Previously, the `useLinkTo` and `useLinkBuilder` hooks could be used to build a path for a screen or action for a path respectively. This was primarily useful for building custom navigators. Now, both of these hooks are merged into a single `useLinkTools` hook:
145+
146+
```js
147+
const { buildHref, buildAction } = useLinkTools();
148+
149+
const href = buildHref('Details', { foo: 42 }); // '/details?foo=42'
150+
const action = buildAction('/details?foo=42'); // { type: 'NAVIGATE', payload: { name: 'Details', params: { foo: 42 } } }
151+
```
152+
153+
Note that this hook is intended to be used by custom navigators and not by end users. For end users, the `Link` component and `useLinkProps` are the recommended way to navigate.
154+
155+
### Material Top Tab Navigator no longers requires installing `react-native-tab-view`
156+
157+
Previously, `@react-navigation/material-top-tabs` required installing `react-native-tab-view` as a dependency in the project. We have now moved this package to the React Navigation monorepo and able to coordinate the releases together, so it's no longer necessary to install it separately.
158+
159+
If you use `@react-navigation/material-top-tabs` and don't use `react-native-tab-view` anywhere else in your project, you can remove it from your dependencies after upgrading.
160+
161+
If you need to enforce a specific version of `react-native-tab-view` for some reason, we recommend using [Yarn resolutions](https://classic.yarnpkg.com/lang/en/docs/selective-version-resolutions/) or [npm overrides](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#overrides) to do so.
162+
163+
### Material Bottom Tab Navigator now lives in `react-native-paper` package
164+
165+
The `@react-navigation/material-bottom-tabs` package provided React Navigation integration for `react-native-paper`'s `BottomNavigation` component. To make it easier to keep it updated with the changes in `react-native-paper`, we have now moved it to the `react-native-paper` package.
166+
167+
If you are using `@react-navigation/material-bottom-tabs` in your project, you can remove it from your dependencies and change the imports to `react-native-paper/react-navigation` instead:
168+
169+
```diff
170+
- import { createMaterialBottomTabNavigator } from '@react-navigation/material-bottom-tabs';
171+
+ import { createMaterialBottomTabNavigator } from 'react-native-paper/react-navigation';
172+
```
173+
174+
### The flipper devtools plugin is now removed
175+
176+
Previously, we added a Flipper plugin for React Navigation to make debugging navigation easier. However, it has added significant maintenance overhead for us. The Flipper team hasn't been focused on React Native recently, so the overall experience of using Flipper with React Native has been poor.
177+
178+
> Currently, the Flipper team has been focused on native developer experience, so we are going back to the drawing board. We have created a new pillar within our team focused on Developer Experience. We are currently investigating improved Chrome Debugger protocol support from the Hermes team as well as migrating the debugging experience from Flipper to Chrome DevTools so we can deliver a debugging experience that meets our standard.
179+
>
180+
> [react-native-community/discussions-and-proposals#546 (comment)](https://github.com/react-native-community/discussions-and-proposals/discussions/546#discussioncomment-4178951)
181+
182+
Since the React Native team migrating away from Flipper, it doesn't make much sense for us to spend additional resources to keep supporting it. So we've removed the Flipper plugin from `@react-navigation/devtools`.
183+
184+
## New features
185+
186+
### Navigators now support a static configuration API
187+
188+
TODO
189+
190+
### The drawer implementation is now available in `react-native-drawer-layout` as a standalone package
191+
7192
TODO

0 commit comments

Comments
 (0)