agentic-mobile-kit 0.0.2 → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +20 -8
- package/bin/cli.js +31 -5
- package/lib/init.js +199 -0
- package/package.json +9 -3
- package/stacks/react-native/template/.agents/skills/LICENSE-callstack +21 -0
- package/stacks/react-native/template/.agents/skills/THIRD_PARTY.md +9 -0
- package/stacks/react-native/template/.agents/skills/m-bugfix/SKILL.md +23 -0
- package/stacks/react-native/template/.agents/skills/m-bugfix/agents/openai.yaml +3 -0
- package/stacks/react-native/template/.agents/skills/m-continue/SKILL.md +22 -0
- package/stacks/react-native/template/.agents/skills/m-continue/agents/openai.yaml +3 -0
- package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +50 -0
- package/stacks/react-native/template/.agents/skills/m-feature/agents/openai.yaml +3 -0
- package/stacks/react-native/template/.agents/skills/m-pause/SKILL.md +14 -0
- package/stacks/react-native/template/.agents/skills/m-pause/agents/openai.yaml +3 -0
- package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +29 -0
- package/stacks/react-native/template/.agents/skills/m-review/agents/openai.yaml +3 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/POWER.md +172 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/SKILL.md +238 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/agents/openai.yaml +4 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-analyze-app.md +208 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-analyze-js.md +264 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-barrel-exports.md +250 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-code-splitting.md +255 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-hermes-mmap.md +167 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-library-size.md +164 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-native-assets.md +208 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-r8-android.md +231 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/bundle-tree-shaking.md +215 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-animations-reanimated.md +273 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-atomic-state.md +190 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-bottomsheet.md +339 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-concurrent-react.md +238 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-lists-flatlist-flashlist.md +223 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-measure-fps.md +178 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-memory-leaks.md +168 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-profile-react.md +138 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-react-compiler.md +261 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/js-uncontrolled-components.md +219 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-android-16kb-alignment.md +114 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-measure-tti.md +221 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-memory-leaks.md +206 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-memory-patterns.md +240 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-platform-setup.md +112 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-profiling.md +140 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-sdks-over-polyfills.md +192 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-threading-model.md +230 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-turbo-modules.md +210 -0
- package/stacks/react-native/template/.agents/skills/react-native-best-practices/references/native-view-flattening.md +180 -0
- package/stacks/react-native/template/.agents/skills/react-navigation/SKILL.md +63 -0
- package/stacks/react-native/template/.agents/skills/react-navigation/agents/openai.yaml +4 -0
- package/stacks/react-native/template/.agents/skills/react-navigation/references/bottom-tabs.md +496 -0
- package/stacks/react-native/template/.agents/skills/react-navigation/references/drawers.md +474 -0
- package/stacks/react-native/template/.agents/skills/react-navigation/references/form-sheet.md +305 -0
- package/stacks/react-native/template/.agents/skills/react-navigation/references/header.md +270 -0
- package/stacks/react-native/template/.agents/skills/react-navigation/references/material-top-tabs.md +453 -0
- package/stacks/react-native/template/.agents/skills/react-navigation/references/native-bottom-tabs.md +365 -0
- package/stacks/react-native/template/.agents/skills/react-navigation/references/safe-areas.md +95 -0
- package/stacks/react-native/template/.agents/skills/react-navigation/references/stacks.md +392 -0
- package/stacks/react-native/template/.agents/skills/upgrading-react-native/SKILL.md +79 -0
- package/stacks/react-native/template/.agents/skills/upgrading-react-native/agents/openai.yaml +4 -0
- package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/expo-sdk-upgrade.md +65 -0
- package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/monorepo-singlerepo-targeting.md +34 -0
- package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/react.md +42 -0
- package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/upgrade-helper-core.md +122 -0
- package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/upgrade-verification.md +53 -0
- package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/upgrading-dependencies.md +41 -0
- package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/upgrading-react-native.md +52 -0
- package/stacks/react-native/template/.githooks/pre-commit +49 -0
- package/stacks/react-native/template/.githooks/pre-push +5 -0
- package/stacks/react-native/template/.github/pull_request_template.md +19 -0
- package/stacks/react-native/template/.github/workflows/ci.yml +61 -0
- package/stacks/react-native/template/.github/workflows/ios.yml +43 -0
- package/stacks/react-native/template/.gitleaks.toml +12 -0
- package/stacks/react-native/template/.rulesync/hooks.jsonc +8 -0
- package/stacks/react-native/template/.rulesync/permissions.jsonc +36 -0
- package/stacks/react-native/template/.rulesync/subagents/m-reviewer.md +15 -0
- package/stacks/react-native/template/AGENTS.md +45 -0
- package/stacks/react-native/template/CLAUDE.md +1 -0
- package/stacks/react-native/template/docs/ai/conventions.md +8 -0
- package/stacks/react-native/template/docs/ai/decisions.md +6 -0
- package/stacks/react-native/template/docs/ai/known-issues.md +17 -0
- package/stacks/react-native/template/docs/ai/product.md +7 -0
- package/stacks/react-native/template/docs/ai/react-native.md +27 -0
- package/stacks/react-native/template/docs/ai/structure.md +7 -0
- package/stacks/react-native/template/docs/ai/team-process.md +9 -0
- package/stacks/react-native/template/docs/ai/tech.md +7 -0
- package/stacks/react-native/template/rulesync.jsonc +9 -0
- package/stacks/react-native/template/scripts/ai/guard.js +35 -0
- package/stacks/react-native/template/scripts/ai/handoff-check.js +28 -0
- package/stacks/react-native/template/scripts/ai/install-deps.sh +14 -0
- package/stacks/react-native/template/scripts/ai/ios-build.sh +11 -0
- package/stacks/react-native/template/scripts/ai/pm-run.sh +16 -0
- package/stacks/react-native/template/specs/_templates/design.md +15 -0
- package/stacks/react-native/template/specs/_templates/progress.md +14 -0
- package/stacks/react-native/template/specs/_templates/requirements.md +30 -0
- package/stacks/react-native/template/specs/_templates/tasks.md +6 -0
|
@@ -0,0 +1,392 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Native Stack Navigator
|
|
3
|
+
impact: HIGH
|
|
4
|
+
tags: react-navigation, native-stack, navigation, header, header-items, search-bar, large-title, modal, animation, form-sheet
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Skill: Native Stack Navigator
|
|
8
|
+
|
|
9
|
+
## Description
|
|
10
|
+
|
|
11
|
+
Use `createNativeStackNavigator` for screen-to-screen flows.
|
|
12
|
+
|
|
13
|
+
## When to Use
|
|
14
|
+
|
|
15
|
+
- Building the default push-based flow for an app
|
|
16
|
+
- Using platform-native headers, large titles, or a native search bar
|
|
17
|
+
- Presenting modal or sheet screens with native-stack presentations
|
|
18
|
+
|
|
19
|
+
## Basic Example
|
|
20
|
+
|
|
21
|
+
**Static API**
|
|
22
|
+
|
|
23
|
+
```tsx
|
|
24
|
+
import { createNativeStackNavigator } from '@react-navigation/native-stack';
|
|
25
|
+
|
|
26
|
+
const AppStack = createNativeStackNavigator({
|
|
27
|
+
screens: {
|
|
28
|
+
Home: HomeScreen,
|
|
29
|
+
Profile: ProfileScreen,
|
|
30
|
+
},
|
|
31
|
+
});
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
**Dynamic API**
|
|
35
|
+
|
|
36
|
+
```tsx
|
|
37
|
+
import { createNativeStackNavigator } from '@react-navigation/native-stack';
|
|
38
|
+
|
|
39
|
+
const Stack = createNativeStackNavigator();
|
|
40
|
+
|
|
41
|
+
function AppStack() {
|
|
42
|
+
return (
|
|
43
|
+
<Stack.Navigator>
|
|
44
|
+
<Stack.Screen name="Home" component={HomeScreen} />
|
|
45
|
+
<Stack.Screen name="Profile" component={ProfileScreen} />
|
|
46
|
+
</Stack.Navigator>
|
|
47
|
+
);
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Common Features
|
|
52
|
+
|
|
53
|
+
### Large Title
|
|
54
|
+
|
|
55
|
+
Use `headerLargeTitleEnabled: true` for an iOS large title that collapses into the regular header on scroll.
|
|
56
|
+
|
|
57
|
+
**Static API**
|
|
58
|
+
|
|
59
|
+
```tsx
|
|
60
|
+
const AppStack = createNativeStackNavigator({
|
|
61
|
+
screens: {
|
|
62
|
+
Library: {
|
|
63
|
+
screen: LibraryScreen,
|
|
64
|
+
options: {
|
|
65
|
+
headerLargeTitleEnabled: true,
|
|
66
|
+
},
|
|
67
|
+
},
|
|
68
|
+
},
|
|
69
|
+
});
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
**Dynamic API**
|
|
73
|
+
|
|
74
|
+
```tsx
|
|
75
|
+
import { createNativeStackNavigator } from '@react-navigation/native-stack';
|
|
76
|
+
|
|
77
|
+
const Stack = createNativeStackNavigator();
|
|
78
|
+
|
|
79
|
+
function AppStack() {
|
|
80
|
+
return (
|
|
81
|
+
<Stack.Navigator>
|
|
82
|
+
<Stack.Screen
|
|
83
|
+
name="Library"
|
|
84
|
+
component={LibraryScreen}
|
|
85
|
+
options={{
|
|
86
|
+
headerLargeTitleEnabled: true,
|
|
87
|
+
}}
|
|
88
|
+
/>
|
|
89
|
+
</Stack.Navigator>
|
|
90
|
+
);
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
- Only supported on iOS.
|
|
95
|
+
- The scroll view in the screen must use `contentInsetAdjustmentBehavior="automatic"`.
|
|
96
|
+
- Don't set a background color on the header if large title is enabled as it makes title invisible on iOS 26.
|
|
97
|
+
- Don't set `headerTransparent: false` if large title is enabled.
|
|
98
|
+
- If the scrollable area does not fill the screen, the large title will not collapse on scroll.
|
|
99
|
+
|
|
100
|
+
### Header Search Bar
|
|
101
|
+
|
|
102
|
+
Use `headerSearchBarOptions` to render a native search bar. If the search configuration depends on screen state, update it with `navigation.setOptions(...)`.
|
|
103
|
+
|
|
104
|
+
**Static API**
|
|
105
|
+
|
|
106
|
+
```tsx
|
|
107
|
+
const AppStack = createNativeStackNavigator({
|
|
108
|
+
screens: {
|
|
109
|
+
Search: {
|
|
110
|
+
screen: SearchScreen,
|
|
111
|
+
options: {
|
|
112
|
+
headerSearchBarOptions: {
|
|
113
|
+
placeholder: 'Search',
|
|
114
|
+
},
|
|
115
|
+
},
|
|
116
|
+
},
|
|
117
|
+
},
|
|
118
|
+
});
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
**Dynamic API**
|
|
122
|
+
|
|
123
|
+
```tsx
|
|
124
|
+
import { createNativeStackNavigator } from '@react-navigation/native-stack';
|
|
125
|
+
|
|
126
|
+
const Stack = createNativeStackNavigator();
|
|
127
|
+
|
|
128
|
+
function AppStack() {
|
|
129
|
+
return (
|
|
130
|
+
<Stack.Navigator>
|
|
131
|
+
<Stack.Screen
|
|
132
|
+
name="Search"
|
|
133
|
+
component={SearchScreen}
|
|
134
|
+
options={{
|
|
135
|
+
headerSearchBarOptions: {
|
|
136
|
+
placeholder: 'Search',
|
|
137
|
+
},
|
|
138
|
+
}}
|
|
139
|
+
/>
|
|
140
|
+
</Stack.Navigator>
|
|
141
|
+
);
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
- The scroll view in the screen must use `contentInsetAdjustmentBehavior="automatic"`.
|
|
146
|
+
- If the screen doesn't have a scroll view, use `headerTopInsetEnabled: true`.
|
|
147
|
+
|
|
148
|
+
### Header Buttons and Custom Content
|
|
149
|
+
|
|
150
|
+
Use `unstable_headerLeftItems` and `unstable_headerRightItems` for native iOS header buttons or menus. Use `headerLeft`, `headerRight`, `headerTitle`, and `headerBackground` for custom React content, and as a fallback on other platforms.
|
|
151
|
+
|
|
152
|
+
**Static API**
|
|
153
|
+
|
|
154
|
+
```tsx
|
|
155
|
+
import { Button, Text, View } from 'react-native';
|
|
156
|
+
import { createNativeStackNavigator } from '@react-navigation/native-stack';
|
|
157
|
+
|
|
158
|
+
const AppStack = createNativeStackNavigator({
|
|
159
|
+
screens: {
|
|
160
|
+
Profile: {
|
|
161
|
+
screen: ProfileScreen,
|
|
162
|
+
options: {
|
|
163
|
+
headerTitle: ({ tintColor, children }) => (
|
|
164
|
+
<Text style={{ color: tintColor, fontSize: 18 }}>{children}</Text>
|
|
165
|
+
),
|
|
166
|
+
headerBackground: () => (
|
|
167
|
+
<View style={{ flex: 1, backgroundColor: '#fff' }} />
|
|
168
|
+
),
|
|
169
|
+
unstable_headerLeftItems: () => [
|
|
170
|
+
{
|
|
171
|
+
type: 'button',
|
|
172
|
+
label: 'Edit',
|
|
173
|
+
onPress: () => {
|
|
174
|
+
// Do something
|
|
175
|
+
},
|
|
176
|
+
},
|
|
177
|
+
],
|
|
178
|
+
unstable_headerRightItems: () => [
|
|
179
|
+
{
|
|
180
|
+
type: 'button',
|
|
181
|
+
label: 'Done',
|
|
182
|
+
icon: {
|
|
183
|
+
type: 'sfSymbol',
|
|
184
|
+
name: 'checkmark',
|
|
185
|
+
},
|
|
186
|
+
onPress: () => {
|
|
187
|
+
// Do something
|
|
188
|
+
},
|
|
189
|
+
},
|
|
190
|
+
],
|
|
191
|
+
headerLeft: ({ tintColor }) => (
|
|
192
|
+
<Button title="Edit" color={tintColor} onPress={() => {}} />
|
|
193
|
+
),
|
|
194
|
+
headerRight: ({ tintColor }) => (
|
|
195
|
+
<Button title="Done" color={tintColor} onPress={() => {}} />
|
|
196
|
+
),
|
|
197
|
+
},
|
|
198
|
+
},
|
|
199
|
+
},
|
|
200
|
+
});
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
**Dynamic API**
|
|
204
|
+
|
|
205
|
+
```tsx
|
|
206
|
+
import { Button, Text, View } from 'react-native';
|
|
207
|
+
import { createNativeStackNavigator } from '@react-navigation/native-stack';
|
|
208
|
+
|
|
209
|
+
const Stack = createNativeStackNavigator();
|
|
210
|
+
|
|
211
|
+
function AppStack() {
|
|
212
|
+
return (
|
|
213
|
+
<Stack.Navigator>
|
|
214
|
+
<Stack.Screen
|
|
215
|
+
name="Profile"
|
|
216
|
+
component={ProfileScreen}
|
|
217
|
+
options={{
|
|
218
|
+
headerTitle: ({ tintColor, children }) => (
|
|
219
|
+
<Text style={{ color: tintColor, fontSize: 18 }}>{children}</Text>
|
|
220
|
+
),
|
|
221
|
+
headerBackground: () => (
|
|
222
|
+
<View style={{ flex: 1, backgroundColor: '#fff' }} />
|
|
223
|
+
),
|
|
224
|
+
unstable_headerLeftItems: () => [
|
|
225
|
+
{
|
|
226
|
+
type: 'button',
|
|
227
|
+
label: 'Edit',
|
|
228
|
+
onPress: () => {
|
|
229
|
+
// Do something
|
|
230
|
+
},
|
|
231
|
+
},
|
|
232
|
+
],
|
|
233
|
+
unstable_headerRightItems: () => [
|
|
234
|
+
{
|
|
235
|
+
type: 'button',
|
|
236
|
+
label: 'Done',
|
|
237
|
+
icon: {
|
|
238
|
+
type: 'sfSymbol',
|
|
239
|
+
name: 'checkmark',
|
|
240
|
+
},
|
|
241
|
+
onPress: () => {
|
|
242
|
+
// Do something
|
|
243
|
+
},
|
|
244
|
+
},
|
|
245
|
+
],
|
|
246
|
+
headerLeft: ({ tintColor }) => (
|
|
247
|
+
<Button title="Edit" color={tintColor} onPress={() => {}} />
|
|
248
|
+
),
|
|
249
|
+
headerRight: ({ tintColor }) => (
|
|
250
|
+
<Button title="Done" color={tintColor} onPress={() => {}} />
|
|
251
|
+
),
|
|
252
|
+
}}
|
|
253
|
+
/>
|
|
254
|
+
</Stack.Navigator>
|
|
255
|
+
);
|
|
256
|
+
}
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
- `unstable_headerLeftItems` and `unstable_headerRightItems` are only supported on iOS and override `headerLeft` and `headerRight` when both are specified.
|
|
260
|
+
- Use `headerLeft` when replacing the back button. Add `headerBackVisible: true` if the back button should still be shown alongside the custom left element.
|
|
261
|
+
- `headerTitle` is useful when the title needs custom typography or extra layout, but custom title elements do not animate with the native title transition.
|
|
262
|
+
- Use `headerBackground` for a gradient, image, or custom background view. For translucent native headers on iOS, prefer `headerTransparent: true` with `scrollEdgeEffects` for iOS 26+ or `headerBlurEffect` for earlier versions.
|
|
263
|
+
- Some behavior differs between iOS versions. On iOS 26+, `unstable_headerRightItems` can collapse into the system overflow menu when there is not enough space.
|
|
264
|
+
- Custom items with `type: 'custom'` in `unstable_headerRightItems` are not collapsed into the overflow menu.
|
|
265
|
+
- Labels are used when items collapse into the overflow menu, and for accessibility.
|
|
266
|
+
|
|
267
|
+
### Screen Presentations
|
|
268
|
+
|
|
269
|
+
Use the screen `presentation` option to control whether a screen is pushed normally or shown as a modal or sheet.
|
|
270
|
+
|
|
271
|
+
**Static API**
|
|
272
|
+
|
|
273
|
+
```tsx
|
|
274
|
+
const AppStack = createNativeStackNavigator({
|
|
275
|
+
screens: {
|
|
276
|
+
Home: HomeScreen,
|
|
277
|
+
Compose: {
|
|
278
|
+
screen: ComposeScreen,
|
|
279
|
+
options: {
|
|
280
|
+
presentation: 'modal',
|
|
281
|
+
animation: 'slide_from_bottom',
|
|
282
|
+
},
|
|
283
|
+
},
|
|
284
|
+
},
|
|
285
|
+
});
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
**Dynamic API**
|
|
289
|
+
|
|
290
|
+
```tsx
|
|
291
|
+
import { createNativeStackNavigator } from '@react-navigation/native-stack';
|
|
292
|
+
|
|
293
|
+
const Stack = createNativeStackNavigator();
|
|
294
|
+
|
|
295
|
+
function AppStack() {
|
|
296
|
+
return (
|
|
297
|
+
<Stack.Navigator>
|
|
298
|
+
<Stack.Screen name="Home" component={HomeScreen} />
|
|
299
|
+
<Stack.Screen
|
|
300
|
+
name="Compose"
|
|
301
|
+
component={ComposeScreen}
|
|
302
|
+
options={{
|
|
303
|
+
presentation: 'modal',
|
|
304
|
+
animation: 'slide_from_bottom',
|
|
305
|
+
}}
|
|
306
|
+
/>
|
|
307
|
+
</Stack.Navigator>
|
|
308
|
+
);
|
|
309
|
+
}
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
- Use `card` for the default push presentation.
|
|
313
|
+
- Use `modal` for a standard modal presentation.
|
|
314
|
+
- Use `containedModal` for a current-context modal presentation on iOS and the default modal presentation on Android.
|
|
315
|
+
- Use `fullScreenModal` when the screen should take over the whole screen. On iOS, this presentation cannot be dismissed by gesture.
|
|
316
|
+
- Use `transparentModal` or `containedTransparentModal` when the previous screen should remain visible behind translucent content.
|
|
317
|
+
- Use `formSheet` when the design calls for a native sheet. Use [form-sheet.md](./form-sheet.md) for detents and platform-specific caveats.
|
|
318
|
+
- Use the `animation` option in the section below when the default transition does not fit the flow.
|
|
319
|
+
|
|
320
|
+
### Transition Animations
|
|
321
|
+
|
|
322
|
+
Use `animation` option to customize the transition animation.
|
|
323
|
+
|
|
324
|
+
**Static API**
|
|
325
|
+
|
|
326
|
+
```tsx
|
|
327
|
+
const AppStack = createNativeStackNavigator({
|
|
328
|
+
screens: {
|
|
329
|
+
Home: HomeScreen,
|
|
330
|
+
Details: {
|
|
331
|
+
screen: DetailsScreen,
|
|
332
|
+
options: {
|
|
333
|
+
animation: 'fade_from_bottom',
|
|
334
|
+
animationDuration: 300,
|
|
335
|
+
},
|
|
336
|
+
},
|
|
337
|
+
},
|
|
338
|
+
});
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
**Dynamic API**
|
|
342
|
+
|
|
343
|
+
```tsx
|
|
344
|
+
import { createNativeStackNavigator } from '@react-navigation/native-stack';
|
|
345
|
+
|
|
346
|
+
const Stack = createNativeStackNavigator();
|
|
347
|
+
|
|
348
|
+
function AppStack() {
|
|
349
|
+
return (
|
|
350
|
+
<Stack.Navigator>
|
|
351
|
+
<Stack.Screen name="Home" component={HomeScreen} />
|
|
352
|
+
<Stack.Screen
|
|
353
|
+
name="Details"
|
|
354
|
+
component={DetailsScreen}
|
|
355
|
+
options={{
|
|
356
|
+
animation: 'fade_from_bottom',
|
|
357
|
+
animationDuration: 300,
|
|
358
|
+
}}
|
|
359
|
+
/>
|
|
360
|
+
</Stack.Navigator>
|
|
361
|
+
);
|
|
362
|
+
}
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
- Supported `animation` values include `default`, `fade`, `fade_from_bottom`, `simple_push`, `slide_from_bottom`, `slide_from_right`, `slide_from_left`, `flip`, and `none`.
|
|
366
|
+
- `flip` requires `presentation: 'modal'` on iOS.
|
|
367
|
+
- `slide_from_right` and `slide_from_left` fall back to the default transition on iOS.
|
|
368
|
+
- `simple_push` removes the shadow and native header transition on iOS and falls back to the default transition on Android.
|
|
369
|
+
- Use `animationTypeForReplace: 'pop'` when `navigation.replace(...)` should feel like going back, such as auth or onboarding flows.
|
|
370
|
+
- Use `animationDuration` on iOS to tune `slide_from_bottom`, `fade_from_bottom`, `fade`, and `simple_push`. It does not apply to `default`, `flip`, or screens presented as `modal` or `formSheet`.
|
|
371
|
+
- Gesture-related transition options are only supported on iOS.
|
|
372
|
+
- Use `gestureEnabled` to disable swipe-to-dismiss when the animation should only run programmatically.
|
|
373
|
+
- Use `fullScreenGestureEnabled` to start the dismiss gesture anywhere on the screen. This uses `simple_push`-style behavior, and the default iOS transition cannot be matched due to platform limitations.
|
|
374
|
+
- Use `animationMatchesGesture` when the interactive dismiss gesture should follow the `animation` option. It does not affect screens presented modally.
|
|
375
|
+
- Use `fullScreenGestureShadowEnabled` to control the shadow shown during a full-screen dismiss gesture.
|
|
376
|
+
- On iOS, `gestureDirection: 'vertical'` implies `animation: 'slide_from_bottom'` together with full-screen dismissal gestures.
|
|
377
|
+
|
|
378
|
+
## Notes
|
|
379
|
+
|
|
380
|
+
- For scrollable content and `contentInsetAdjustmentBehavior="automatic"`, native stack needs it to be in the first-descendant chain — no views should be rendered before the scrollable view.
|
|
381
|
+
|
|
382
|
+
## Canonical Docs
|
|
383
|
+
|
|
384
|
+
- [Native Stack Navigator](https://reactnavigation.org/docs/native-stack-navigator)
|
|
385
|
+
- [Moving between screens](https://reactnavigation.org/docs/navigating)
|
|
386
|
+
- [Configuring the header bar](https://reactnavigation.org/docs/headers)
|
|
387
|
+
- [Opening a modal](https://reactnavigation.org/docs/modal)
|
|
388
|
+
|
|
389
|
+
## Related Skills
|
|
390
|
+
|
|
391
|
+
- [form-sheet.md](./form-sheet.md)
|
|
392
|
+
- [safe-areas.md](./safe-areas.md)
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: upgrading-react-native
|
|
3
|
+
description: Upgrades React Native apps to newer versions by applying rn-diff-purge template diffs, updating package.json dependencies, migrating native iOS and Android configuration, resolving CocoaPods and Gradle changes, and handling breaking API updates. Use when upgrading React Native, bumping RN version, updating from RN 0.x to 0.y, or migrating Expo SDK alongside a React Native upgrade.
|
|
4
|
+
license: MIT
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Upgrading React Native
|
|
8
|
+
|
|
9
|
+
## Overview
|
|
10
|
+
|
|
11
|
+
Covers the full React Native upgrade workflow: template diffs via Upgrade Helper, dependency updates, Expo SDK steps, and common pitfalls.
|
|
12
|
+
|
|
13
|
+
## Typical Upgrade Sequence
|
|
14
|
+
|
|
15
|
+
1. **Route**: Choose the right upgrade path via [upgrading-react-native.md][upgrading-react-native]
|
|
16
|
+
2. **Diff**: Fetch the canonical template diff using Upgrade Helper via [upgrade-helper-core.md][upgrade-helper-core]
|
|
17
|
+
3. **Dependencies**: Assess and update third-party packages via [upgrading-dependencies.md][upgrading-dependencies]
|
|
18
|
+
4. **React**: Align React version if upgraded via [react.md][react]
|
|
19
|
+
5. **Expo** (if applicable): Apply Expo SDK layer via [expo-sdk-upgrade.md][expo-sdk-upgrade]
|
|
20
|
+
6. **Verify**: Run post-upgrade checks via [upgrade-verification.md][upgrade-verification]
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
# Quick start: detect current version and fetch diff
|
|
24
|
+
npm pkg get dependencies.react-native --prefix "$APP_DIR"
|
|
25
|
+
npm view react-native dist-tags.latest
|
|
26
|
+
|
|
27
|
+
# Example: upgrading from 0.76.9 to 0.78.2
|
|
28
|
+
# 1. Fetch the template diff
|
|
29
|
+
curl -L -f -o /tmp/rn-diff.diff \
|
|
30
|
+
"https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/0.76.9..0.78.2.diff" \
|
|
31
|
+
&& echo "Diff downloaded OK" || echo "ERROR: diff not found, check versions"
|
|
32
|
+
# 2. Review changed files
|
|
33
|
+
grep -n "^diff --git" /tmp/rn-diff.diff
|
|
34
|
+
# 3. Update package.json, apply native changes, then install + rebuild
|
|
35
|
+
npm install --prefix "$APP_DIR"
|
|
36
|
+
cd "$APP_DIR/ios" && pod install
|
|
37
|
+
# 4. Validate: both platforms must build successfully
|
|
38
|
+
npx react-native build-android --mode debug --no-packager
|
|
39
|
+
xcodebuild -workspace "$APP_DIR/ios/App.xcworkspace" -scheme App -sdk iphonesimulator build
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## When to Apply
|
|
43
|
+
|
|
44
|
+
Reference these guidelines when:
|
|
45
|
+
- Moving a React Native app to a newer version
|
|
46
|
+
- Reconciling native config changes from Upgrade Helper
|
|
47
|
+
- Validating release notes for breaking changes
|
|
48
|
+
|
|
49
|
+
## Quick Reference
|
|
50
|
+
|
|
51
|
+
| File | Description |
|
|
52
|
+
|------|-------------|
|
|
53
|
+
| [upgrading-react-native.md][upgrading-react-native] | Router: choose the right upgrade path |
|
|
54
|
+
| [upgrade-helper-core.md][upgrade-helper-core] | Core Upgrade Helper workflow and reliability gates |
|
|
55
|
+
| [upgrading-dependencies.md][upgrading-dependencies] | Dependency compatibility checks and migration planning |
|
|
56
|
+
| [react.md][react] | React and React 19 upgrade alignment rules |
|
|
57
|
+
| [expo-sdk-upgrade.md][expo-sdk-upgrade] | Expo SDK-specific upgrade layer (conditional) |
|
|
58
|
+
| [upgrade-verification.md][upgrade-verification] | Post-upgrade verification checklist, including agent-device-assisted checks |
|
|
59
|
+
| [monorepo-singlerepo-targeting.md][monorepo-singlerepo-targeting] | Monorepo and single-repo app targeting and command scoping |
|
|
60
|
+
|
|
61
|
+
## Problem → Skill Mapping
|
|
62
|
+
|
|
63
|
+
| Problem | Start With |
|
|
64
|
+
|---------|------------|
|
|
65
|
+
| Need to upgrade React Native | [upgrade-helper-core.md][upgrade-helper-core] |
|
|
66
|
+
| Need dependency risk triage and migration options | [upgrading-dependencies.md][upgrading-dependencies] |
|
|
67
|
+
| Need React/React 19 package alignment | [react.md][react] |
|
|
68
|
+
| Need workflow routing first | [upgrading-react-native.md][upgrading-react-native] |
|
|
69
|
+
| Need Expo SDK-specific steps | [expo-sdk-upgrade.md][expo-sdk-upgrade] |
|
|
70
|
+
| Need manual or agent-assisted regression validation | [upgrade-verification.md][upgrade-verification] |
|
|
71
|
+
| Need repo/app command scoping | [monorepo-singlerepo-targeting.md][monorepo-singlerepo-targeting] |
|
|
72
|
+
|
|
73
|
+
[upgrading-react-native]: references/upgrading-react-native.md
|
|
74
|
+
[upgrade-helper-core]: references/upgrade-helper-core.md
|
|
75
|
+
[upgrading-dependencies]: references/upgrading-dependencies.md
|
|
76
|
+
[react]: references/react.md
|
|
77
|
+
[expo-sdk-upgrade]: references/expo-sdk-upgrade.md
|
|
78
|
+
[upgrade-verification]: references/upgrade-verification.md
|
|
79
|
+
[monorepo-singlerepo-targeting]: references/monorepo-singlerepo-targeting.md
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Expo SDK Upgrade Layer
|
|
3
|
+
impact: HIGH
|
|
4
|
+
tags: expo, sdk, react-native, dependencies
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Skill: Expo SDK Upgrade Layer
|
|
8
|
+
|
|
9
|
+
Expo-specific add-on to the core Upgrade Helper workflow. Use only when `expo` exists in app `package.json`.
|
|
10
|
+
|
|
11
|
+
## Quick Commands
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm pkg get dependencies.expo devDependencies.expo --prefix "$APP_DIR"
|
|
15
|
+
cd "$APP_DIR" && npx expo install --fix
|
|
16
|
+
cd "$APP_DIR" && npx expo-doctor
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## When to Apply
|
|
20
|
+
|
|
21
|
+
- `expo` or `expo-updates` is present in the target app package
|
|
22
|
+
- RN upgrade is paired with Expo SDK upgrade
|
|
23
|
+
|
|
24
|
+
## Official Expo Reference
|
|
25
|
+
|
|
26
|
+
- Follow Expo's official upgrade skill as a primary guide:
|
|
27
|
+
- [Expo Upgrading Expo Skill][expo-upgrading-expo-skill]
|
|
28
|
+
- Important for this workflow: skip `app.json` changes, because this is not an Expo Managed project.
|
|
29
|
+
|
|
30
|
+
## Pre-Upgrade Audit (Required)
|
|
31
|
+
|
|
32
|
+
- Confirm SDK version and target path.
|
|
33
|
+
- Inventory dependencies and native modules.
|
|
34
|
+
- Review config plugins and prebuild behavior.
|
|
35
|
+
- Review native build setup (Gradle, iOS settings, CI/EAS config).
|
|
36
|
+
- Identify critical app flows for regression testing before changes.
|
|
37
|
+
|
|
38
|
+
## Workflow Additions
|
|
39
|
+
|
|
40
|
+
1. Run Expo compatibility alignment.
|
|
41
|
+
- `npx expo install --fix` (source of truth for SDK-compatible versions).
|
|
42
|
+
- Treat `expo-modules` package versions as SDK-coupled; align them with Expo recommendations.
|
|
43
|
+
2. Run health checks.
|
|
44
|
+
- `npx expo-doctor`; resolve blocking issues first.
|
|
45
|
+
3. If native folders are part of workflow, reconcile prebuild output.
|
|
46
|
+
- `npx expo prebuild --clean` (when applicable).
|
|
47
|
+
4. Handle React 19 pairing.
|
|
48
|
+
- Run [react.md](react.md).
|
|
49
|
+
5. Run [upgrade-verification.md](upgrade-verification.md) for manual or agent-assisted regression checks and release gates.
|
|
50
|
+
|
|
51
|
+
## Notes
|
|
52
|
+
|
|
53
|
+
- Use `npx expo ...`; do not require global `expo-cli`.
|
|
54
|
+
- Some package bumps may be optional if not SDK-bound; validate before deferring.
|
|
55
|
+
- Read Expo and React Native release notes deeply before editing code, then map each breaking change to a concrete code/task item.
|
|
56
|
+
|
|
57
|
+
## Related Skills
|
|
58
|
+
|
|
59
|
+
- [upgrading-react-native.md](upgrading-react-native.md) - Routing and mode selection
|
|
60
|
+
- [upgrade-helper-core.md](upgrade-helper-core.md) - Base upgrade workflow
|
|
61
|
+
- [react.md](react.md) - React and React 19 alignment
|
|
62
|
+
- [upgrade-verification.md](upgrade-verification.md) - Post-upgrade validation, including agent-device-assisted checks
|
|
63
|
+
- [monorepo-singlerepo-targeting.md](monorepo-singlerepo-targeting.md) - Repo/app selection and command scoping
|
|
64
|
+
|
|
65
|
+
[expo-upgrading-expo-skill]: https://github.com/expo/skills/blob/main/plugins/upgrading-expo/skills/upgrading-expo/SKILL.md
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Monorepo vs Single-App Targeting
|
|
3
|
+
impact: HIGH
|
|
4
|
+
tags: monorepo, workspace, react-native, app-selection
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Skill: Monorepo vs Single-App Targeting
|
|
8
|
+
|
|
9
|
+
Small instruction set for selecting the correct app package and running upgrade commands in the right scope.
|
|
10
|
+
|
|
11
|
+
## Quick Commands
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
APP_DIR=apps/mobile
|
|
15
|
+
npm pkg get dependencies.react-native devDependencies.react-native --prefix "$APP_DIR"
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Rules
|
|
19
|
+
|
|
20
|
+
1. Pick one target app package before any upgrade command.
|
|
21
|
+
2. Run all app-specific commands with `--prefix "$APP_DIR"` or from `cd "$APP_DIR"`.
|
|
22
|
+
3. Use `APP_DIR=.` for single-package repos.
|
|
23
|
+
4. Never apply diffs to workspace root when RN app lives in a subpackage.
|
|
24
|
+
|
|
25
|
+
## Verification
|
|
26
|
+
|
|
27
|
+
- `react-native` is present in `APP_DIR/package.json`.
|
|
28
|
+
- `ios/` and `android/` paths used for build/pods are under `APP_DIR`.
|
|
29
|
+
|
|
30
|
+
## Related Skills
|
|
31
|
+
|
|
32
|
+
- [upgrading-react-native.md](upgrading-react-native.md) - Routing and mode selection
|
|
33
|
+
- [upgrade-helper-core.md](upgrade-helper-core.md) - Base upgrade workflow
|
|
34
|
+
- [expo-sdk-upgrade.md](expo-sdk-upgrade.md) - Expo-specific steps
|
package/stacks/react-native/template/.agents/skills/upgrading-react-native/references/react.md
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: React Upgrade Layer
|
|
3
|
+
impact: HIGH
|
|
4
|
+
tags: react, react-19, rntl, types
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Skill: React Upgrade Layer
|
|
8
|
+
|
|
9
|
+
React-specific upgrade rules to run when `react` changes during a React Native or Expo upgrade.
|
|
10
|
+
|
|
11
|
+
## When to Apply
|
|
12
|
+
|
|
13
|
+
- `react` version changes (major, minor, or patch).
|
|
14
|
+
- React Native target implies a newer React pairing.
|
|
15
|
+
- Tests/types break after React upgrade.
|
|
16
|
+
|
|
17
|
+
## React Pairing Rules
|
|
18
|
+
|
|
19
|
+
1. Keep companion packages aligned with installed React version:
|
|
20
|
+
- `react-test-renderer`
|
|
21
|
+
- `@types/react`
|
|
22
|
+
- `react-dom` (if used by the app)
|
|
23
|
+
2. Prefer matching React major and minor exactly; patch should also match when available.
|
|
24
|
+
3. Do not leave these packages on older `x.y` after upgrading `react`.
|
|
25
|
+
|
|
26
|
+
## React 19 Rules
|
|
27
|
+
|
|
28
|
+
1. Upgrade `@testing-library/react-native` to `v13+`.
|
|
29
|
+
2. Follow:
|
|
30
|
+
- [Expo React 19 Reference][expo-react-19-reference]
|
|
31
|
+
- [RNTL LLM Docs][rntl-llm-docs]
|
|
32
|
+
3. Expect type-level breakages from deprecated API removals; fix code and mocks accordingly.
|
|
33
|
+
|
|
34
|
+
## Related Skills
|
|
35
|
+
|
|
36
|
+
- [upgrade-helper-core.md](upgrade-helper-core.md) - Core RN upgrade workflow
|
|
37
|
+
- [upgrading-dependencies.md](upgrading-dependencies.md) - Dependency compatibility triage
|
|
38
|
+
- [expo-sdk-upgrade.md](expo-sdk-upgrade.md) - Expo-specific upgrade layer
|
|
39
|
+
- [upgrade-verification.md](upgrade-verification.md) - Post-upgrade validation, including agent-device-assisted checks
|
|
40
|
+
|
|
41
|
+
[expo-react-19-reference]: https://github.com/expo/skills/blob/main/plugins/upgrading-expo/skills/upgrading-expo/references/react-19.md
|
|
42
|
+
[rntl-llm-docs]: https://oss.callstack.com/react-native-testing-library/llms.txt
|