The CLAUDE.md Every React Native Project Needs

React Native development is fundamentally different from web development. Your platform-aware code, native modules, navigation stacks, and app store requirements don't fit into a generic CLAUDE.md template. Yet most teams hand their AI agent a standard web developer playbook and wonder why the results are broken.

A proper CLAUDE.md for React Native isn't just documentation — it's the instruction set that teaches your AI agent the mobile-specific patterns, constraints, and workflows that separate production apps from prototype code.

Why React Native Projects Need a Specialized CLAUDE.md

Web frameworks and mobile frameworks solve different problems. A web app cares about SEO, server rendering, route prefetching, and CSS media queries. A React Native app cares about platform performance, native bridge efficiency, native module versioning, permissions systems, and app store review guidelines.

When an AI agent doesn't understand these differences, it writes code that:

• Ignores platform-specific visual conventions (iOS vs Android)
• Passes navigation props through nested screens (anti-pattern)
• Uses non-web-compatible APIs without bridge detection
• Misses permission declarations in app.json and native configs
• Creates type-unsafe screen navigation
• Forgets safe area insets and notch handling

A mobile-aware CLAUDE.md prevents all of these. It codifies your project's decisions upfront so every agent works inside those guardrails from the first commit.

What's Different About Mobile

Navigation & Screen Types

Web uses URL-based routing. Mobile uses navigation stacks. React Navigation stacks are deeply nested, type-aware, and require careful handling of screen params. A generic CLAUDE.md misses this entirely.

// ❌ Wrong: passing props through nesting
<Stack.Screen
  name="Details"
  component={() => <DetailsScreen userId={userId} />}
/>

// ✓ Right: type-safe params
<Stack.Screen
  name="Details"
  component={DetailsScreen}
  initialParams={{ userId: '123' }}
/>

// Screen component receives params, not props
function DetailsScreen({ route }: RootStackScreenProps<'Details'>) {
  const { userId } = route.params;
}

Native Modules & Bridges

Web doesn't have native modules. Mobile does. Your CLAUDE.md needs to document which native modules are installed, their versioning constraints, platform support, and how to safely use them.

// Document module availability
import * as LocalAuthentication from 'expo-local-authentication';

// Always check support before use
const compatible = await LocalAuthentication.hasHardwareAsync();
if (!compatible) {
  // fallback to PIN
}

Platform-Specific Code

Web developers rarely need platform branching. Mobile developers do it constantly. Your CLAUDE.md must establish conventions for using Platform.select(), file naming (*.ios.ts), and when branching is appropriate.

// Convention 1: File naming for platform-specific logic
src/utils/storage.ios.ts   // iOS only
src/utils/storage.android.ts // Android only
src/utils/storage.ts       // Shared interface

// Convention 2: Platform.select for small diffs
const statusBarHeight = Platform.select({
  ios: 44,
  android: 24,
});

Build & Deployment

Web uses npm install and npm run build. Mobile uses EAS, Xcode, and Gradle. Your AI agent needs to understand app.json, eas.json, native config plugins, and app store submission rules.

The Template Structure

A production-grade CLAUDE.md for React Native includes these sections:

1. Project Layout

# Project Structure
src/
├── app/              # Navigators & root screens
├── screens/          # Screen components (1 file per screen)
├── components/       # Shared UI components
├── hooks/            # Shared hooks (useAuth, useApi, etc)
├── services/         # API clients, platform services
├── lib/              # Utilities, helpers
├── types/            # TypeScript interfaces & navigation types
├── theme/            # Colors, typography (NOT Tailwind)

2. Component Patterns

// components/Button.tsx
import { TouchableOpacity, Text } from 'react-native';

interface ButtonProps {
  label: string;
  onPress: () => void;
  variant?: 'primary' | 'secondary';
}

export function Button({ label, onPress, variant = 'primary' }: ButtonProps) {
  const bgColor = variant === 'primary' ? 'bg-blue-600' : 'bg-gray-200';
  return (
    <TouchableOpacity
      onPress={onPress}
      className={`px-4 py-2 rounded ${bgColor}`}
    >
      <Text>{label}</Text>
    </TouchableOpacity>
  );
}

3. Hook Conventions

// hooks/useApi.ts
export function useApi<T>(
  endpoint: string,
  options?: RequestInit
) {
  const [data, setData] = useState<T | null>(null);
  const [error, setError] = useState<Error | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const fetch = async () => {
      try {
        const res = await fetch(endpoint, options);
        setData(await res.json());
      } catch (e) {
        setError(e as Error);
      } finally {
        setLoading(false);
      }
    };
    fetch();
  }, [endpoint]);

  return { data, error, loading };
}

4. Navigation Typing

// types/navigation.ts
import { NativeStackScreenProps } from '@react-navigation/native-stack';

export type RootStackParamList = {
  Auth: undefined;
  Home: undefined;
  Details: { userId: string };
  Settings: undefined;
};

export type RootStackScreenProps<T extends keyof RootStackParamList> =
  NativeStackScreenProps<RootStackParamList, T>;

// Usage in screen component
function DetailsScreen({ route }: RootStackScreenProps<'Details'>) {
  const { userId } = route.params; // fully typed
}

5. API Layer

// services/api.ts
const BASE_URL = __DEV__ ? 'http://localhost:3000' : 'https://api.example.com';

export const api = {
  async get<T>(endpoint: string) {
    const res = await fetch(`${BASE_URL}${endpoint}`);
    if (!res.ok) throw new Error('API Error');
    return res.json() as Promise<T>;
  },

  async post<T>(endpoint: string, body: any) {
    const res = await fetch(`${BASE_URL}${endpoint}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
    });
    if (!res.ok) throw new Error('API Error');
    return res.json() as Promise<T>;
  },
};

6. Styling Rules

// theme/colors.ts
export const colors = {
  primary: '#3B82F6',
  secondary: '#8B5CF6',
  background: '#000000',
  surface: '#1F2937',
  text: '#FFFFFF',
  mutedText: '#9CA3AF',
  error: '#EF4444',
  success: '#10B981',
};

// Use StyleSheet for performance
import { StyleSheet } from 'react-native';

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: colors.background,
    paddingHorizontal: 16,
  },
});

7. Testing Strategy

Use React Native Testing Library + Jest. Mock platform-specific modules. Test navigation separately from components.

// __tests__/components/Button.test.tsx
import { render, fireEvent } from '@testing-library/react-native';
import { Button } from '@/components/Button';

describe('Button', () => {
  it('calls onPress when pressed', () => {
    const onPress = jest.fn();
    const { getByText } = render(
      <Button label="Press me" onPress={onPress} />
    );
    fireEvent.press(getByText('Press me'));
    expect(onPress).toHaveBeenCalled();
  });
});

8. Security Checklist

• Never store tokens in AsyncStorage (use SecureStore)
• Enable certificate pinning for API requests
• Never log sensitive data in console (use __DEV__)
• Validate all permissions before accessing platform features
• Keep native dependencies up-to-date
• Use ProGuard for Android release builds
• Sign iOS builds with proper provisioning profiles

How It Works With Archie Mobile

Archie Mobile extends Archie with mobile-specific skills that use your CLAUDE.md to design, break down, and implement features.

When you run /architect on a mobile feature, Archie reads your CLAUDE.md, understands your navigation structure, platform support matrix, and API layer. It designs the feature considering iOS/Android differences, native module availability, and safe area insets from the start.

When you run /tech-lead, Archie breaks the feature into platform-aware tasks. Instead of one generic "add auth" task, it might create: "Implement auth hook (shared)", "Add Face ID on iOS", "Add BiometricPrompt on Android".

When /dev-agent runs, it works in isolated git worktrees just like web development, but it knows the mobile patterns from your CLAUDE.md. It creates properly typed screens, respects your component library, and uses the API layer you defined.

Next Steps

Download the free React Native CLAUDE.md template below. It includes all sections, example code, and a memory file structure designed for AI-assisted mobile development.

Add it to your project root, customize it for your stack (Expo vs bare React Native, your nav library, your state management), and watch your AI agent start shipping production mobile code.

Ready to pair AI agents with your mobile team? Learn how to structure the full workflow with Archie Mobile.