Mobile App Development with Cursor

Your team needs to ship a mobile app that works on both iOS and Android. The designers handed you Figma mockups, the backend API already exists, and the deadline is six weeks away. You chose React Native because your team knows TypeScript, but nobody has deep native module experience. The first screen took three days because half the time was spent debugging Metro bundler issues, platform-specific styling quirks, and navigation library configuration. At this pace, you will not make the deadline.

Cursor changes the calculus for mobile development because it understands your project structure, your component library, and your platform constraints simultaneously. Instead of context-switching between Stack Overflow, React Native docs, and platform-specific guides, you stay in the editor and let Agent handle the cross-platform complexity.

What You’ll Walk Away With

• A project rules setup that makes Cursor aware of iOS vs Android differences
• Prompts for generating screens, navigation flows, and platform-specific components
• A workflow for connecting React Native to existing backend APIs
• Techniques for debugging mobile-specific issues (Metro, native modules, permissions)
• Strategies for handling platform-specific code paths with Agent mode

Configuring Cursor for React Native

Mobile projects have more context than web projects. You need Cursor to understand not just your TypeScript code, but also your native configuration (Xcode project files, Gradle build configs), your navigation structure, and your platform-specific overrides.

Start with a .cursorignore that keeps the index focused:

.cursorignore

ios/Pods/
android/.gradle/
android/build/
android/app/build/
node_modules/
.expo/
*.lock

Native dependency directories are massive and rarely helpful for AI context. Excluding them speeds up indexing and keeps Agent focused on your application code.

Next, create project rules that encode your mobile architecture:

.cursor/rules/mobile.md

# React Native Project

## Stack
- React Native 0.76 with New Architecture enabled
- TypeScript strict mode
- React Navigation 7 (native stack)
- Zustand for state management
- React Query for API calls
- Nativewind (Tailwind CSS for React Native)

## Platform Conventions
- Platform-specific files use .ios.tsx / .android.tsx extensions
- Shared components go in src/components/
- Screens go in src/screens/ with one file per screen
- Navigation defined in src/navigation/
- API layer in src/api/ using React Query hooks

## Styling
- Use Nativewind className for styling, not StyleSheet.create
- All spacing uses 4px base unit (p-1 = 4px, p-2 = 8px)
- Use SafeAreaView at screen level, not component level
- Test on both iPhone SE (small) and iPhone 15 Pro Max (large)

## Important
- This is React Native, not React DOM. Never use HTML elements or web CSS.
- Always handle both iOS and Android behaviors
- Test keyboard avoidance on forms
- Use Platform.select() for platform-specific values
- Images must include @2x and @3x variants

Scaffolding Screens from Designs

The most common mobile development task is turning a design into a screen. Cursor excels at this when you give it the right context.

Tip

Copy-paste prompt for generating a screen from a design description:

@src/navigation/RootNavigator.tsx @src/components/Button.tsx @src/components/Input.tsx

Create a new screen at src/screens/ProfileScreen.tsx that implements a user profile editor:

1. Header: User avatar (circular, 80px) with camera icon overlay for photo change
2. Form fields: Display name, email (read-only), phone number, bio (multiline)
3. Section: Notification preferences with toggle switches for email, push, SMS
4. Bottom: "Save Changes" button using our Button component, disabled until changes are made
5. Loading state while fetching profile data
6. Keyboard avoiding view that scrolls the active field into view

Use React Query to fetch from GET /api/users/me and PATCH /api/users/me.
Use our existing Input and Button components.
Register the screen in RootNavigator.
Follow our Nativewind styling conventions.

The key to good screen generation is referencing your existing components. When you point Agent at Button.tsx and Input.tsx, it uses your actual component API (props, variants, styles) rather than inventing its own.

Handling Platform Differences

When a screen needs to behave differently on iOS and Android, be explicit:

@src/screens/ProfileScreen.tsx

The profile screen needs these platform-specific adjustments:

iOS:
- Use a large title navigation header (headerLargeTitle: true)
- Date picker should use the inline iOS style
- Haptic feedback on save button press

Android:
- Use a standard material header
- Date picker should use the Android dialog style
- Use the system back gesture, not a custom back button

Use Platform.select() for simple values. For complex differences,
create ProfileScreen.ios.tsx and ProfileScreen.android.tsx if needed.

Connecting to Backend APIs

Mobile apps are API consumers. Cursor can generate your entire API integration layer if you give it the backend contract.

Tip

Copy-paste prompt for generating an API layer with React Query:

@src/api/client.ts

Here are the endpoints for our user feature:

- GET /api/users/me -> { id, name, email, phone, bio, avatar_url, preferences }
- PATCH /api/users/me -> accepts partial user object, returns updated user
- POST /api/users/me/avatar -> multipart form upload, returns { avatar_url }
- GET /api/notifications -> paginated list { data: Notification[], next_cursor }
- PATCH /api/notifications/:id/read -> marks notification as read

Generate React Query hooks in src/api/hooks/:
1. Each endpoint gets a custom hook with proper TypeScript types
2. Mutations should optimistically update the cache
3. The notifications hook should support infinite scroll with useInfiniteQuery
4. Error handling should show a toast using our showToast utility
5. Include retry logic for network failures (3 retries with exponential backoff)

Use our existing API client at src/api/client.ts for the base fetch function.

Working with Navigation

Navigation is one of the most error-prone parts of React Native development. Deep linking, tab structures, and authenticated vs unauthenticated stacks all have subtle configuration requirements.

@src/navigation

Refactor our navigation to support:
1. Auth flow: Login -> Register -> ForgotPassword (no back gesture to main app)
2. Main tabs: Home, Search, Notifications, Profile
3. Modal stack: any screen can present a modal (e.g., compose post, settings)
4. Deep linking: myapp://profile, myapp://post/:id, myapp://notifications

Requirements:
- The tab bar should hide when keyboard is open on Android
- Notifications tab should show an unread count badge
- Deep links should work when the app is cold-started
- Authenticated screens redirect to login if no token is present

Use React Navigation 7 with native stack.
Follow the navigator patterns already in our codebase.

Caution

Agent sometimes generates navigation configurations that work on one platform but crash on the other. Always test navigation changes on both iOS and Android simulators before considering them done. Pay special attention to gesture handling and header configuration, which differ significantly between platforms.

Debugging Mobile-Specific Issues

Mobile development has a unique class of bugs that do not exist in web development: Metro bundler crashes, native module linking failures, platform permission issues, and device-specific rendering bugs. Cursor’s Ask mode is your first tool for these.

Metro Bundler Issues

My React Native app fails to start with this Metro error:

error: Error: Unable to resolve module @react-navigation/native-stack
from src/navigation/RootNavigator.tsx

I have run npm install and the package is in node_modules.
What are the common causes of Metro not resolving installed packages?

Ask mode will walk you through the usual suspects: stale Metro cache (npx react-native start --reset-cache), missing babel configuration for the package, or a version mismatch between React Navigation packages.

Native Module Failures

After adding react-native-camera, the iOS build fails with:

ld: framework not found AVFoundation
clang: error: linker command failed with exit code 1

But AVFoundation is a system framework. What is wrong?

I am using React Native 0.76 with New Architecture.
My Podfile is at @ios/Podfile.

Agent can analyze your Podfile and identify missing pod installs, incorrect build phases, or framework linking issues specific to the New Architecture.

Debugging Layout Issues

Mobile layout bugs are notoriously hard to debug because you cannot inspect elements the way you can in a browser. Describe the visual issue to Cursor:

@src/screens/ChatScreen.tsx

The chat message list renders correctly, but when the keyboard opens:
1. The input field is hidden behind the keyboard on Android
2. On iOS, the list scrolls up correctly but there is a 20px gap at the bottom
3. The "scroll to bottom" FAB overlaps with the input field

Here is my current KeyboardAvoidingView setup. What is wrong
and how do I fix it for both platforms?

Building Offline-First Features

Mobile apps need to work without reliable network connectivity. This is a cross-cutting concern that Cursor can help weave through your existing code:

Tip

Copy-paste prompt for adding offline support:

@src/api/client.ts @src/api/hooks/useNotifications.ts

Add offline support to our notification system:

1. Cache notification data in AsyncStorage with a 24-hour expiry
2. When offline, serve from cache and show an "Offline" banner
3. When back online, sync: fetch new notifications and mark queued reads
4. Queue read-marking actions while offline and replay when connected
5. Use React Query's built-in offline support (networkMode: 'offlineFirst')

Also create a useNetworkStatus hook that:
- Uses @react-native-community/netinfo
- Provides isConnected and connectionType
- Shows a non-intrusive banner when offline

Do not modify the existing hook APIs -- wrap them with offline awareness.

When This Breaks

Agent generates web-specific code in a React Native project. This happens when your rules are not active or when the AI confuses React DOM with React Native. The most common symptom: generating <div> instead of <View>, or using CSS properties like box-shadow that do not exist in React Native. Your project rules should explicitly state “This is React Native. Never use HTML elements or web-specific CSS.”

Platform-specific files are not picked up by Metro. If Agent creates Component.ios.tsx but Metro still loads the base Component.tsx, the base file takes priority. React Native’s platform resolution requires either platform-specific files without a base file, or a base file that re-exports from platform-specific ones.

Generated native module code does not compile. Agent can write Objective-C bridges and Kotlin modules, but the build configuration is often wrong. For native module issues, provide your Podfile (iOS) or build.gradle (Android) as context so Agent generates compatible configurations.

React Navigation types are incorrect. Navigation typing in React Navigation is complex. If Agent generates screens with incorrect route params, reference your src/navigation/types.ts file explicitly. The AI needs to see your RootStackParamList type to generate correct navigation props.

Styles look different on iOS and Android. Shadow rendering, font weights, and padding behave differently across platforms. When generating screens, tell Agent: “Use Platform.select for shadows since iOS uses shadowColor/shadowOffset and Android uses elevation.”

What’s Next

Testing & TDD Set up mobile testing with Detox and Jest for React Native.

CI/CD Build mobile-specific CI pipelines with EAS Build and Fastlane.

Performance Profile and optimize React Native rendering and startup time.