AGENTS.md

profiles/vercel-labs/agent-skills/vercel-labs_agent-skills_react-native-skills/for-codex/AGENTS.md

AGENTS.md

Quality

72/100

Scores the file, not the repository.

Length

8,409 words

56 headings · 125 code blocks

Repository

— · pushed 9 days ago

Last changed

today

First indexed today.

nota-america/forgecat-agent-profiles/profiles/vercel-labs/agent-skills/vercel-labs_agent-skills_react-native-skills/for-codex/AGENTS.md

1

2# Sections

4This file defines all sections, their ordering, impact levels, and descriptions.

5The section ID (in parentheses) is the filename prefix used to group rules.

7---

9## 1. Core Rendering (rendering)

11**Impact:** CRITICAL

12**Description:** Fundamental React Native rendering rules. Violations cause

13runtime crashes or broken UI.

15## 2. List Performance (list-performance)

17**Impact:** HIGH

18**Description:** Optimizing virtualized lists (FlatList, LegendList, FlashList)

19for smooth scrolling and fast updates.

21## 3. Animation (animation)

23**Impact:** HIGH

24**Description:** GPU-accelerated animations, Reanimated patterns, and avoiding

25render thrashing during gestures.

27## 4. Scroll Performance (scroll)

29**Impact:** HIGH

30**Description:** Tracking scroll position without causing render thrashing.

32## 5. Navigation (navigation)

34**Impact:** HIGH

35**Description:** Using native navigators for stack and tab navigation instead of

36JS-based alternatives.

38## 6. React State (react-state)

40**Impact:** MEDIUM

41**Description:** Patterns for managing React state to avoid stale closures and

42unnecessary re-renders.

44## 7. State Architecture (state)

46**Impact:** MEDIUM

47**Description:** Ground truth principles for state variables and derived values.

49## 8. React Compiler (react-compiler)

51**Impact:** MEDIUM

52**Description:** Compatibility patterns for React Compiler with React Native and

53Reanimated.

55## 9. User Interface (ui)

57**Impact:** MEDIUM

58**Description:** Native UI patterns for images, menus, modals, styling, and

59platform-consistent interfaces.

61## 10. Design System (design-system)

63**Impact:** MEDIUM

64**Description:** Architecture patterns for building maintainable component

65libraries.

67## 11. Monorepo (monorepo)

69**Impact:** LOW

70**Description:** Dependency management and native module configuration in

71monorepos.

73## 12. Third-Party Dependencies (imports)

75**Impact:** LOW

76**Description:** Wrapping and re-exporting third-party dependencies for

77maintainability.

79## 13. JavaScript (js)

81**Impact:** LOW

82**Description:** Micro-optimizations like hoisting expensive object creation.

84## 14. Fonts (fonts)

86**Impact:** LOW

87**Description:** Native font loading for improved performance.

88

90

91## Rule Title Here

93**Impact: MEDIUM (optional impact description)**

95Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.

97**Incorrect (description of what's wrong):**

99```typescript

100// Bad code example here

101const bad = example()

102```

103

104**Correct (description of what's right):**

105

106```typescript

107// Good code example here

108const good = example()

109```

110

111Reference: [Link to documentation or resource](https://example.com)

112

113

114

115## Prefer useDerivedValue Over useAnimatedReaction

116

117When deriving a shared value from another, use `useDerivedValue` instead of

118`useAnimatedReaction`. Derived values are declarative, automatically track

119dependencies, and return a value you can use directly. Animated reactions are

120for side effects, not derivations.

121

122**Incorrect (useAnimatedReaction for derivation):**

123

124```tsx

125import { useSharedValue, useAnimatedReaction } from 'react-native-reanimated'

126

127function MyComponent() {

128 const progress = useSharedValue(0)

129 const opacity = useSharedValue(1)

130

131 useAnimatedReaction(

132 () => progress.value,

133 (current) => {

134 opacity.value = 1 - current

135 }

136 )

137

138 // ...

139}

140```

141

142**Correct (useDerivedValue):**

143

144```tsx

145import { useSharedValue, useDerivedValue } from 'react-native-reanimated'

146

147function MyComponent() {

148 const progress = useSharedValue(0)

149

150 const opacity = useDerivedValue(() => 1 - progress.get())

151

152 // ...

153}

154```

155

156Use `useAnimatedReaction` only for side effects that don't produce a value

157(e.g., triggering haptics, logging, calling `runOnJS`).

158

159Reference:

160[Reanimated useDerivedValue](https://docs.swmansion.com/react-native-reanimated/docs/core/useDerivedValue)

161

162

163

164## Use GestureDetector for Animated Press States

165

166For animated press states (scale, opacity on press), use `GestureDetector` with

167`Gesture.Tap()` and shared values instead of Pressable's

168`onPressIn`/`onPressOut`. Gesture callbacks run on the UI thread as worklets—no

169JS thread round-trip for press animations.

170

171**Incorrect (Pressable with JS thread callbacks):**

172

173```tsx

174import { Pressable } from 'react-native'

175import Animated, {

176 useSharedValue,

177 useAnimatedStyle,

178 withTiming,

179} from 'react-native-reanimated'

180

181function AnimatedButton({ onPress }: { onPress: () => void }) {

182 const scale = useSharedValue(1)

183

184 const animatedStyle = useAnimatedStyle(() => ({

185 transform: [{ scale: scale.value }],

186 }))

187

188 return (

189 <Pressable

190 onPress={onPress}

191 onPressIn={() => (scale.value = withTiming(0.95))}

192 onPressOut={() => (scale.value = withTiming(1))}

193 >

194 <Animated.View style={animatedStyle}>

195 <Text>Press me</Text>

196 </Animated.View>

197 </Pressable>

198 )

199}

200```

201

202**Correct (GestureDetector with UI thread worklets):**

203

204```tsx

205import { Gesture, GestureDetector } from 'react-native-gesture-handler'

206import Animated, {

207 useSharedValue,

208 useAnimatedStyle,

209 withTiming,

210 interpolate,

211 runOnJS,

212} from 'react-native-reanimated'

213

214function AnimatedButton({ onPress }: { onPress: () => void }) {

215 // Store the press STATE (0 = not pressed, 1 = pressed)

216 const pressed = useSharedValue(0)

217

218 const tap = Gesture.Tap()

219 .onBegin(() => {

220 pressed.set(withTiming(1))

221 })

222 .onFinalize(() => {

223 pressed.set(withTiming(0))

224 })

225 .onEnd(() => {

226 runOnJS(onPress)()

227 })

228

229 // Derive visual values from the state

230 const animatedStyle = useAnimatedStyle(() => ({

231 transform: [

232 { scale: interpolate(withTiming(pressed.get()), [0, 1], [1, 0.95]) },

233 ],

234 }))

235

236 return (

237 <GestureDetector gesture={tap}>

238 <Animated.View style={animatedStyle}>

239 <Text>Press me</Text>

240 </Animated.View>

241 </GestureDetector>

242 )

243}

244```

245

246Store the press **state** (0 or 1), then derive the scale via `interpolate`.

247This keeps the shared value as ground truth. Use `runOnJS` to call JS functions

248from worklets. Use `.set()` and `.get()` for React Compiler compatibility.

249

250Reference:

251[Gesture Handler Tap Gesture](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture)

252

253

254

255## Animate Transform and Opacity Instead of Layout Properties

256

257Avoid animating `width`, `height`, `top`, `left`, `margin`, or `padding`. These trigger layout recalculation on every frame. Instead, use `transform` (scale, translate) and `opacity` which run on the GPU without triggering layout.

258

259**Incorrect (animates height, triggers layout every frame):**

260

261```tsx

262import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'

263

264function CollapsiblePanel({ expanded }: { expanded: boolean }) {

265 const animatedStyle = useAnimatedStyle(() => ({

266 height: withTiming(expanded ? 200 : 0), // triggers layout on every frame

267 overflow: 'hidden',

268 }))

269

270 return <Animated.View style={animatedStyle}>{children}</Animated.View>

271}

272```

273

274**Correct (animates scaleY, GPU-accelerated):**

275

276```tsx

277import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'

278

279function CollapsiblePanel({ expanded }: { expanded: boolean }) {

280 const animatedStyle = useAnimatedStyle(() => ({

281 transform: [

282 { scaleY: withTiming(expanded ? 1 : 0) },

283 ],

284 opacity: withTiming(expanded ? 1 : 0),

285 }))

286

287 return (

288 <Animated.View style={[{ height: 200, transformOrigin: 'top' }, animatedStyle]}>

289 {children}

290 </Animated.View>

291 )

292}

293```

294

295**Correct (animates translateY for slide animations):**

296

297```tsx

298import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'

299

300function SlideIn({ visible }: { visible: boolean }) {

301 const animatedStyle = useAnimatedStyle(() => ({

302 transform: [

303 { translateY: withTiming(visible ? 0 : 100) },

304 ],

305 opacity: withTiming(visible ? 1 : 0),

306 }))

307

308 return <Animated.View style={animatedStyle}>{children}</Animated.View>

309}

310```

311

312GPU-accelerated properties: `transform` (translate, scale, rotate), `opacity`. Everything else triggers layout.

313

314

315

316## Use Compound Components Over Polymorphic Children

317

318Don't create components that can accept a string if they aren't a text node. If

319a component can receive a string child, it must be a dedicated `*Text`

320component. For components like buttons, which can have both a View (or

321Pressable) together with text, use compound components, such a `Button`,

322`ButtonText`, and `ButtonIcon`.

323

324**Incorrect (polymorphic children):**

325

326```tsx

327import { Pressable, Text } from 'react-native'

328

329type ButtonProps = {

330 children: string | React.ReactNode

331 icon?: React.ReactNode

332}

333

334function Button({ children, icon }: ButtonProps) {

335 return (

336 <Pressable>

337 {icon}

338 {typeof children === 'string' ? <Text>{children}</Text> : children}

339 </Pressable>

340 )

341}

342

343// Usage is ambiguous

344<Button icon={<Icon />}>Save</Button>

345<Button><CustomText>Save</CustomText></Button>

346```

347

348**Correct (compound components):**

349

350```tsx

351import { Pressable, Text } from 'react-native'

352

353function Button({ children }: { children: React.ReactNode }) {

354 return <Pressable>{children}</Pressable>

355}

356

357function ButtonText({ children }: { children: React.ReactNode }) {

358 return <Text>{children}</Text>

359}

360

361function ButtonIcon({ children }: { children: React.ReactNode }) {

362 return <>{children}</>

363}

364

365// Usage is explicit and composable

366<Button>

367 <ButtonIcon><SaveIcon /></ButtonIcon>

368 <ButtonText>Save</ButtonText>

369</Button>

370

371<Button>

372 <ButtonText>Cancel</ButtonText>

373</Button>

374```

375

376

377

378## Use Expo Config Plugin for Font Loading

379

380Use the `expo-font` config plugin to embed fonts at build time instead of

381`useFonts` or `Font.loadAsync`. Embedded fonts are more efficient.

382

383**Incorrect (async font loading):**

384

385```tsx

386import { useFonts } from 'expo-font'

387import { Text, View } from 'react-native'

388

389function App() {

390 const [fontsLoaded] = useFonts({

391 'Geist-Bold': require('./assets/fonts/Geist-Bold.otf'),

392 })

393

394 if (!fontsLoaded) {

395 return null

396 }

397

398 return (

399 <View>

400 <Text style={{ fontFamily: 'Geist-Bold' }}>Hello</Text>

401 </View>

402 )

403}

404```

405

406**Correct (config plugin, fonts embedded at build):**

407

408```json

409// app.json

410{

411 "expo": {

412 "plugins": [

413 [

414 "expo-font",

415 {

416 "fonts": ["./assets/fonts/Geist-Bold.otf"]

417 }

418 ]

419 ]

420 }

421}

422```

423

424```tsx

425import { Text, View } from 'react-native'

426

427function App() {

428 // No loading state needed—font is already available

429 return (

430 <View>

431 <Text style={{ fontFamily: 'Geist-Bold' }}>Hello</Text>

432 </View>

433 )

434}

435```

436

437After adding fonts to the config plugin, run `npx expo prebuild` and rebuild the

438native app.

439

440Reference:

441[Expo Font Documentation](https://docs.expo.dev/versions/latest/sdk/font/)

442

443

444

445## Import from Design System Folder

446

447Re-export dependencies from a design system folder. App code imports from there,

448not directly from packages. This enables global changes and easy refactoring.

449

450**Incorrect (imports directly from package):**

451

452```tsx

453import { View, Text } from 'react-native'

454import { Button } from '@ui/button'

455

456function Profile() {

457 return (

458 <View>

459 <Text>Hello</Text>

460 <Button>Save</Button>

461 </View>

462 )

463}

464```

465

466**Correct (imports from design system):**

467

468```tsx

469// components/view.tsx

470import { View as RNView } from 'react-native'

471

472// ideal: pick the props you will actually use to control implementation

473export function View(

474 props: Pick<React.ComponentProps<typeof RNView>, 'style' | 'children'>

475) {

476 return <RNView {...props} />

477}

478```

479

480```tsx

481// components/text.tsx

482export { Text } from 'react-native'

483```

484

485```tsx

486// components/button.tsx

487export { Button } from '@ui/button'

488```

489

490```tsx

491import { View } from '@/components/view'

492import { Text } from '@/components/text'

493import { Button } from '@/components/button'

494

495function Profile() {

496 return (

497 <View>

498 <Text>Hello</Text>

499 <Button>Save</Button>

500 </View>

501 )

502}

503```

504

505Start by simply re-exporting. Customize later without changing app code.

506

507

508

509## Hoist Intl Formatter Creation

510

511Don't create `Intl.DateTimeFormat`, `Intl.NumberFormat`, or

512`Intl.RelativeTimeFormat` inside render or loops. These are expensive to

513instantiate. Hoist to module scope when the locale/options are static.

514

515**Incorrect (new formatter every render):**

516

517```tsx

518function Price({ amount }: { amount: number }) {

519 const formatter = new Intl.NumberFormat('en-US', {

520 style: 'currency',

521 currency: 'USD',

522 })

523 return <Text>{formatter.format(amount)}</Text>

524}

525```

526

527**Correct (hoisted to module scope):**

528

529```tsx

530const currencyFormatter = new Intl.NumberFormat('en-US', {

531 style: 'currency',

532 currency: 'USD',

533})

534

535function Price({ amount }: { amount: number }) {

536 return <Text>{currencyFormatter.format(amount)}</Text>

537}

538```

539

540**For dynamic locales, memoize:**

541

542```tsx

543const dateFormatter = useMemo(

544 () => new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }),

545 [locale]

546)

547```

548

549**Common formatters to hoist:**

550

551```tsx

552// Module-level formatters

553const dateFormatter = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' })

554const timeFormatter = new Intl.DateTimeFormat('en-US', { timeStyle: 'short' })

555const percentFormatter = new Intl.NumberFormat('en-US', { style: 'percent' })

556const relativeFormatter = new Intl.RelativeTimeFormat('en-US', {

557 numeric: 'auto',

558})

559```

560

561Creating `Intl` objects is significantly more expensive than `RegExp` or plain

562objects—each instantiation parses locale data and builds internal lookup tables.

563

564

565

566## List performance callbacks

567

568**Impact: HIGH (Fewer re-renders and faster lists)**

569

570When passing callback functions to list items, create a single instance of the

571callback at the root of the list. Items should then call it with a unique

572identifier.

573

574**Incorrect (creates a new callback on each render):**

575

576```typescript

577return (

578 <LegendList

579 renderItem={({ item }) => {

580 // bad: creates a new callback on each render

581 const onPress = () => handlePress(item.id)

582 return <Item key={item.id} item={item} onPress={onPress} />

583 }}

584 />

585)

586```

587

588**Correct (a single function instance passed to each item):**

589

590```typescript

591const onPress = useCallback(() => handlePress(item.id), [handlePress, item.id])

592

593return (

594 <LegendList

595 renderItem={({ item }) => (

596 <Item key={item.id} item={item} onPress={onPress} />

597 )}

598 />

599)

600```

601

602Reference: [Link to documentation or resource](https://example.com)

603

604

605

606## Optimize List Performance with Stable Object References

607

608Don't map or filter data before passing to virtualized lists. Virtualization

609relies on object reference stability to know what changed—new references cause

610full re-renders of all visible items. Attempt to prevent frequent renders at the

611list-parent level.

612

613Where needed, use context selectors within list items.

614

615**Incorrect (creates new object references on every keystroke):**

616

617```tsx

618function DomainSearch() {

619 const { keyword, setKeyword } = useKeywordZustandState()

620 const { data: tlds } = useTlds()

621

622 // Bad: creates new objects on every render, reparenting the entire list on every keystroke

623 const domains = tlds.map((tld) => ({

624 domain: `${keyword}.${tld.name}`,

625 tld: tld.name,

626 price: tld.price,

627 }))

628

629 return (

630 <>

631 <TextInput value={keyword} onChangeText={setKeyword} />

632 <LegendList

633 data={domains}

634 renderItem={({ item }) => <DomainItem item={item} keyword={keyword} />}

635 />

636 </>

637 )

638}

639```

640

641**Correct (stable references, transform inside items):**

642

643```tsx

644const renderItem = ({ item }) => <DomainItem tld={item} />

645

646function DomainSearch() {

647 const { data: tlds } = useTlds()

648

649 return (

650 <LegendList

651 // good: as long as the data is stable, LegendList will not re-render the entire list

652 data={tlds}

653 renderItem={renderItem}

654 />

655 )

656}

657

658function DomainItem({ tld }: { tld: Tld }) {

659 // good: transform within items, and don't pass the dynamic data as a prop

660 // good: use a selector function from zustand to receive a stable string back

661 const domain = useKeywordZustandState((s) => s.keyword + '.' + tld.name)

662 return <Text>{domain}</Text>

663}

664```

665

666**Updating parent array reference:**

667

668Creating a new array instance can be okay, as long as its inner object

669references are stable. For instance, if you sort a list of objects:

670

671```tsx

672// good: creates a new array instance without mutating the inner objects

673// good: parent array reference is unaffected by typing and updating "keyword"

674const sortedTlds = tlds.toSorted((a, b) => a.name.localeCompare(b.name))

675

676return <LegendList data={sortedTlds} renderItem={renderItem} />

677```

678

679Even though this creates a new array instance `sortedTlds`, the inner object

680references are stable.

681

682**With zustand for dynamic data (avoids parent re-renders):**

683

684```tsx

685const useSearchStore = create<{ keyword: string }>(() => ({ keyword: '' }))

686

687function DomainSearch() {

688 const { data: tlds } = useTlds()

689

690 return (

691 <>

692 <SearchInput />

693 <LegendList

694 data={tlds}

695 // if you aren't using React Compiler, wrap renderItem with useCallback

696 renderItem={({ item }) => <DomainItem tld={item} />}

697 />

698 </>

699 )

700}

701

702function DomainItem({ tld }: { tld: Tld }) {

703 // Select only what you need—component only re-renders when keyword changes

704 const keyword = useSearchStore((s) => s.keyword)

705 const domain = `${keyword}.${tld.name}`

706 return <Text>{domain}</Text>

707}

708```

709

710Virtualization can now skip items that haven't changed when typing. Only visible

711items (~20) re-render on keystroke, rather than the parent.

712

713**Deriving state within list items based on parent data (avoids parent

714re-renders):**

715

716For components where the data is conditional based on the parent state, this

717pattern is even more important. For example, if you are checking if an item is

718favorited, toggling favorites only re-renders one component if the item itself

719is in charge of accessing the state rather than the parent:

720

721```tsx

722function DomainItemFavoriteButton({ tld }: { tld: Tld }) {

723 const isFavorited = useFavoritesStore((s) => s.favorites.has(tld.id))

724 return <TldFavoriteButton isFavorited={isFavorited} />

725}

726```

727

728Note: if you're using the React Compiler, you can read React Context values

729directly within list items. Although this is slightly slower than using a

730Zustand selector in most cases, the effect may be negligible.

731

732

733

734## Use Compressed Images in Lists

735

736Always load compressed, appropriately-sized images in lists. Full-resolution

737images consume excessive memory and cause scroll jank. Request thumbnails from

738your server or use an image CDN with resize parameters.

739

740**Incorrect (full-resolution images):**

741

742```tsx

743function ProductItem({ product }: { product: Product }) {

744 return (

745 <View>

746 {/* 4000x3000 image loaded for a 100x100 thumbnail */}

747 <Image

748 source={{ uri: product.imageUrl }}

749 style={{ width: 100, height: 100 }}

750 />

751 <Text>{product.name}</Text>

752 </View>

753 )

754}

755```

756

757**Correct (request appropriately-sized image):**

758

759```tsx

760function ProductItem({ product }: { product: Product }) {

761 // Request a 200x200 image (2x for retina)

762 const thumbnailUrl = `${product.imageUrl}?w=200&h=200&fit=cover`

763

764 return (

765 <View>

766 <Image

767 source={{ uri: thumbnailUrl }}

768 style={{ width: 100, height: 100 }}

769 contentFit='cover'

770 />

771 <Text>{product.name}</Text>

772 </View>

773 )

774}

775```

776

777Use an optimized image component with built-in caching and placeholder support,

778such as `expo-image` or `SolitoImage` (which uses `expo-image` under the hood).

779Request images at 2x the display size for retina screens.

780

781

782

783## Avoid Inline Objects in renderItem

784

785Don't create new objects inside `renderItem` to pass as props. Inline objects

786create new references on every render, breaking memoization. Pass primitive

787values directly from `item` instead.

788

789**Incorrect (inline object breaks memoization):**

790

791```tsx

792function UserList({ users }: { users: User[] }) {

793 return (

794 <LegendList

795 data={users}

796 renderItem={({ item }) => (

797 <UserRow

798 // Bad: new object on every render

799 user={{ id: item.id, name: item.name, avatar: item.avatar }}

800 />

801 )}

802 />

803 )

804}

805```

806

807**Incorrect (inline style object):**

808

809```tsx

810renderItem={({ item }) => (

811 <UserRow

812 name={item.name}

813 // Bad: new style object on every render

814 style={{ backgroundColor: item.isActive ? 'green' : 'gray' }}

815 />

816)}

817```

818

819**Correct (pass item directly or primitives):**

820

821```tsx

822function UserList({ users }: { users: User[] }) {

823 return (

824 <LegendList

825 data={users}

826 renderItem={({ item }) => (

827 // Good: pass the item directly

828 <UserRow user={item} />

829 )}

830 />

831 )

832}

833```

834

835**Correct (pass primitives, derive inside child):**

836

837```tsx

838renderItem={({ item }) => (

839 <UserRow

840 id={item.id}

841 name={item.name}

842 isActive={item.isActive}

843 />

844)}

845

846const UserRow = memo(function UserRow({ id, name, isActive }: Props) {

847 // Good: derive style inside memoized component

848 const backgroundColor = isActive ? 'green' : 'gray'

849 return <View style={[styles.row, { backgroundColor }]}>{/* ... */}</View>

850})

851```

852

853**Correct (hoist static styles in module scope):**

854

855```tsx

856const activeStyle = { backgroundColor: 'green' }

857const inactiveStyle = { backgroundColor: 'gray' }

858

859renderItem={({ item }) => (

860 <UserRow

861 name={item.name}

862 // Good: stable references

863 style={item.isActive ? activeStyle : inactiveStyle}

864 />

865)}

866```

867

868Passing primitives or stable references allows `memo()` to skip re-renders when

869the actual values haven't changed.

870

871**Note:** If you have the React Compiler enabled, it handles memoization

872automatically and these manual optimizations become less critical.

873

874

875

876## Keep List Items Lightweight

877

878List items should be as inexpensive as possible to render. Minimize hooks, avoid

879queries, and limit React Context access. Virtualized lists render many items

880during scroll—expensive items cause jank.

881

882**Incorrect (heavy list item):**

883

884```tsx

885function ProductRow({ id }: { id: string }) {

886 // Bad: query inside list item

887 const { data: product } = useQuery(['product', id], () => fetchProduct(id))

888 // Bad: multiple context accesses

889 const theme = useContext(ThemeContext)

890 const user = useContext(UserContext)

891 const cart = useContext(CartContext)

892 // Bad: expensive computation

893 const recommendations = useMemo(

894 () => computeRecommendations(product),

895 [product]

896 )

897

898 return <View>{/* ... */}</View>

899}

900```

901

902**Correct (lightweight list item):**

903

904```tsx

905function ProductRow({ name, price, imageUrl }: Props) {

906 // Good: receives only primitives, minimal hooks

907 return (

908 <View>

909 <Image source={{ uri: imageUrl }} />

910 <Text>{name}</Text>

911 <Text>{price}</Text>

912 </View>

913 )

914}

915```

916

917**Move data fetching to parent:**

918

919```tsx

920// Parent fetches all data once

921function ProductList() {

922 const { data: products } = useQuery(['products'], fetchProducts)

923

924 return (

925 <LegendList

926 data={products}

927 renderItem={({ item }) => (

928 <ProductRow name={item.name} price={item.price} imageUrl={item.image} />

929 )}

930 />

931 )

932}

933```

934

935**For shared values, use Zustand selectors instead of Context:**

936

937```tsx

938// Incorrect: Context causes re-render when any cart value changes

939function ProductRow({ id, name }: Props) {

940 const { items } = useContext(CartContext)

941 const inCart = items.includes(id)

942 // ...

943}

944

945// Correct: Zustand selector only re-renders when this specific value changes

946function ProductRow({ id, name }: Props) {

947 // use Set.has (created once at the root) instead of Array.includes()

948 const inCart = useCartStore((s) => s.items.has(id))

949 // ...

950}

951```

952

953**Guidelines for list items:**

954

955- No queries or data fetching

956- No expensive computations (move to parent or memoize at parent level)

957- Prefer Zustand selectors over React Context

958- Minimize useState/useEffect hooks

959- Pass pre-computed values as props

960

961The goal: list items should be simple rendering functions that take props and

962return JSX.

963

964

965

966## Pass Primitives to List Items for Memoization

967

968When possible, pass only primitive values (strings, numbers, booleans) as props

969to list item components. Primitives enable shallow comparison in `memo()` to

970work correctly, skipping re-renders when values haven't changed.

971

972**Incorrect (object prop requires deep comparison):**

973

974```tsx

975type User = { id: string; name: string; email: string; avatar: string }

976

977const UserRow = memo(function UserRow({ user }: { user: User }) {

978 // memo() compares user by reference, not value

979 // If parent creates new user object, this re-renders even if data is same

980 return <Text>{user.name}</Text>

981})

982

983renderItem={({ item }) => <UserRow user={item} />}

984```

985

986This can still be optimized, but it is harder to memoize properly.

987

988**Correct (primitive props enable shallow comparison):**

989

990```tsx

991const UserRow = memo(function UserRow({

992 id,

993 name,

994 email,

995}: {

996 id: string

997 name: string

998 email: string

999}) {

1000 // memo() compares each primitive directly

1001 // Re-renders only if id, name, or email actually changed

1002 return <Text>{name}</Text>

1003})

1004

1005renderItem={({ item }) => (

1006 <UserRow id={item.id} name={item.name} email={item.email} />

1007)}

1008```

1009

1010**Pass only what you need:**

1011

1012```tsx

1013// Incorrect: passing entire item when you only need name

1014<UserRow user={item} />

1015

1016// Correct: pass only the fields the component uses

1017<UserRow name={item.name} avatarUrl={item.avatar} />

1018```

1019

1020**For callbacks, hoist or use item ID:**

1021

1022```tsx

1023// Incorrect: inline function creates new reference

1024<UserRow name={item.name} onPress={() => handlePress(item.id)} />

1025

1026// Correct: pass ID, handle in child

1027<UserRow id={item.id} name={item.name} />

1028

1029const UserRow = memo(function UserRow({ id, name }: Props) {

1030 const handlePress = useCallback(() => {

1031 // use id here

1032 }, [id])

1033 return <Pressable onPress={handlePress}><Text>{name}</Text></Pressable>

1034})

1035```

1036

1037Primitive props make memoization predictable and effective.

1038

1039**Note:** If you have the React Compiler enabled, you do not need to use

1040`memo()` or `useCallback()`, but the object references still apply.

1041

1042

1043

1044## Use Item Types for Heterogeneous Lists

1045

1046When a list has different item layouts (messages, images, headers, etc.), use a

1047`type` field on each item and provide `getItemType` to the list. This puts items

1048into separate recycling pools so a message component never gets recycled into an

1049image component.

1050

1051**Incorrect (single component with conditionals):**

1052

1053```tsx

1054type Item = { id: string; text?: string; imageUrl?: string; isHeader?: boolean }

1055

1056function ListItem({ item }: { item: Item }) {

1057 if (item.isHeader) {

1058 return <HeaderItem title={item.text} />

1059 }

1060 if (item.imageUrl) {

1061 return <ImageItem url={item.imageUrl} />

1062 }

1063 return <MessageItem text={item.text} />

1064}

1065

1066function Feed({ items }: { items: Item[] }) {

1067 return (

1068 <LegendList

1069 data={items}

1070 renderItem={({ item }) => <ListItem item={item} />}

1071 recycleItems

1072 />

1073 )

1074}

1075```

1076

1077**Correct (typed items with separate components):**

1078

1079```tsx

1080type HeaderItem = { id: string; type: 'header'; title: string }

1081type MessageItem = { id: string; type: 'message'; text: string }

1082type ImageItem = { id: string; type: 'image'; url: string }

1083type FeedItem = HeaderItem | MessageItem | ImageItem

1084

1085function Feed({ items }: { items: FeedItem[] }) {

1086 return (

1087 <LegendList

1088 data={items}

1089 keyExtractor={(item) => item.id}

1090 getItemType={(item) => item.type}

1091 renderItem={({ item }) => {

1092 switch (item.type) {

1093 case 'header':

1094 return <SectionHeader title={item.title} />

1095 case 'message':

1096 return <MessageRow text={item.text} />

1097 case 'image':

1098 return <ImageRow url={item.url} />

1099 }

1100 }}

1101 recycleItems

1102 />

1103 )

1104}

1105```

1106

1107**Why this matters:**

1108

1109- **Recycling efficiency**: Items with the same type share a recycling pool

1110- **No layout thrashing**: A header never recycles into an image cell

1111- **Type safety**: TypeScript can narrow the item type in each branch

1112- **Better size estimation**: Use `getEstimatedItemSize` with `itemType` for

1113 accurate estimates per type

1114

1115```tsx

1116<LegendList

1117 data={items}

1118 keyExtractor={(item) => item.id}

1119 getItemType={(item) => item.type}

1120 getEstimatedItemSize={(index, item, itemType) => {

1121 switch (itemType) {

1122 case 'header':

1123 return 48

1124 case 'message':

1125 return 72

1126 case 'image':

1127 return 300

1128 default:

1129 return 72

1130 }

1131 }}

1132 renderItem={({ item }) => {

1133 /* ... */

1134 }}

1135 recycleItems

1136/>

1137```

1138

1139Reference:

1140[LegendList getItemType](https://legendapp.com/open-source/list/api/props/#getitemtype-v2)

1141

1142

1143

1144## Use a List Virtualizer for Any List

1145

1146Use a list virtualizer like LegendList or FlashList instead of ScrollView with

1147mapped children—even for short lists. Virtualizers only render visible items,

1148reducing memory usage and mount time. ScrollView renders all children upfront,

1149which gets expensive quickly.

1150

1151**Incorrect (ScrollView renders all items at once):**

1152

1153```tsx

1154function Feed({ items }: { items: Item[] }) {

1155 return (

1156 <ScrollView>

1157 {items.map((item) => (

1158 <ItemCard key={item.id} item={item} />

1159 ))}

1160 </ScrollView>

1161 )

1162}

1163// 50 items = 50 components mounted, even if only 10 visible

1164```

1165

1166**Correct (virtualizer renders only visible items):**

1167

1168```tsx

1169import { LegendList } from '@legendapp/list'

1170

1171function Feed({ items }: { items: Item[] }) {

1172 return (

1173 <LegendList

1174 data={items}

1175 // if you aren't using React Compiler, wrap these with useCallback

1176 renderItem={({ item }) => <ItemCard item={item} />}

1177 keyExtractor={(item) => item.id}

1178 estimatedItemSize={80}

1179 />

1180 )

1181}

1182// Only ~10-15 visible items mounted at a time

1183```

1184

1185**Alternative (FlashList):**

1186

1187```tsx

1188import { FlashList } from '@shopify/flash-list'

1189

1190function Feed({ items }: { items: Item[] }) {

1191 return (

1192 <FlashList

1193 data={items}

1194 // if you aren't using React Compiler, wrap these with useCallback

1195 renderItem={({ item }) => <ItemCard item={item} />}

1196 keyExtractor={(item) => item.id}

1197 />

1198 )

1199}

1200```

1201

1202Benefits apply to any screen with scrollable content—profiles, settings, feeds,

1203search results. Default to virtualization.

1204

1205

1206

1207## Install Native Dependencies in App Directory

1208

1209In a monorepo, packages with native code must be installed in the native app's

1210directory directly. Autolinking only scans the app's `node_modules`—it won't

1211find native dependencies installed in other packages.

1212

1213**Incorrect (native dep in shared package only):**

1214

1215```

1216packages/

1217 ui/

1218 package.json # has react-native-reanimated

1219 app/

1220 package.json # missing react-native-reanimated

1221```

1222

1223Autolinking fails—native code not linked.

1224

1225**Correct (native dep in app directory):**

1226

1227```

1228packages/

1229 ui/

1230 package.json # has react-native-reanimated

1231 app/

1232 package.json # also has react-native-reanimated

1233```

1234

1235```json

1236// packages/app/package.json

1237{

1238 "dependencies": {

1239 "react-native-reanimated": "3.16.1"

1240 }

1241}

1242```

1243

1244Even if the shared package uses the native dependency, the app must also list it

1245for autolinking to detect and link the native code.

1246

1247

1248

1249## Use Single Dependency Versions Across Monorepo

1250

1251Use a single version of each dependency across all packages in your monorepo.

1252Prefer exact versions over ranges. Multiple versions cause duplicate code in

1253bundles, runtime conflicts, and inconsistent behavior across packages.

1254

1255Use a tool like syncpack to enforce this. As a last resort, use yarn resolutions

1256or npm overrides.

1257

1258**Incorrect (version ranges, multiple versions):**

1259

1260```json

1261// packages/app/package.json

1262{

1263 "dependencies": {

1264 "react-native-reanimated": "^3.0.0"

1265 }

1266}

1267

1268// packages/ui/package.json

1269{

1270 "dependencies": {

1271 "react-native-reanimated": "^3.5.0"

1272 }

1273}

1274```

1275

1276**Correct (exact versions, single source of truth):**

1277

1278```json

1279// package.json (root)

1280{

1281 "pnpm": {

1282 "overrides": {

1283 "react-native-reanimated": "3.16.1"

1284 }

1285 }

1286}

1287

1288// packages/app/package.json

1289{

1290 "dependencies": {

1291 "react-native-reanimated": "3.16.1"

1292 }

1293}

1294

1295// packages/ui/package.json

1296{

1297 "dependencies": {

1298 "react-native-reanimated": "3.16.1"

1299 }

1300}

1301```

1302

1303Use your package manager's override/resolution feature to enforce versions at

1304the root. When adding dependencies, specify exact versions without `^` or `~`.

1305

1306

1307

1308## Use Native Navigators for Navigation

1309

1310Always use native navigators instead of JS-based ones. Native navigators use

1311platform APIs (UINavigationController on iOS, Fragment on Android) for better

1312performance and native behavior.

1313

1314**For stacks:** Use `@react-navigation/native-stack` or expo-router's default

1315stack (which uses native-stack). Avoid `@react-navigation/stack`.

1316

1317**For tabs:** Use `react-native-bottom-tabs` (native) or expo-router's native

1318tabs. Avoid `@react-navigation/bottom-tabs` when native feel matters.

1319

1320### Stack Navigation

1321

1322**Incorrect (JS stack navigator):**

1323

1324```tsx

1325import { createStackNavigator } from '@react-navigation/stack'

1326

1327const Stack = createStackNavigator()

1328

1329function App() {

1330 return (

1331 <Stack.Navigator>

1332 <Stack.Screen name='Home' component={HomeScreen} />

1333 <Stack.Screen name='Details' component={DetailsScreen} />

1334 </Stack.Navigator>

1335 )

1336}

1337```

1338

1339**Correct (native stack with react-navigation):**

1340

1341```tsx

1342import { createNativeStackNavigator } from '@react-navigation/native-stack'

1343

1344const Stack = createNativeStackNavigator()

1345

1346function App() {

1347 return (

1348 <Stack.Navigator>

1349 <Stack.Screen name='Home' component={HomeScreen} />

1350 <Stack.Screen name='Details' component={DetailsScreen} />

1351 </Stack.Navigator>

1352 )

1353}

1354```

1355

1356**Correct (expo-router uses native stack by default):**

1357

1358```tsx

1359// app/_layout.tsx

1360import { Stack } from 'expo-router'

1361

1362export default function Layout() {

1363 return <Stack />

1364}

1365```

1366

1367### Tab Navigation

1368

1369**Incorrect (JS bottom tabs):**

1370

1371```tsx

1372import { createBottomTabNavigator } from '@react-navigation/bottom-tabs'

1373

1374const Tab = createBottomTabNavigator()

1375

1376function App() {

1377 return (

1378 <Tab.Navigator>

1379 <Tab.Screen name='Home' component={HomeScreen} />

1380 <Tab.Screen name='Settings' component={SettingsScreen} />

1381 </Tab.Navigator>

1382 )

1383}

1384```

1385

1386**Correct (native bottom tabs with react-navigation):**

1387

1388```tsx

1389import { createNativeBottomTabNavigator } from '@bottom-tabs/react-navigation'

1390

1391const Tab = createNativeBottomTabNavigator()

1392

1393function App() {

1394 return (

1395 <Tab.Navigator>

1396 <Tab.Screen

1397 name='Home'

1398 component={HomeScreen}

1399 options={{

1400 tabBarIcon: () => ({ sfSymbol: 'house' }),

1401 }}

1402 />

1403 <Tab.Screen

1404 name='Settings'

1405 component={SettingsScreen}

1406 options={{

1407 tabBarIcon: () => ({ sfSymbol: 'gear' }),

1408 }}

1409 />

1410 </Tab.Navigator>

1411 )

1412}

1413```

1414

1415**Correct (expo-router native tabs):**

1416

1417```tsx

1418// app/(tabs)/_layout.tsx

1419import { NativeTabs } from 'expo-router/unstable-native-tabs'

1420

1421export default function TabLayout() {

1422 return (

1423 <NativeTabs>

1424 <NativeTabs.Trigger name='index'>

1425 <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>

1426 <NativeTabs.Trigger.Icon sf='house.fill' md='home' />

1427 </NativeTabs.Trigger>

1428 <NativeTabs.Trigger name='settings'>

1429 <NativeTabs.Trigger.Label>Settings</NativeTabs.Trigger.Label>

1430 <NativeTabs.Trigger.Icon sf='gear' md='settings' />

1431 </NativeTabs.Trigger>

1432 </NativeTabs>

1433 )

1434}

1435```

1436

1437On iOS, native tabs automatically enable `contentInsetAdjustmentBehavior` on the

1438first `ScrollView` at the root of each tab screen, so content scrolls correctly

1439behind the translucent tab bar. If you need to disable this, use

1440`disableAutomaticContentInsets` on the trigger.

1441

1442### Prefer Native Header Options Over Custom Components

1443

1444**Incorrect (custom header component):**

1445

1446```tsx

1447<Stack.Screen

1448 name='Profile'

1449 component={ProfileScreen}

1450 options={{

1451 header: () => <CustomHeader title='Profile' />,

1452 }}

1453/>

1454```

1455

1456**Correct (native header options):**

1457

1458```tsx

1459<Stack.Screen

1460 name='Profile'

1461 component={ProfileScreen}

1462 options={{

1463 title: 'Profile',

1464 headerLargeTitleEnabled: true,

1465 headerSearchBarOptions: {

1466 placeholder: 'Search',

1467 },

1468 }}

1469/>

1470```

1471

1472Native headers support iOS large titles, search bars, blur effects, and proper

1473safe area handling automatically.

1474

1475### Why Native Navigators

1476

1477- **Performance**: Native transitions and gestures run on the UI thread

1478- **Platform behavior**: Automatic iOS large titles, Android material design

1479- **System integration**: Scroll-to-top on tab tap, PiP avoidance, proper safe

1480 areas

1481- **Accessibility**: Platform accessibility features work automatically

1482

1483Reference:

1484

1485- [React Navigation Native Stack](https://reactnavigation.org/docs/native-stack-navigator)

1486- [React Native Bottom Tabs with React Navigation](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-react-navigation)

1487- [React Native Bottom Tabs with Expo Router](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-expo-router)

1488- [Expo Router Native Tabs](https://docs.expo.dev/router/advanced/native-tabs)

1489

1490

1491

1492## Destructure Functions Early in Render

1493

1494This rule is only applicable if you are using the React Compiler.

1495

1496Destructure functions from hooks at the top of render scope. Never dot into

1497objects to call functions. Destructured functions are stable references; dotting

1498creates new references and breaks memoization.

1499

1500**Incorrect (dotting into object):**

1501

1502```tsx

1503import { useRouter } from 'expo-router'

1504

1505function SaveButton(props) {

1506 const router = useRouter()

1507

1508 // bad: react-compiler will key the cache on "props" and "router", which are objects that change each render

1509 const handlePress = () => {

1510 props.onSave()

1511 router.push('/success') // unstable reference

1512 }

1513

1514 return <Button onPress={handlePress}>Save</Button>

1515}

1516```

1517

1518**Correct (destructure early):**

1519

1520```tsx

1521import { useRouter } from 'expo-router'

1522

1523function SaveButton({ onSave }) {

1524 const { push } = useRouter()

1525

1526 // good: react-compiler will key on push and onSave

1527 const handlePress = () => {

1528 onSave()

1529 push('/success') // stable reference

1530 }

1531

1532 return <Button onPress={handlePress}>Save</Button>

1533}

1534```

1535

1536

1537

1538## Use .get() and .set() for Shared Values with React Compiler

1539

1540With React Compiler enabled, use `.get()` and `.set()` instead of reading or

1541writing `.value` directly on Reanimated shared values. The compiler can't track

1542property access—explicit methods ensure correct behavior.

1543

1544**Incorrect (breaks with React Compiler):**

1545

1546```tsx

1547import { useSharedValue } from 'react-native-reanimated'

1548

1549function Counter() {

1550 const count = useSharedValue(0)

1551

1552 const increment = () => {

1553 count.value = count.value + 1 // opts out of react compiler

1554 }

1555

1556 return <Button onPress={increment} title={`Count: ${count.value}`} />

1557}

1558```

1559

1560**Correct (React Compiler compatible):**

1561

1562```tsx

1563import { useSharedValue } from 'react-native-reanimated'

1564

1565function Counter() {

1566 const count = useSharedValue(0)

1567

1568 const increment = () => {

1569 count.set(count.get() + 1)

1570 }

1571

1572 return <Button onPress={increment} title={`Count: ${count.get()}`} />

1573}

1574```

1575

1576See the

1577[Reanimated docs](https://docs.swmansion.com/react-native-reanimated/docs/core/useSharedValue/#react-compiler-support)

1578for more.

1579

1580

1581

1582## Use Dispatch Updaters for State That Depends on Current Value

1583

1584When the next state depends on the current state, use a dispatch updater

1585(`setState(prev => ...)`) instead of reading the state variable directly in a

1586callback. This avoids stale closures and ensures you're comparing against the

1587latest value.

1588

1589**Incorrect (reads state directly):**

1590

1591```tsx

1592const [size, setSize] = useState<Size | undefined>(undefined)

1593

1594const onLayout = (e: LayoutChangeEvent) => {

1595 const { width, height } = e.nativeEvent.layout

1596 // size may be stale in this closure

1597 if (size?.width !== width || size?.height !== height) {

1598 setSize({ width, height })

1599 }

1600}

1601```

1602

1603**Correct (dispatch updater):**

1604

1605```tsx

1606const [size, setSize] = useState<Size | undefined>(undefined)

1607

1608const onLayout = (e: LayoutChangeEvent) => {

1609 const { width, height } = e.nativeEvent.layout

1610 setSize((prev) => {

1611 if (prev?.width === width && prev?.height === height) return prev

1612 return { width, height }

1613 })

1614}

1615```

1616

1617Returning the previous value from the updater skips the re-render.

1618

1619For primitive states, you don't need to compare values before firing a

1620re-render.

1621

1622**Incorrect (unnecessary comparison for primitive state):**

1623

1624```tsx

1625const [size, setSize] = useState<Size | undefined>(undefined)

1626

1627const onLayout = (e: LayoutChangeEvent) => {

1628 const { width, height } = e.nativeEvent.layout

1629 setSize((prev) => (prev === width ? prev : width))

1630}

1631```

1632

1633**Correct (sets primitive state directly):**

1634

1635```tsx

1636const [size, setSize] = useState<Size | undefined>(undefined)

1637

1638const onLayout = (e: LayoutChangeEvent) => {

1639 const { width, height } = e.nativeEvent.layout

1640 setSize(width)

1641}

1642```

1643

1644However, if the next state depends on the current state, you should still use a

1645dispatch updater.

1646

1647**Incorrect (reads state directly from the callback):**

1648

1649```tsx

1650const [count, setCount] = useState(0)

1651

1652const onTap = () => {

1653 setCount(count + 1)

1654}

1655```

1656

1657**Correct (dispatch updater):**

1658

1659```tsx

1660const [count, setCount] = useState(0)

1661

1662const onTap = () => {

1663 setCount((prev) => prev + 1)

1664}

1665```

1666

1667

1668

1669## Use fallback state instead of initialState

1670

1671Use `undefined` as initial state and nullish coalescing (`??`) to fall back to

1672parent or server values. State represents user intent only—`undefined` means

1673"user hasn't chosen yet." This enables reactive fallbacks that update when the

1674source changes, not just on initial render.

1675

1676**Incorrect (syncs state, loses reactivity):**

1677

1678```tsx

1679type Props = { fallbackEnabled: boolean }

1680

1681function Toggle({ fallbackEnabled }: Props) {

1682 const [enabled, setEnabled] = useState(defaultEnabled)

1683 // If fallbackEnabled changes, state is stale

1684 // State mixes user intent with default value

1685

1686 return <Switch value={enabled} onValueChange={setEnabled} />

1687}

1688```

1689

1690**Correct (state is user intent, reactive fallback):**

1691

1692```tsx

1693type Props = { fallbackEnabled: boolean }

1694

1695function Toggle({ fallbackEnabled }: Props) {

1696 const [_enabled, setEnabled] = useState<boolean | undefined>(undefined)

1697 const enabled = _enabled ?? defaultEnabled

1698 // undefined = user hasn't touched it, falls back to prop

1699 // If defaultEnabled changes, component reflects it

1700 // Once user interacts, their choice persists

1701

1702 return <Switch value={enabled} onValueChange={setEnabled} />

1703}

1704```

1705

1706**With server data:**

1707

1708```tsx

1709function ProfileForm({ data }: { data: User }) {

1710 const [_theme, setTheme] = useState<string | undefined>(undefined)

1711 const theme = _theme ?? data.theme

1712 // Shows server value until user overrides

1713 // Server refetch updates the fallback automatically

1714

1715 return <ThemePicker value={theme} onChange={setTheme} />

1716}

1717```

1718

1719

1720

1721## Minimize State Variables and Derive Values

1722

1723Use the fewest state variables possible. If a value can be computed from existing state or props, derive it during render instead of storing it in state. Redundant state causes unnecessary re-renders and can drift out of sync.

1724

1725**Incorrect (redundant state):**

1726

1727```tsx

1728function Cart({ items }: { items: Item[] }) {

1729 const [total, setTotal] = useState(0)

1730 const [itemCount, setItemCount] = useState(0)

1731

1732 useEffect(() => {

1733 setTotal(items.reduce((sum, item) => sum + item.price, 0))

1734 setItemCount(items.length)

1735 }, [items])

1736

1737 return (

1738 <View>

1739 <Text>{itemCount} items</Text>

1740 <Text>Total: ${total}</Text>

1741 </View>

1742 )

1743}

1744```

1745

1746**Correct (derived values):**

1747

1748```tsx

1749function Cart({ items }: { items: Item[] }) {

1750 const total = items.reduce((sum, item) => sum + item.price, 0)

1751 const itemCount = items.length

1752

1753 return (

1754 <View>

1755 <Text>{itemCount} items</Text>

1756 <Text>Total: ${total}</Text>

1757 </View>

1758 )

1759}

1760```

1761

1762**Another example:**

1763

1764```tsx

1765// Incorrect: storing both firstName, lastName, AND fullName

1766const [firstName, setFirstName] = useState('')

1767const [lastName, setLastName] = useState('')

1768const [fullName, setFullName] = useState('')

1769

1770// Correct: derive fullName

1771const [firstName, setFirstName] = useState('')

1772const [lastName, setLastName] = useState('')

1773const fullName = `${firstName} ${lastName}`

1774```

1775

1776State should be the minimal source of truth. Everything else is derived.

1777

1778Reference: [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure)

1779

1780

1781

1782## Never Use && with Potentially Falsy Values

1783

1784Never use `{value && <Component />}` when `value` could be an empty string or

1785`0`. These are falsy but JSX-renderable—React Native will try to render them as

1786text outside a `<Text>` component, causing a hard crash in production.

1787

1788**Incorrect (crashes if count is 0 or name is ""):**

1789

1790```tsx

1791function Profile({ name, count }: { name: string; count: number }) {

1792 return (

1793 <View>

1794 {name && <Text>{name}</Text>}

1795 {count && <Text>{count} items</Text>}

1796 </View>

1797 )

1798}

1799// If name="" or count=0, renders the falsy value → crash

1800```

1801

1802**Correct (ternary with null):**

1803

1804```tsx

1805function Profile({ name, count }: { name: string; count: number }) {

1806 return (

1807 <View>

1808 {name ? <Text>{name}</Text> : null}

1809 {count ? <Text>{count} items</Text> : null}

1810 </View>

1811 )

1812}

1813```

1814

1815**Correct (explicit boolean coercion):**

1816

1817```tsx

1818function Profile({ name, count }: { name: string; count: number }) {

1819 return (

1820 <View>

1821 {!!name && <Text>{name}</Text>}

1822 {!!count && <Text>{count} items</Text>}

1823 </View>

1824 )

1825}

1826```

1827

1828**Best (early return):**

1829

1830```tsx

1831function Profile({ name, count }: { name: string; count: number }) {

1832 if (!name) return null

1833

1834 return (

1835 <View>

1836 <Text>{name}</Text>

1837 {count > 0 ? <Text>{count} items</Text> : null}

1838 </View>

1839 )

1840}

1841```

1842

1843Early returns are clearest. When using conditionals inline, prefer ternary or

1844explicit boolean checks.

1845

1846**Lint rule:** Enable `react/jsx-no-leaked-render` from

1847[eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-no-leaked-render.md)

1848to catch this automatically.

1849

1850

1851

1852## Wrap Strings in Text Components

1853

1854Strings must be rendered inside `<Text>`. React Native crashes if a string is a

1855direct child of `<View>`.

1856

1857**Incorrect (crashes):**

1858

1859```tsx

1860import { View } from 'react-native'

1861

1862function Greeting({ name }: { name: string }) {

1863 return <View>Hello, {name}!</View>

1864}

1865// Error: Text strings must be rendered within a <Text> component.

1866```

1867

1868**Correct:**

1869

1870```tsx

1871import { View, Text } from 'react-native'

1872

1873function Greeting({ name }: { name: string }) {

1874 return (

1875 <View>

1876 <Text>Hello, {name}!</Text>

1877 </View>

1878 )

1879}

1880```

1881

1882

1883

1884## Never Track Scroll Position in useState

1885

1886Never store scroll position in `useState`. Scroll events fire rapidly—state

1887updates cause render thrashing and dropped frames. Use a Reanimated shared value

1888for animations or a ref for non-reactive tracking.

1889

1890**Incorrect (useState causes jank):**

1891

1892```tsx

1893import { useState } from 'react'

1894import {

1895 ScrollView,

1896 NativeSyntheticEvent,

1897 NativeScrollEvent,

1898} from 'react-native'

1899

1900function Feed() {

1901 const [scrollY, setScrollY] = useState(0)

1902

1903 const onScroll = (e: NativeSyntheticEvent<NativeScrollEvent>) => {

1904 setScrollY(e.nativeEvent.contentOffset.y) // re-renders on every frame

1905 }

1906

1907 return <ScrollView onScroll={onScroll} scrollEventThrottle={16} />

1908}

1909```

1910

1911**Correct (Reanimated for animations):**

1912

1913```tsx

1914import Animated, {

1915 useSharedValue,

1916 useAnimatedScrollHandler,

1917} from 'react-native-reanimated'

1918

1919function Feed() {

1920 const scrollY = useSharedValue(0)

1921

1922 const onScroll = useAnimatedScrollHandler({

1923 onScroll: (e) => {

1924 scrollY.value = e.contentOffset.y // runs on UI thread, no re-render

1925 },

1926 })

1927

1928 return (

1929 <Animated.ScrollView

1930 onScroll={onScroll}

1931 // higher number has better performance, but it fires less often.

1932 // unset this if you need higher precision over performance.

1933 scrollEventThrottle={16}

1934 />

1935 )

1936}

1937```

1938

1939**Correct (ref for non-reactive tracking):**

1940

1941```tsx

1942import { useRef } from 'react'

1943import {

1944 ScrollView,

1945 NativeSyntheticEvent,

1946 NativeScrollEvent,

1947} from 'react-native'

1948

1949function Feed() {

1950 const scrollY = useRef(0)

1951

1952 const onScroll = (e: NativeSyntheticEvent<NativeScrollEvent>) => {

1953 scrollY.current = e.nativeEvent.contentOffset.y // no re-render

1954 }

1955

1956 return <ScrollView onScroll={onScroll} scrollEventThrottle={16} />

1957}

1958```

1959

1960

1961

1962## State Must Represent Ground Truth

1963

1964State variables—both React `useState` and Reanimated shared values—should

1965represent the actual state of something (e.g., `pressed`, `progress`, `isOpen`),

1966not derived visual values (e.g., `scale`, `opacity`, `translateY`). Derive

1967visual values from state using computation or interpolation.

1968

1969**Incorrect (storing the visual output):**

1970

1971```tsx

1972const scale = useSharedValue(1)

1973

1974const tap = Gesture.Tap()

1975 .onBegin(() => {

1976 scale.set(withTiming(0.95))

1977 })

1978 .onFinalize(() => {

1979 scale.set(withTiming(1))

1980 })

1981

1982const animatedStyle = useAnimatedStyle(() => ({

1983 transform: [{ scale: scale.get() }],

1984}))

1985```

1986

1987**Correct (storing the state, deriving the visual):**

1988

1989```tsx

1990const pressed = useSharedValue(0) // 0 = not pressed, 1 = pressed

1991

1992const tap = Gesture.Tap()

1993 .onBegin(() => {

1994 pressed.set(withTiming(1))

1995 })

1996 .onFinalize(() => {

1997 pressed.set(withTiming(0))

1998 })

1999

2000const animatedStyle = useAnimatedStyle(() => ({

2001 transform: [{ scale: interpolate(pressed.get(), [0, 1], [1, 0.95]) }],

2002}))

2003```

2004

2005**Why this matters:**

2006

2007State variables should represent real "state", not necessarily a desired end

2008result.

2009

20101. **Single source of truth** — The state (`pressed`) describes what's

2011 happening; visuals are derived

20122. **Easier to extend** — Adding opacity, rotation, or other effects just

2013 requires more interpolations from the same state

20143. **Debugging** — Inspecting `pressed = 1` is clearer than `scale = 0.95`

20154. **Reusable logic** — The same `pressed` value can drive multiple visual

2016 properties

2017

2018**Same principle for React state:**

2019

2020```tsx

2021// Incorrect: storing derived values

2022const [isExpanded, setIsExpanded] = useState(false)

2023const [height, setHeight] = useState(0)

2024

2025useEffect(() => {

2026 setHeight(isExpanded ? 200 : 0)

2027}, [isExpanded])

2028

2029// Correct: derive from state

2030const [isExpanded, setIsExpanded] = useState(false)

2031const height = isExpanded ? 200 : 0

2032```

2033

2034State is the minimal truth. Everything else is derived.

2035

2036

2037

2038## Use expo-image for Optimized Images

2039

2040Use `expo-image` instead of React Native's `Image`. It provides memory-efficient caching, blurhash placeholders, progressive loading, and better performance for lists.

2041

2042**Incorrect (React Native Image):**

2043

2044```tsx

2045import { Image } from 'react-native'

2046

2047function Avatar({ url }: { url: string }) {

2048 return <Image source={{ uri: url }} style={styles.avatar} />

2049}

2050```

2051

2052**Correct (expo-image):**

2053

2054```tsx

2055import { Image } from 'expo-image'

2056

2057function Avatar({ url }: { url: string }) {

2058 return <Image source={{ uri: url }} style={styles.avatar} />

2059}

2060```

2061

2062**With blurhash placeholder:**

2063

2064```tsx

2065<Image

2066 source={{ uri: url }}

2067 placeholder={{ blurhash: 'LGF5]+Yk^6#M@-5c,1J5@[or[Q6.' }}

2068 contentFit="cover"

2069 transition={200}

2070 style={styles.image}

2071/>

2072```

2073

2074**With priority and caching:**

2075

2076```tsx

2077<Image

2078 source={{ uri: url }}

2079 priority="high"

2080 cachePolicy="memory-disk"

2081 style={styles.hero}

2082/>

2083```

2084

2085**Key props:**

2086

2087- `placeholder` — Blurhash or thumbnail while loading

2088- `contentFit` — `cover`, `contain`, `fill`, `scale-down`

2089- `transition` — Fade-in duration (ms)

2090- `priority` — `low`, `normal`, `high`

2091- `cachePolicy` — `memory`, `disk`, `memory-disk`, `none`

2092- `recyclingKey` — Unique key for list recycling

2093

2094For cross-platform (web + native), use `SolitoImage` from `solito/image` which uses `expo-image` under the hood.

2095

2096Reference: [expo-image](https://docs.expo.dev/versions/latest/sdk/image/)

2097

2098

2099

2100## Use Galeria for Image Galleries and Lightbox

2101

2102For image galleries with lightbox (tap to fullscreen), use `@nandorojo/galeria`.

2103It provides native shared element transitions with pinch-to-zoom, double-tap

2104zoom, and pan-to-close. Works with any image component including `expo-image`.

2105

2106**Incorrect (custom modal implementation):**

2107

2108```tsx

2109function ImageGallery({ urls }: { urls: string[] }) {

2110 const [selected, setSelected] = useState<string | null>(null)

2111

2112 return (

2113 <>

2114 {urls.map((url) => (

2115 <Pressable key={url} onPress={() => setSelected(url)}>

2116 <Image source={{ uri: url }} style={styles.thumbnail} />

2117 </Pressable>

2118 ))}

2119 <Modal visible={!!selected} onRequestClose={() => setSelected(null)}>

2120 <Image source={{ uri: selected! }} style={styles.fullscreen} />

2121 </Modal>

2122 </>

2123 )

2124}

2125```

2126

2127**Correct (Galeria with expo-image):**

2128

2129```tsx

2130import { Galeria } from '@nandorojo/galeria'

2131import { Image } from 'expo-image'

2132

2133function ImageGallery({ urls }: { urls: string[] }) {

2134 return (

2135 <Galeria urls={urls}>

2136 {urls.map((url, index) => (

2137 <Galeria.Image index={index} key={url}>

2138 <Image source={{ uri: url }} style={styles.thumbnail} />

2139 </Galeria.Image>

2140 ))}

2141 </Galeria>

2142 )

2143}

2144```

2145

2146**Single image:**

2147

2148```tsx

2149import { Galeria } from '@nandorojo/galeria'

2150import { Image } from 'expo-image'

2151

2152function Avatar({ url }: { url: string }) {

2153 return (

2154 <Galeria urls={[url]}>

2155 <Galeria.Image>

2156 <Image source={{ uri: url }} style={styles.avatar} />

2157 </Galeria.Image>

2158 </Galeria>

2159 )

2160}

2161```

2162

2163**With low-res thumbnails and high-res fullscreen:**

2164

2165```tsx

2166<Galeria urls={highResUrls}>

2167 {lowResUrls.map((url, index) => (

2168 <Galeria.Image index={index} key={url}>

2169 <Image source={{ uri: url }} style={styles.thumbnail} />

2170 </Galeria.Image>

2171 ))}

2172</Galeria>

2173```

2174

2175**With FlashList:**

2176

2177```tsx

2178<Galeria urls={urls}>

2179 <FlashList

2180 data={urls}

2181 renderItem={({ item, index }) => (

2182 <Galeria.Image index={index}>

2183 <Image source={{ uri: item }} style={styles.thumbnail} />

2184 </Galeria.Image>

2185 )}

2186 numColumns={3}

2187 estimatedItemSize={100}

2188 />

2189</Galeria>

2190```

2191

2192Works with `expo-image`, `SolitoImage`, `react-native` Image, or any image

2193component.

2194

2195Reference: [Galeria](https://github.com/nandorojo/galeria)

2196

2197

2198

2199## Measuring View Dimensions

2200

2201Use both `useLayoutEffect` (synchronous) and `onLayout` (for updates). The sync

2202measurement gives you the initial size immediately; `onLayout` keeps it current

2203when the view changes. For non-primitive states, use a dispatch updater to

2204compare values and avoid unnecessary re-renders.

2205

2206**Height only:**

2207

2208```tsx

2209import { useLayoutEffect, useRef, useState } from 'react'

2210import { View, LayoutChangeEvent } from 'react-native'

2211

2212function MeasuredBox({ children }: { children: React.ReactNode }) {

2213 const ref = useRef<View>(null)

2214 const [height, setHeight] = useState<number | undefined>(undefined)

2215

2216 useLayoutEffect(() => {

2217 // Sync measurement on mount (RN 0.82+)

2218 const rect = ref.current?.getBoundingClientRect()

2219 if (rect) setHeight(rect.height)

2220 // Pre-0.82: ref.current?.measure((x, y, w, h) => setHeight(h))

2221 }, [])

2222

2223 const onLayout = (e: LayoutChangeEvent) => {

2224 setHeight(e.nativeEvent.layout.height)

2225 }

2226

2227 return (

2228 <View ref={ref} onLayout={onLayout}>

2229 {children}

2230 </View>

2231 )

2232}

2233```

2234

2235**Both dimensions:**

2236

2237```tsx

2238import { useLayoutEffect, useRef, useState } from 'react'

2239import { View, LayoutChangeEvent } from 'react-native'

2240

2241type Size = { width: number; height: number }

2242

2243function MeasuredBox({ children }: { children: React.ReactNode }) {

2244 const ref = useRef<View>(null)

2245 const [size, setSize] = useState<Size | undefined>(undefined)

2246

2247 useLayoutEffect(() => {

2248 const rect = ref.current?.getBoundingClientRect()

2249 if (rect) setSize({ width: rect.width, height: rect.height })

2250 }, [])

2251

2252 const onLayout = (e: LayoutChangeEvent) => {

2253 const { width, height } = e.nativeEvent.layout

2254 setSize((prev) => {

2255 // for non-primitive states, compare values before firing a re-render

2256 if (prev?.width === width && prev?.height === height) return prev

2257 return { width, height }

2258 })

2259 }

2260

2261 return (

2262 <View ref={ref} onLayout={onLayout}>

2263 {children}

2264 </View>

2265 )

2266}

2267```

2268

2269Use functional setState to compare—don't read state directly in the callback.

2270

2271

2272

2273## Use Native Menus for Dropdowns and Context Menus

2274

2275Use native platform menus instead of custom JS implementations. Native menus

2276provide built-in accessibility, consistent platform UX, and better performance.

2277Use [zeego](https://zeego.dev) for cross-platform native menus.

2278

2279**Incorrect (custom JS menu):**

2280

2281```tsx

2282import { useState } from 'react'

2283import { View, Pressable, Text } from 'react-native'

2284

2285function MyMenu() {

2286 const [open, setOpen] = useState(false)

2287

2288 return (

2289 <View>

2290 <Pressable onPress={() => setOpen(!open)}>

2291 <Text>Open Menu</Text>

2292 </Pressable>

2293 {open && (

2294 <View style={{ position: 'absolute', top: 40 }}>

2295 <Pressable onPress={() => console.log('edit')}>

2296 <Text>Edit</Text>

2297 </Pressable>

2298 <Pressable onPress={() => console.log('delete')}>

2299 <Text>Delete</Text>

2300 </Pressable>

2301 </View>

2302 )}

2303 </View>

2304 )

2305}

2306```

2307

2308**Correct (native menu with zeego):**

2309

2310```tsx

2311import * as DropdownMenu from 'zeego/dropdown-menu'

2312

2313function MyMenu() {

2314 return (

2315 <DropdownMenu.Root>

2316 <DropdownMenu.Trigger>

2317 <Pressable>

2318 <Text>Open Menu</Text>

2319 </Pressable>

2320 </DropdownMenu.Trigger>

2321

2322 <DropdownMenu.Content>

2323 <DropdownMenu.Item key='edit' onSelect={() => console.log('edit')}>

2324 <DropdownMenu.ItemTitle>Edit</DropdownMenu.ItemTitle>

2325 </DropdownMenu.Item>

2326

2327 <DropdownMenu.Item

2328 key='delete'

2329 destructive

2330 onSelect={() => console.log('delete')}

2331 >

2332 <DropdownMenu.ItemTitle>Delete</DropdownMenu.ItemTitle>

2333 </DropdownMenu.Item>

2334 </DropdownMenu.Content>

2335 </DropdownMenu.Root>

2336 )

2337}

2338```

2339

2340**Context menu (long-press):**

2341

2342```tsx

2343import * as ContextMenu from 'zeego/context-menu'

2344

2345function MyContextMenu() {

2346 return (

2347 <ContextMenu.Root>

2348 <ContextMenu.Trigger>

2349 <View style={{ padding: 20 }}>

2350 <Text>Long press me</Text>

2351 </View>

2352 </ContextMenu.Trigger>

2353

2354 <ContextMenu.Content>

2355 <ContextMenu.Item key='copy' onSelect={() => console.log('copy')}>

2356 <ContextMenu.ItemTitle>Copy</ContextMenu.ItemTitle>

2357 </ContextMenu.Item>

2358

2359 <ContextMenu.Item key='paste' onSelect={() => console.log('paste')}>

2360 <ContextMenu.ItemTitle>Paste</ContextMenu.ItemTitle>

2361 </ContextMenu.Item>

2362 </ContextMenu.Content>

2363 </ContextMenu.Root>

2364 )

2365}

2366```

2367

2368**Checkbox items:**

2369

2370```tsx

2371import * as DropdownMenu from 'zeego/dropdown-menu'

2372

2373function SettingsMenu() {

2374 const [notifications, setNotifications] = useState(true)

2375

2376 return (

2377 <DropdownMenu.Root>

2378 <DropdownMenu.Trigger>

2379 <Pressable>

2380 <Text>Settings</Text>

2381 </Pressable>

2382 </DropdownMenu.Trigger>

2383

2384 <DropdownMenu.Content>

2385 <DropdownMenu.CheckboxItem

2386 key='notifications'

2387 value={notifications}

2388 onValueChange={() => setNotifications((prev) => !prev)}

2389 >

2390 <DropdownMenu.ItemIndicator />

2391 <DropdownMenu.ItemTitle>Notifications</DropdownMenu.ItemTitle>

2392 </DropdownMenu.CheckboxItem>

2393 </DropdownMenu.Content>

2394 </DropdownMenu.Root>

2395 )

2396}

2397```

2398

2399**Submenus:**

2400

2401```tsx

2402import * as DropdownMenu from 'zeego/dropdown-menu'

2403

2404function MenuWithSubmenu() {

2405 return (

2406 <DropdownMenu.Root>

2407 <DropdownMenu.Trigger>

2408 <Pressable>

2409 <Text>Options</Text>

2410 </Pressable>

2411 </DropdownMenu.Trigger>

2412

2413 <DropdownMenu.Content>

2414 <DropdownMenu.Item key='home' onSelect={() => console.log('home')}>

2415 <DropdownMenu.ItemTitle>Home</DropdownMenu.ItemTitle>

2416 </DropdownMenu.Item>

2417

2418 <DropdownMenu.Sub>

2419 <DropdownMenu.SubTrigger key='more'>

2420 <DropdownMenu.ItemTitle>More Options</DropdownMenu.ItemTitle>

2421 </DropdownMenu.SubTrigger>

2422

2423 <DropdownMenu.SubContent>

2424 <DropdownMenu.Item key='settings'>

2425 <DropdownMenu.ItemTitle>Settings</DropdownMenu.ItemTitle>

2426 </DropdownMenu.Item>

2427

2428 <DropdownMenu.Item key='help'>

2429 <DropdownMenu.ItemTitle>Help</DropdownMenu.ItemTitle>

2430 </DropdownMenu.Item>

2431 </DropdownMenu.SubContent>

2432 </DropdownMenu.Sub>

2433 </DropdownMenu.Content>

2434 </DropdownMenu.Root>

2435 )

2436}

2437```

2438

2439Reference: [Zeego Documentation](https://zeego.dev/components/dropdown-menu)

2440

2441

2442

2443## Use Native Modals Over JS-Based Bottom Sheets

2444

2445Use native `<Modal>` with `presentationStyle="formSheet"` or React Navigation

2446v7's native form sheet instead of JS-based bottom sheet libraries. Native modals

2447have built-in gestures, accessibility, and better performance. Rely on native UI

2448for low-level primitives.

2449

2450**Incorrect (JS-based bottom sheet):**

2451

2452```tsx

2453import BottomSheet from 'custom-js-bottom-sheet'

2454

2455function MyScreen() {

2456 const sheetRef = useRef<BottomSheet>(null)

2457

2458 return (

2459 <View style={{ flex: 1 }}>

2460 <Button onPress={() => sheetRef.current?.expand()} title='Open' />

2461 <BottomSheet ref={sheetRef} snapPoints={['50%', '90%']}>

2462 <View>

2463 <Text>Sheet content</Text>

2464 </View>

2465 </BottomSheet>

2466 </View>

2467 )

2468}

2469```

2470

2471**Correct (native Modal with formSheet):**

2472

2473```tsx

2474import { Modal, View, Text, Button } from 'react-native'

2475

2476function MyScreen() {

2477 const [visible, setVisible] = useState(false)

2478

2479 return (

2480 <View style={{ flex: 1 }}>

2481 <Button onPress={() => setVisible(true)} title='Open' />

2482 <Modal

2483 visible={visible}

2484 presentationStyle='formSheet'

2485 animationType='slide'

2486 onRequestClose={() => setVisible(false)}

2487 >

2488 <View>

2489 <Text>Sheet content</Text>

2490 </View>

2491 </Modal>

2492 </View>

2493 )

2494}

2495```

2496

2497**Correct (React Navigation v7 native form sheet):**

2498

2499```tsx

2500// In your navigator

2501<Stack.Screen

2502 name='Details'

2503 component={DetailsScreen}

2504 options={{

2505 presentation: 'formSheet',

2506 sheetAllowedDetents: 'fitToContents',

2507 }}

2508/>

2509```

2510

2511Native modals provide swipe-to-dismiss, proper keyboard avoidance, and

2512accessibility out of the box.

2513

2514

2515

2516## Use Pressable Instead of Touchable Components

2517

2518Never use `TouchableOpacity` or `TouchableHighlight`. Use `Pressable` from

2519`react-native` or `react-native-gesture-handler` instead.

2520

2521**Incorrect (legacy Touchable components):**

2522

2523```tsx

2524import { TouchableOpacity } from 'react-native'

2525

2526function MyButton({ onPress }: { onPress: () => void }) {

2527 return (

2528 <TouchableOpacity onPress={onPress} activeOpacity={0.7}>

2529 <Text>Press me</Text>

2530 </TouchableOpacity>

2531 )

2532}

2533```

2534

2535**Correct (Pressable):**

2536

2537```tsx

2538import { Pressable } from 'react-native'

2539

2540function MyButton({ onPress }: { onPress: () => void }) {

2541 return (

2542 <Pressable onPress={onPress}>

2543 <Text>Press me</Text>

2544 </Pressable>

2545 )

2546}

2547```

2548

2549**Correct (Pressable from gesture handler for lists):**

2550

2551```tsx

2552import { Pressable } from 'react-native-gesture-handler'

2553

2554function ListItem({ onPress }: { onPress: () => void }) {

2555 return (

2556 <Pressable onPress={onPress}>

2557 <Text>Item</Text>

2558 </Pressable>

2559 )

2560}

2561```

2562

2563Use `react-native-gesture-handler` Pressable inside scrollable lists for better

2564gesture coordination, as long as you are using the ScrollView from

2565`react-native-gesture-handler` as well.

2566

2567**For animated press states (scale, opacity changes):** Use `GestureDetector`

2568with Reanimated shared values instead of Pressable's style callback. See the

2569`animation-gesture-detector-press` rule.

2570

2571

2572

2573## Use contentInsetAdjustmentBehavior for Safe Areas

2574

2575Use `contentInsetAdjustmentBehavior="automatic"` on the root ScrollView instead of wrapping content in SafeAreaView or manual padding. This lets iOS handle safe area insets natively with proper scroll behavior.

2576

2577**Incorrect (SafeAreaView wrapper):**

2578

2579```tsx

2580import { SafeAreaView, ScrollView, View, Text } from 'react-native'

2581

2582function MyScreen() {

2583 return (

2584 <SafeAreaView style={{ flex: 1 }}>

2585 <ScrollView>

2586 <View>

2587 <Text>Content</Text>

2588 </View>

2589 </ScrollView>

2590 </SafeAreaView>

2591 )

2592}

2593```

2594

2595**Incorrect (manual safe area padding):**

2596

2597```tsx

2598import { ScrollView, View, Text } from 'react-native'

2599import { useSafeAreaInsets } from 'react-native-safe-area-context'

2600

2601function MyScreen() {

2602 const insets = useSafeAreaInsets()

2603

2604 return (

2605 <ScrollView contentContainerStyle={{ paddingTop: insets.top }}>

2606 <View>

2607 <Text>Content</Text>

2608 </View>

2609 </ScrollView>

2610 )

2611}

2612```

2613

2614**Correct (native content inset adjustment):**

2615

2616```tsx

2617import { ScrollView, View, Text } from 'react-native'

2618

2619function MyScreen() {

2620 return (

2621 <ScrollView contentInsetAdjustmentBehavior='automatic'>

2622 <View>

2623 <Text>Content</Text>

2624 </View>

2625 </ScrollView>

2626 )

2627}

2628```

2629

2630The native approach handles dynamic safe areas (keyboard, toolbars) and allows content to scroll behind the status bar naturally.

2631

2632

2633

2634## Use contentInset for Dynamic ScrollView Spacing

2635

2636When adding space to the top or bottom of a ScrollView that may change

2637(keyboard, toolbars, dynamic content), use `contentInset` instead of padding.

2638Changing `contentInset` doesn't trigger layout recalculation—it adjusts the

2639scroll area without re-rendering content.

2640

2641**Incorrect (padding causes layout recalculation):**

2642

2643```tsx

2644function Feed({ bottomOffset }: { bottomOffset: number }) {

2645 return (

2646 <ScrollView contentContainerStyle={{ paddingBottom: bottomOffset }}>

2647 {children}

2648 </ScrollView>

2649 )

2650}

2651// Changing bottomOffset triggers full layout recalculation

2652```

2653

2654**Correct (contentInset for dynamic spacing):**

2655

2656```tsx

2657function Feed({ bottomOffset }: { bottomOffset: number }) {

2658 return (

2659 <ScrollView

2660 contentInset={{ bottom: bottomOffset }}

2661 scrollIndicatorInsets={{ bottom: bottomOffset }}

2662 >

2663 {children}

2664 </ScrollView>

2665 )

2666}

2667// Changing bottomOffset only adjusts scroll bounds

2668```

2669

2670Use `scrollIndicatorInsets` alongside `contentInset` to keep the scroll

2671indicator aligned. For static spacing that never changes, padding is fine.

2672

2673

2674

2675## Modern React Native Styling Patterns

2676

2677Follow these styling patterns for cleaner, more consistent React Native code.

2678

2679**Always use `borderCurve: 'continuous'` with `borderRadius`:**

2680

2681```tsx

2682// Incorrect

2683{ borderRadius: 12 }

2684

2685// Correct – smoother iOS-style corners

2686{ borderRadius: 12, borderCurve: 'continuous' }

2687```

2688

2689**Use `gap` instead of margin for spacing between elements:**

2690

2691```tsx

2692// Incorrect – margin on children

2693<View>

2694 <Text style={{ marginBottom: 8 }}>Title</Text>

2695 <Text style={{ marginBottom: 8 }}>Subtitle</Text>

2696</View>

2697

2698// Correct – gap on parent

2699<View style={{ gap: 8 }}>

2700 <Text>Title</Text>

2701 <Text>Subtitle</Text>

2702</View>

2703```

2704

2705**Use `padding` for space within, `gap` for space between:**

2706

2707```tsx

2708<View style={{ padding: 16, gap: 12 }}>

2709 <Text>First</Text>

2710 <Text>Second</Text>

2711</View>

2712```

2713

2714**Use `experimental_backgroundImage` for linear gradients:**

2715

2716```tsx

2717// Incorrect – third-party gradient library

2718<LinearGradient colors={['#000', '#fff']} />

2719

2720// Correct – native CSS gradient syntax

2721<View

2722 style={{

2723 experimental_backgroundImage: 'linear-gradient(to bottom, #000, #fff)',

2724 }}

2725/>

2726```

2727

2728**Use CSS `boxShadow` string syntax for shadows:**

2729

2730```tsx

2731// Incorrect – legacy shadow objects or elevation

2732{ shadowColor: '#000', shadowOffset: { width: 0, height: 2 }, shadowOpacity: 0.1 }

2733{ elevation: 4 }

2734

2735// Correct – CSS box-shadow syntax

2736{ boxShadow: '0 2px 8px rgba(0, 0, 0, 0.1)' }

2737```

2738

2739**Avoid multiple font sizes – use weight and color for emphasis:**

2740

2741```tsx

2742// Incorrect – varying font sizes for hierarchy

2743<Text style={{ fontSize: 18 }}>Title</Text>

2744<Text style={{ fontSize: 14 }}>Subtitle</Text>

2745<Text style={{ fontSize: 12 }}>Caption</Text>

2746

2747// Correct – consistent size, vary weight and color

2748<Text style={{ fontWeight: '600' }}>Title</Text>

2749<Text style={{ color: '#666' }}>Subtitle</Text>

2750<Text style={{ color: '#999' }}>Caption</Text>

2751```

2752

2753Limiting font sizes creates visual consistency. Use `fontWeight` (bold/semibold)

2754and grayscale colors for hierarchy instead.

2755

2756

The other instruction files in this repository
Repository	Format	Stack	Covers	Score	Changed
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-build.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	16/100	today
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-code-simplify.mdc · 51	Cursor rules	typescriptgithub-actions	testing-strategy	30/100	today
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-plan.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	16/100	today
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-review.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	16/100	today
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-ship.mdc · 51	Cursor rules	typescriptgithub-actions	testing-strategygitdeploymentdo-not	61/100	today
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-spec.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	16/100	today
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-test.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	16/100	today
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-forgecat/AGENTS.md · 51	AGENTS.md	typescriptgithub-actions	lint-formatstylearchdo-not	73/100	today
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-forgecat/CLAUDE.md · 51	CLAUDE.md	typescriptgithub-actions	teststylearchagent-behaviour	70/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-code/anthropics_claude-code_ralph-wiggum/for-cursor/.cursor/rules/cmd-cancel-ralph.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	16/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-code/anthropics_claude-code_ralph-wiggum/for-cursor/.cursor/rules/cmd-help.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	54/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-code/anthropics_claude-code_ralph-wiggum/for-cursor/.cursor/rules/cmd-ralph-loop.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	22/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_agent-sdk-dev/for-cursor/.cursor/rules/cmd-new-sdk-app.mdc · 51	Cursor rules	typescriptgithub-actions	setupstylearchdocs	76/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_claude-md-management/for-cursor/.cursor/rules/cmd-revise-claude-md.mdc · 51	Cursor rules	typescriptgithub-actions	agent-behaviour	50/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_code-review/for-cursor/.cursor/rules/cmd-code-review.mdc · 51	Cursor rules	typescriptgithub-actions	testing-strategygit	35/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_commit-commands/for-cursor/.cursor/rules/cmd-clean_gone.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	60/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_commit-commands/for-cursor/.cursor/rules/cmd-commit-push-pr.mdc · 51	Cursor rules	typescriptgithub-actions	stylegit	44/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_commit-commands/for-cursor/.cursor/rules/cmd-commit.mdc · 51	Cursor rules	typescriptgithub-actions	style	44/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_example-plugin/for-cursor/.cursor/rules/cmd-example-command.mdc · 51	Cursor rules	typescriptgithub-actions	lint-formatstyleagent-behaviour	58/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_feature-dev/for-cursor/.cursor/rules/cmd-feature-dev.mdc · 51	Cursor rules	typescriptgithub-actions	stylearchgit	56/100	today

The other instruction files in this repository

Repository

Format

Stack

Covers

Score

Changed

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-build.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

16/100

today

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-code-simplify.mdc · 51

Cursor rules

typescriptgithub-actions

testing-strategy

30/100

today

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-plan.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

16/100

today

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-review.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

16/100

today

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-ship.mdc · 51

Cursor rules

typescriptgithub-actions

testing-strategygitdeploymentdo-not

61/100

today

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-spec.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

16/100

today

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-test.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

16/100

today

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-forgecat/AGENTS.md · 51

AGENTS.md

typescriptgithub-actions

lint-formatstylearchdo-not

73/100

today

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-forgecat/CLAUDE.md · 51

CLAUDE.md

typescriptgithub-actions

teststylearchagent-behaviour

70/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-code/anthropics_claude-code_ralph-wiggum/for-cursor/.cursor/rules/cmd-cancel-ralph.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

16/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-code/anthropics_claude-code_ralph-wiggum/for-cursor/.cursor/rules/cmd-help.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

54/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-code/anthropics_claude-code_ralph-wiggum/for-cursor/.cursor/rules/cmd-ralph-loop.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

22/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_agent-sdk-dev/for-cursor/.cursor/rules/cmd-new-sdk-app.mdc · 51

Cursor rules

typescriptgithub-actions

setupstylearchdocs

76/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_claude-md-management/for-cursor/.cursor/rules/cmd-revise-claude-md.mdc · 51

Cursor rules

typescriptgithub-actions

agent-behaviour

50/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_code-review/for-cursor/.cursor/rules/cmd-code-review.mdc · 51

Cursor rules

typescriptgithub-actions

testing-strategygit

35/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_commit-commands/for-cursor/.cursor/rules/cmd-clean_gone.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

60/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_commit-commands/for-cursor/.cursor/rules/cmd-commit-push-pr.mdc · 51

Cursor rules

typescriptgithub-actions

stylegit

44/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_commit-commands/for-cursor/.cursor/rules/cmd-commit.mdc · 51

Cursor rules

typescriptgithub-actions

style

44/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_example-plugin/for-cursor/.cursor/rules/cmd-example-command.mdc · 51

Cursor rules

typescriptgithub-actions

lint-formatstyleagent-behaviour

58/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_feature-dev/for-cursor/.cursor/rules/cmd-feature-dev.mdc · 51

Cursor rules

typescriptgithub-actions

stylearchgit

56/100

today

Repository	Format	Stack	Covers	Score	Changed
n8n-io/n8npackages/@n8n/agents/AGENTS.md · 201k	AGENTS.md	typescriptlangchain+16	buildteststylearch+3	100/100	14 days ago
aaif-goose/gooseAGENTS.md · 53k	AGENTS.md	rusttypescript+2	setupbuildtestlint-format+7	100/100	8 days ago
duckduckgo/content-scope-scriptsspecial-pages/AGENTS.md · 70	AGENTS.md	typescriptjavascript+5	buildteststylearch+3	100/100	14 days ago
deepseek-ai/deepseek-harnessnative/landlock-run/AGENTS.md · 104k	AGENTS.md	typescriptvitest+9	setupteststylearch+3	100/100	today
code-yeongyu/oh-my-openagentpackages/web/AGENTS.md · 68k	AGENTS.md	typescriptbun+10	setupbuildtestlint-format+6	100/100	13 days ago
TryGhost/Ghoste2e/AGENTS.md · 55k	AGENTS.md	typescriptjavascript+11	setupteststylearch+2	100/100	today
vllm-project/vllmAGENTS.md · 89k	AGENTS.md	pythonpytorch+3	setuptestlint-formatstyle+5	100/100	14 days ago
mui/material-uiAGENTS.md · 99k	AGENTS.md	typescriptjavascript+13	setupbuildtestlint-format+9	100/100	14 days ago

Built for the same person as RuleStack

Built for the same person as RuleStack

Also in nota-america/forgecat-agent-profiles

Similar configs

Put this measurement in your README