React Native + Expo

Scenario

You maintain a cross-platform mobile application built with React Native and Expo.

The application targets:

• iOS;
• Android.

The repository uses Expo Router, TypeScript, native device APIs, and EAS builds.

Mobile development introduces concerns that a normal React web application's instructions may not cover, such as:

• platform-specific behavior;
• native permissions;
• Expo compatibility;
• device testing;
• build configuration.

Repository Structure

mobile-app/
├── app/
│   ├── _layout.tsx
│   ├── index.tsx
│   ├── profile/
│   └── settings/
├── src/
│   ├── components/
│   ├── features/
│   ├── hooks/
│   └── services/
├── assets/
├── app.json
├── eas.json
├── package.json
└── AGENTS.md

AGENTS.md

# Mobile Application Instructions

## Development

- Use the repository's existing Expo and React Native workflow.
- Use `pnpm` for dependency management.
- Follow the existing Expo Router structure under `app/`.
- Keep reusable application logic under `src/`.

## Cross-Platform Changes

- Consider both iOS and Android when changing mobile behavior.
- Do not assume a platform-specific API behaves identically across platforms.
- Use existing platform abstractions when available.
- Keep platform-specific implementations explicit when behavior genuinely differs.

## Native Dependencies

- Prefer Expo-compatible packages when they satisfy the requirement.
- Check compatibility with the project's current Expo SDK before adding native dependencies.
- Do not introduce native configuration changes unnecessarily.

## Permissions

- Use the existing permission-request workflow.
- Update platform permission configuration when introducing new device capabilities.
- Handle denied permissions as a normal application state.

## UI

- Preserve safe-area, keyboard, accessibility, and touch behavior.
- Follow existing responsive layout patterns.
- Avoid relying on browser-only APIs.

## Validation

For mobile changes:

- run `pnpm lint`;
- run `pnpm typecheck`;
- run relevant tests;
- verify important UI changes on the affected platforms.

For native configuration changes, validate the appropriate development or EAS build workflow.

What This Does

This adds mobile-specific constraints that would not be obvious from generic React guidance.

For example, a developer implementing file selection should not automatically use:

document.querySelector("input[type=file]");

That is a browser API.

The application needs a React Native or Expo-compatible approach.

Likewise, introducing camera access may require more than calling an API.

The workflow may include:

install compatible library
        ↓
configure permissions
        ↓
request runtime permission
        ↓
handle denial
        ↓
test iOS
        ↓
test Android

What This Does NOT Do

The instructions do not require every change to contain separate iOS and Android implementations.

Most React Native code can remain shared.

Platform-specific code should exist when platform behavior genuinely differs.

The file also does not require testing every small change on every physical device.

Validation should be proportional to the change.

A native permission change deserves more platform verification than a text-copy update.

Why These Instructions Matter

A React Native repository looks familiar to web developers:

React
TypeScript
components
hooks
state

But the runtime is different.

A package that works in a browser may depend on:

DOM
window
localStorage
browser file APIs

and therefore fail in React Native.

Native permissions create another important difference.

Suppose an agent adds location functionality but forgets platform configuration.

The TypeScript code may compile while the feature fails on a real device or production build.

Key Decisions

Think cross-platform

Ask:

Does this behavior differ on iOS and Android?

before assuming one implementation covers both.

Prefer existing abstractions

If the repository already wraps:

storage
permissions
notifications
camera
filesystem

reuse those abstractions.

Check Expo compatibility

A package that supports React Native is not automatically compatible with the project's Expo workflow.

Treat permissions as product behavior

Users can deny permissions.

The application must handle that state rather than assuming permission is granted.

Validate native changes more deeply

Changes to:

app.json
native modules
permissions
EAS configuration

have a different risk profile from normal JavaScript changes.

When to Use This Pattern

Use this pattern when:

• the project uses React Native and Expo;
• iOS and Android are both supported;
• native device capabilities are used;
• EAS builds or Expo configuration matter;
• agents familiar with web React may work on the repository.

The key lesson is that React Native is React, but it is not a browser application.