Skip to content

Commit c9bb0d9

Browse files
satya164satya164
committed
Add blog post for static API
1 parent e321de1 commit c9bb0d9

File tree

1 file changed

+191
-0
lines changed

1 file changed

+191
-0
lines changed

‎blog/2024-03-25-introducing-static-api.md

+191
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
---
2+
title: Introducing to Static API
3+
author: Satyajit Sahoo
4+
author_url: https://twitter.com/satya164
5+
author_title: Core Team
6+
author_image_url: https://avatars2.githubusercontent.com/u/1174278?s=200&v=4
7+
tags: [announcement]
8+
---
9+
10+
Two of the major pain points of using React Navigation have been TypeScript and deep linking configuration. Due to the dynamic nature of the navigators, it is necessary to manually maintain the TypeScript and deep linking configuration to match the navigation structure. This can be error-prone and time-consuming.
11+
12+
To solve this, we’re adding a new static API to React Navigation 7. It’s not the same API as React Navigation 4, but it’s similar. Many apps don’t need the features that the dynamic API provides, and they can use the simpler static API instead to simplify their codebase.
13+
14+
:::note
15+
16+
The static API it’s an additional optional API. The dynamic API isn’t going away and will remain a first class API of React Navigation. In fact, the static API is written entirely on top of the dynamic API.
17+
18+
:::
19+
20+
## Overview
21+
22+
With the dynamic API, first we import a function such as `createStackNavigator`, then we use it to define screens - each screen has a `name` and a `component`:
23+
24+
```js
25+
const Stack = createStackNavigator();
26+
27+
function RootStack() {
28+
return (
29+
<Stack.Navigator>
30+
<Stack.Screen name="Home" component={Home} />
31+
<Stack.Screen name="Profile" component={Profile} />
32+
<Stack.Screen name="Settings" component={Settings} />
33+
</Stack.Navigator>
34+
);
35+
}
36+
```
37+
38+
The static API follows the same principles. Here we are specifying screens in a property called `screens`, the name of the screen is a key in the configuration object and the value contains the component to render:
39+
40+
```js
41+
const RootStack = {
42+
screens: {
43+
Home: {
44+
screen: Home,
45+
},
46+
Profile: {
47+
screen: Profile,
48+
},
49+
Settings: {
50+
screen: Settings,
51+
},
52+
},
53+
};
54+
```
55+
56+
Then after writing our navigation config, we call `createStaticNavigation` and render the returned the component:
57+
58+
```js
59+
const Navigation = createStaticNavigation(RootStack);
60+
61+
function App() {
62+
return <Navigation />;
63+
}
64+
```
65+
66+
This component is similar to `NavigationContainer` and accepts most of the props accepted by `NavigationContainer`. So this is the place where you can do things like track for screen changes, persist navigation state etc.
67+
68+
See [Static API reference](/docs/7.x/static-configuration?config=static) for more details.
69+
70+
## TypeScript
71+
72+
The typescript types can be inferred from the root navigator with the `StaticParamList` type and then they will be available anywhere you use `useNavigation`.
73+
74+
The only additional code we need to add is the code for the `RootParamList` interface:
75+
76+
```js
77+
declare global {
78+
namespace ReactNavigation {
79+
// highlight-next-line
80+
interface RootParamList extends StaticParamList<typeof RootStack> {}
81+
}
82+
}
83+
```
84+
85+
See [Type checking with TypeScript](/docs/7.x/typescript?config=static) for more details.
86+
87+
## Deep Linking
88+
89+
There are 2 improvements to deep linking API:
90+
91+
1. The linking configuration is now a part of the navigation configuration and can be specified next to the screen. This makes it easier to keep the linking configuration in sync with the navigation structure:
92+
93+
```js
94+
const RootStack = createStackNavigator({
95+
screens: {
96+
Profile: {
97+
screen: Profile,
98+
// highlight-start
99+
linking: {
100+
path: 'user/:id',
101+
},
102+
// highlight-end
103+
},
104+
Settings: {
105+
screen: Settings,
106+
// highlight-start
107+
linking: {
108+
path: 'settings',
109+
},
110+
// highlight-end
111+
},
112+
},
113+
});
114+
```
115+
116+
2. Paths can be generated automatically from the screen names by specifying `enabled: 'auto'`. This avoids the need to specify a path for every screen manually:
117+
118+
```js
119+
const RootStack = createStackNavigator({
120+
screens: {
121+
Home: {
122+
screen: Home, // Generated path: ''
123+
},
124+
Profile: {
125+
screen: Profile, // Generated path: 'profile'
126+
},
127+
NewsFeed: {
128+
screen: Settings, // Generated path: 'news-feed'
129+
},
130+
},
131+
});
132+
133+
const Navigation = createStaticNavigation(RootStack);
134+
135+
function App() {
136+
return (
137+
<Navigation
138+
linking={{
139+
prefix: ['https://mychat.com', 'mychat://'],
140+
// highlight-next-line
141+
enabled: 'auto',
142+
}}
143+
>
144+
<Navigation />
145+
</Navigation>
146+
);
147+
}
148+
```
149+
150+
See [Configuring links](/docs/7.x/configuring-links?config=static) for more details.
151+
152+
## Authentication Flow
153+
154+
One of the nice things about the dynamic APIs is declarative authentication flow. You declaratively define which screens are available for logged in and guest users, and React Navigation would handle showing the appropriate screens automatically. To keep a similar experience, we added some dynamism to the new static API with the if property:
155+
156+
```js
157+
const RootStack = createNativeStackNavigator({
158+
screens: {
159+
Home: {
160+
if: useIsSignedIn,
161+
screen: HomeScreen,
162+
},
163+
SignIn: {
164+
if: useIsSignedOut,
165+
screen: SignInScreen,
166+
},
167+
},
168+
});
169+
```
170+
171+
The if property takes a hook that returns a boolean. When the hook returns true, the screen will be included in the navigation tree, and when it returns false, it won’t be included.
172+
173+
See [Authentication flows](/docs/7.x/auth-flow?config=static) for more details.
174+
175+
## Interoperability
176+
177+
Since we have 2 different APIs in the same library, it's important that they both work together. This way you could start an app with the static API, but if you need flexibility for a specific navigator, you could use the dynamic API for that part. Or you may want to migrate to the static API to reduce the complexity, and with the interoperability, you can do that incrementally.
178+
179+
See [Combining static and dynamic APIs](/docs/7.x/combine-static-with-dynamic) for more details.
180+
181+
## Help us test
182+
183+
The Static API is currently available in React Navigation 7 alpha. You can try it out by installing the `next` tag of the React Navigation packages:
184+
185+
```sh
186+
yarn add @react-navigation/native@next @react-navigation/native-stack@next
187+
```
188+
189+
In addition to the static API, React Navigation 7 also includes a lot of other improvements and new features. Make sure to go through the [upgrade guide](/docs/7.x/upgrading-from-6.x) to see all the changes.
190+
191+
We would love to get feedback from the community on how it works for you and catch any issues before the stable release. If you have any feedback or suggestions, please let us know on our [GitHub Discussions forum](https://github.com/react-navigation/react-navigation/discussions). Or if you find any issues, please report them on our [GitHub issues](https://github.com/react-navigation/react-navigation/issues).

0 commit comments

Comments
 (0)