summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorFernando Rojo <fernando.rojo@vercel.com>2026-01-27 09:20:04 -0800
committerFernando Rojo <fernando.rojo@vercel.com>2026-01-27 09:20:04 -0800
commit485beb804924eb4d96ea99e88a44439039c1ab5e (patch)
tree4cf29a11272b41e380fb5eeb821cbd51b4aec0d4
parent757ccb42a20478be6b7284088978070358b52d5e (diff)
native navigatorsf/native
-rw-r--r--packages/react-best-practices-build/src/config.ts19
-rw-r--r--skills/react-native-skills/AGENTS.md167
-rw-r--r--skills/react-native-skills/rules/list-performance-item-types.md2
-rw-r--r--skills/react-native-skills/rules/navigation-native-navigators.md62
4 files changed, 146 insertions, 104 deletions
diff --git a/packages/react-best-practices-build/src/config.ts b/packages/react-best-practices-build/src/config.ts
index ea75a62..249016f 100644
--- a/packages/react-best-practices-build/src/config.ts
+++ b/packages/react-best-practices-build/src/config.ts
@@ -56,15 +56,16 @@ export const SKILLS: Record<string, SkillConfig> = {
'list-performance': 2,
animation: 3,
scroll: 4,
- 'react-state': 5,
- state: 6,
- 'react-compiler': 7,
- ui: 8,
- 'design-system': 9,
- monorepo: 10,
- imports: 11,
- js: 12,
- fonts: 13,
+ navigation: 5,
+ 'react-state': 6,
+ state: 7,
+ 'react-compiler': 8,
+ ui: 9,
+ 'design-system': 10,
+ monorepo: 11,
+ imports: 12,
+ js: 13,
+ fonts: 14,
},
},
'composition-patterns': {
diff --git a/skills/react-native-skills/AGENTS.md b/skills/react-native-skills/AGENTS.md
index 825002a..d263eb9 100644
--- a/skills/react-native-skills/AGENTS.md
+++ b/skills/react-native-skills/AGENTS.md
@@ -750,12 +750,17 @@ Request images at 2x the display size for retina screens.
**Impact: HIGH (efficient recycling, less layout thrashing)**
-When a list has different item layouts (messages, images, headers, etc.), use
-a `type` field on each item and provide `getItemType` to the list. This puts
-items into separate recycling pools so a message component never gets recycled
-into an image component.
+When a list has different item layouts (messages, images, headers, etc.), use a
-**Incorrect (single component with conditionals):**
+`type` field on each item and provide `getItemType` to the list. This puts items
+
+into separate recycling pools so a message component never gets recycled into an
+
+image component.
+
+[LegendList getItemType](https://legendapp.com/open-source/list/api/props/#getitemtype-v2)
+
+**Incorrect: single component with conditionals**
```tsx
type Item = { id: string; text?: string; imageUrl?: string; isHeader?: boolean }
@@ -781,7 +786,7 @@ function Feed({ items }: { items: Item[] }) {
}
```
-**Correct (typed items with separate components):**
+**Correct: typed items with separate components**
```tsx
type HeaderItem = { id: string; type: 'header'; title: string }
@@ -793,6 +798,7 @@ function Feed({ items }: { items: FeedItem[] }) {
return (
<LegendList
data={items}
+ keyExtractor={(item) => item.id}
getItemType={(item) => item.type}
renderItem={({ item }) => {
switch (item.type) {
@@ -812,30 +818,39 @@ function Feed({ items }: { items: FeedItem[] }) {
**Why this matters:**
-- **Recycling efficiency**: Items with the same type share a recycling pool
-- **No layout thrashing**: A header never recycles into an image cell
-- **Type safety**: TypeScript can narrow the item type in each branch
-- **Better size estimation**: Use `getEstimatedItemSize` with `itemType` for accurate estimates per type
-
```tsx
<LegendList
data={items}
+ keyExtractor={(item) => item.id}
getItemType={(item) => item.type}
getEstimatedItemSize={(index, item, itemType) => {
switch (itemType) {
- case 'header': return 48
- case 'message': return 72
- case 'image': return 300
- default: return 72
+ case 'header':
+ return 48
+ case 'message':
+ return 72
+ case 'image':
+ return 300
+ default:
+ return 72
}
}}
- renderItem={({ item }) => { /* ... */ }}
+ renderItem={({ item }) => {
+ /* ... */
+ }}
recycleItems
/>
```
-Reference:
-[LegendList getItemType](https://legendapp.com/open-source/list/api/props/#getitemtype-v2)
+- **Recycling efficiency**: Items with the same type share a recycling pool
+
+- **No layout thrashing**: A header never recycles into an image cell
+
+- **Type safety**: TypeScript can narrow the item type in each branch
+
+- **Better size estimation**: Use `getEstimatedItemSize` with `itemType` for
+
+ accurate estimates per type
---
@@ -1156,16 +1171,28 @@ JS-based alternatives.
**Impact: HIGH (native performance, platform-appropriate UI)**
Always use native navigators instead of JS-based ones. Native navigators use
+
platform APIs (UINavigationController on iOS, Fragment on Android) for better
+
performance and native behavior.
**For stacks:** Use `@react-navigation/native-stack` or expo-router's default
+
stack (which uses native-stack). Avoid `@react-navigation/stack`.
**For tabs:** Use `react-native-bottom-tabs` (native) or expo-router's native
+
tabs. Avoid `@react-navigation/bottom-tabs` when native feel matters.
-**Incorrect (JS stack navigator):**
+- [React Navigation Native Stack](https://reactnavigation.org/docs/native-stack-navigator)
+
+- [React Native Bottom Tabs with React Navigation](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-react-navigation)
+
+- [React Native Bottom Tabs with Expo Router](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-expo-router)
+
+- [Expo Router Native Tabs](https://docs.expo.dev/router/advanced/native-tabs)
+
+**Incorrect: JS stack navigator**
```tsx
import { createStackNavigator } from '@react-navigation/stack'
@@ -1175,14 +1202,14 @@ const Stack = createStackNavigator()
function App() {
return (
<Stack.Navigator>
- <Stack.Screen name="Home" component={HomeScreen} />
- <Stack.Screen name="Details" component={DetailsScreen} />
+ <Stack.Screen name='Home' component={HomeScreen} />
+ <Stack.Screen name='Details' component={DetailsScreen} />
</Stack.Navigator>
)
}
```
-**Correct (native stack with react-navigation):**
+**Correct: native stack with react-navigation**
```tsx
import { createNativeStackNavigator } from '@react-navigation/native-stack'
@@ -1192,14 +1219,14 @@ const Stack = createNativeStackNavigator()
function App() {
return (
<Stack.Navigator>
- <Stack.Screen name="Home" component={HomeScreen} />
- <Stack.Screen name="Details" component={DetailsScreen} />
+ <Stack.Screen name='Home' component={HomeScreen} />
+ <Stack.Screen name='Details' component={DetailsScreen} />
</Stack.Navigator>
)
}
```
-**Correct (expo-router uses native stack by default):**
+**Correct: expo-router uses native stack by default**
```tsx
// app/_layout.tsx
@@ -1210,7 +1237,7 @@ export default function Layout() {
}
```
-**Incorrect (JS bottom tabs):**
+**Incorrect: JS bottom tabs**
```tsx
import { createBottomTabNavigator } from '@react-navigation/bottom-tabs'
@@ -1220,17 +1247,17 @@ const Tab = createBottomTabNavigator()
function App() {
return (
<Tab.Navigator>
- <Tab.Screen name="Home" component={HomeScreen} />
- <Tab.Screen name="Settings" component={SettingsScreen} />
+ <Tab.Screen name='Home' component={HomeScreen} />
+ <Tab.Screen name='Settings' component={SettingsScreen} />
</Tab.Navigator>
)
}
```
-**Correct (native bottom tabs with react-navigation):**
+**Correct: native bottom tabs with react-navigation**
```tsx
-import { createNativeBottomTabNavigator } from 'react-native-bottom-tabs/react-navigation'
+import { createNativeBottomTabNavigator } from '@bottom-tabs/react-navigation'
const Tab = createNativeBottomTabNavigator()
@@ -1238,14 +1265,14 @@ function App() {
return (
<Tab.Navigator>
<Tab.Screen
- name="Home"
+ name='Home'
component={HomeScreen}
options={{
tabBarIcon: () => ({ sfSymbol: 'house' }),
}}
/>
<Tab.Screen
- name="Settings"
+ name='Settings'
component={SettingsScreen}
options={{
tabBarIcon: () => ({ sfSymbol: 'gear' }),
@@ -1256,51 +1283,57 @@ function App() {
}
```
-**Correct (expo-router native tabs):**
+**Correct: expo-router native tabs**
```tsx
// app/(tabs)/_layout.tsx
-import { NativeTabs } from 'expo-router/native-tabs'
+import { NativeTabs } from 'expo-router/unstable-native-tabs'
export default function TabLayout() {
return (
<NativeTabs>
- <NativeTabs.Screen
- name="index"
- options={{
- title: 'Home',
- tabBarIcon: ({ sfSymbol: 'house' }),
- }}
- />
- <NativeTabs.Screen
- name="settings"
- options={{
- title: 'Settings',
- tabBarIcon: ({ sfSymbol: 'gear' }),
- }}
- />
+ <NativeTabs.Trigger name='index'>
+ <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
+ <NativeTabs.Trigger.Icon sf='house.fill' md='home' />
+ </NativeTabs.Trigger>
+ <NativeTabs.Trigger name='settings'>
+ <NativeTabs.Trigger.Label>Settings</NativeTabs.Trigger.Label>
+ <NativeTabs.Trigger.Icon sf='gear' md='settings' />
+ </NativeTabs.Trigger>
</NativeTabs>
)
}
```
-**Prefer native header options over custom components:**
+On iOS, native tabs automatically enable `contentInsetAdjustmentBehavior` on the
+
+first `ScrollView` at the root of each tab screen, so content scrolls correctly
+
+behind the translucent tab bar. If you need to disable this, use
+
+`disableAutomaticContentInsets` on the trigger.
+
+**Incorrect: custom header component**
```tsx
-// Incorrect: custom header component
<Stack.Screen
- name="Profile"
+ name='Profile'
+ component={ProfileScreen}
options={{
- header: () => <CustomHeader title="Profile" />,
+ header: () => <CustomHeader title='Profile' />,
}}
/>
+```
+
+**Correct: native header options**
-// Correct: native header options
+```tsx
<Stack.Screen
- name="Profile"
+ name='Profile'
+ component={ProfileScreen}
options={{
title: 'Profile',
- headerLargeTitle: true,
+ headerLargeTitleEnabled: true,
headerSearchBarOptions: {
placeholder: 'Search',
},
@@ -1309,19 +1342,18 @@ export default function TabLayout() {
```
Native headers support iOS large titles, search bars, blur effects, and proper
-safe area handling automatically.
-**Why native navigators:**
+safe area handling automatically.
- **Performance**: Native transitions and gestures run on the UI thread
+
- **Platform behavior**: Automatic iOS large titles, Android material design
-- **System integration**: Scroll-to-top on tab tap, PiP avoidance, proper safe areas
-- **Accessibility**: Platform accessibility features work automatically
-Reference:
-- [React Navigation Native Stack](https://reactnavigation.org/docs/native-stack-navigator)
-- [React Navigation Native Bottom Tabs](https://reactnavigation.org/docs/native-bottom-tab-navigator)
-- [Expo Router Native Tabs](https://docs.expo.dev/router/advanced/native-tabs)
+- **System integration**: Scroll-to-top on tab tap, PiP avoidance, proper safe
+
+ areas
+
+- **Accessibility**: Platform accessibility features work automatically
---
@@ -2430,6 +2462,7 @@ accessibility out of the box.
**Impact: LOW (modern API, more flexible)**
Never use `TouchableOpacity` or `TouchableHighlight`. Use `Pressable` from
+
`react-native` or `react-native-gesture-handler` instead.
**Incorrect: legacy Touchable components**
@@ -2475,12 +2508,16 @@ function ListItem({ onPress }: { onPress: () => void }) {
```
Use `react-native-gesture-handler` Pressable inside scrollable lists for better
+
gesture coordination, as long as you are using the ScrollView from
+
`react-native-gesture-handler` as well.
**For animated press states (scale, opacity changes):** Use `GestureDetector`
-with Reanimated shared values instead of Pressable's style callback. See rule
-3.3 (Use GestureDetector for Animated Press States).
+
+with Reanimated shared values instead of Pressable's style callback. See the
+
+`animation-gesture-detector-press` rule.
---
diff --git a/skills/react-native-skills/rules/list-performance-item-types.md b/skills/react-native-skills/rules/list-performance-item-types.md
index 09a9550..1027e4e 100644
--- a/skills/react-native-skills/rules/list-performance-item-types.md
+++ b/skills/react-native-skills/rules/list-performance-item-types.md
@@ -50,6 +50,7 @@ function Feed({ items }: { items: FeedItem[] }) {
return (
<LegendList
data={items}
+ keyExtractor={(item) => item.id}
getItemType={(item) => item.type}
renderItem={({ item }) => {
switch (item.type) {
@@ -78,6 +79,7 @@ function Feed({ items }: { items: FeedItem[] }) {
```tsx
<LegendList
data={items}
+ keyExtractor={(item) => item.id}
getItemType={(item) => item.type}
getEstimatedItemSize={(index, item, itemType) => {
switch (itemType) {
diff --git a/skills/react-native-skills/rules/navigation-native-navigators.md b/skills/react-native-skills/rules/navigation-native-navigators.md
index c973cd8..035c5fd 100644
--- a/skills/react-native-skills/rules/navigation-native-navigators.md
+++ b/skills/react-native-skills/rules/navigation-native-navigators.md
@@ -29,8 +29,8 @@ const Stack = createStackNavigator()
function App() {
return (
<Stack.Navigator>
- <Stack.Screen name="Home" component={HomeScreen} />
- <Stack.Screen name="Details" component={DetailsScreen} />
+ <Stack.Screen name='Home' component={HomeScreen} />
+ <Stack.Screen name='Details' component={DetailsScreen} />
</Stack.Navigator>
)
}
@@ -46,8 +46,8 @@ const Stack = createNativeStackNavigator()
function App() {
return (
<Stack.Navigator>
- <Stack.Screen name="Home" component={HomeScreen} />
- <Stack.Screen name="Details" component={DetailsScreen} />
+ <Stack.Screen name='Home' component={HomeScreen} />
+ <Stack.Screen name='Details' component={DetailsScreen} />
</Stack.Navigator>
)
}
@@ -76,8 +76,8 @@ const Tab = createBottomTabNavigator()
function App() {
return (
<Tab.Navigator>
- <Tab.Screen name="Home" component={HomeScreen} />
- <Tab.Screen name="Settings" component={SettingsScreen} />
+ <Tab.Screen name='Home' component={HomeScreen} />
+ <Tab.Screen name='Settings' component={SettingsScreen} />
</Tab.Navigator>
)
}
@@ -86,7 +86,7 @@ function App() {
**Correct (native bottom tabs with react-navigation):**
```tsx
-import { createNativeBottomTabNavigator } from 'react-native-bottom-tabs/react-navigation'
+import { createNativeBottomTabNavigator } from '@bottom-tabs/react-navigation'
const Tab = createNativeBottomTabNavigator()
@@ -94,14 +94,14 @@ function App() {
return (
<Tab.Navigator>
<Tab.Screen
- name="Home"
+ name='Home'
component={HomeScreen}
options={{
tabBarIcon: () => ({ sfSymbol: 'house' }),
}}
/>
<Tab.Screen
- name="Settings"
+ name='Settings'
component={SettingsScreen}
options={{
tabBarIcon: () => ({ sfSymbol: 'gear' }),
@@ -116,40 +116,39 @@ function App() {
```tsx
// app/(tabs)/_layout.tsx
-import { NativeTabs } from 'expo-router/native-tabs'
+import { NativeTabs } from 'expo-router/unstable-native-tabs'
export default function TabLayout() {
return (
<NativeTabs>
- <NativeTabs.Screen
- name="index"
- options={{
- title: 'Home',
- tabBarIcon: ({ sfSymbol: 'house' }),
- }}
- />
- <NativeTabs.Screen
- name="settings"
- options={{
- title: 'Settings',
- tabBarIcon: ({ sfSymbol: 'gear' }),
- }}
- />
+ <NativeTabs.Trigger name='index'>
+ <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
+ <NativeTabs.Trigger.Icon sf='house.fill' md='home' />
+ </NativeTabs.Trigger>
+ <NativeTabs.Trigger name='settings'>
+ <NativeTabs.Trigger.Label>Settings</NativeTabs.Trigger.Label>
+ <NativeTabs.Trigger.Icon sf='gear' md='settings' />
+ </NativeTabs.Trigger>
</NativeTabs>
)
}
```
+On iOS, native tabs automatically enable `contentInsetAdjustmentBehavior` on the
+first `ScrollView` at the root of each tab screen, so content scrolls correctly
+behind the translucent tab bar. If you need to disable this, use
+`disableAutomaticContentInsets` on the trigger.
+
### Prefer Native Header Options Over Custom Components
**Incorrect (custom header component):**
```tsx
<Stack.Screen
- name="Profile"
+ name='Profile'
component={ProfileScreen}
options={{
- header: () => <CustomHeader title="Profile" />,
+ header: () => <CustomHeader title='Profile' />,
}}
/>
```
@@ -158,11 +157,11 @@ export default function TabLayout() {
```tsx
<Stack.Screen
- name="Profile"
+ name='Profile'
component={ProfileScreen}
options={{
title: 'Profile',
- headerLargeTitle: true,
+ headerLargeTitleEnabled: true,
headerSearchBarOptions: {
placeholder: 'Search',
},
@@ -177,10 +176,13 @@ safe area handling automatically.
- **Performance**: Native transitions and gestures run on the UI thread
- **Platform behavior**: Automatic iOS large titles, Android material design
-- **System integration**: Scroll-to-top on tab tap, PiP avoidance, proper safe areas
+- **System integration**: Scroll-to-top on tab tap, PiP avoidance, proper safe
+ areas
- **Accessibility**: Platform accessibility features work automatically
Reference:
+
- [React Navigation Native Stack](https://reactnavigation.org/docs/native-stack-navigator)
-- [React Navigation Native Bottom Tabs](https://reactnavigation.org/docs/native-bottom-tab-navigator)
+- [React Native Bottom Tabs with React Navigation](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-react-navigation)
+- [React Native Bottom Tabs with Expo Router](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-expo-router)
- [Expo Router Native Tabs](https://docs.expo.dev/router/advanced/native-tabs)