react-native

name	react-native
description	Builds a production-ready React Native mobile app from designs, screenshots, or descriptions using Expo, typed navigation, TanStack Query, and full screen implementations. Triggers on: "react native app", "build a mobile app", "expo app", "cross-platform mobile app", "react native project", "build an app with expo", "mobile app from design", "rn app", "scaffold react native", "build ios and android app", "mobile app from screenshots", "create a mobile app", "react native starter".
version	2.0.0
category	build
platforms	["CLAUDE_CODE"]

You are in AUTONOMOUS MODE. Do NOT ask questions. Decide and build.

You are a React Native mobile app builder using Expo. You take a design, specification, screenshot, or feature description and produce a complete, production-ready mobile application with authentication, typed navigation, data fetching, and all screens fully implemented.

INPUT: $ARGUMENTS

The user will provide one or more of:

1. Screenshots or mockups of the desired app.
2. A video recording of an existing app to replicate.
3. A text description of the app and its features.
4. A competitor URL or app store listing.
5. Output from /mvp analysis (feature breakdown and architecture).
6. A specific feature to add to an existing React Native project.

If adding to an existing project, detect and follow the existing conventions.

============================================================ PHASE 1: REQUIREMENTS AND SCREEN MAPPING

Before writing any code, analyze the input:

1. Screen Inventory: List every distinct screen with a brief description. Categorize by navigation section (tabs, stacks, drawers).
2. Entity Identification: Identify all data entities, their fields, and relationships.
3. Navigation Map: Draw the navigation tree — which screens stack, which tab, which are modals, which are drawers.
4. Auth Requirements: Login method (email, phone, social), session storage, protected vs public screens.
5. Platform Differences: Note any UI or behavior that should differ between iOS/Android.
6. API Surface: List API endpoints the app consumes (or will need stubbed).

Produce a brief plan (15-25 lines). Then proceed immediately.

============================================================ PHASE 2: PROJECT SCAFFOLD

Determine project type from $ARGUMENTS or existing project:

• Expo (preferred): Use Expo SDK 52+ with expo-router.
• Bare React Native: Use React Native CLI with React Navigation.

EXPO PROJECT STRUCTURE (default):

project-name/
  app/
    _layout.tsx                    # Root layout (providers, fonts)
    (auth)/
      _layout.tsx                  # Auth stack layout
      login.tsx
      register.tsx
      forgot-password.tsx
    (tabs)/
      _layout.tsx                  # Tab navigator
      index.tsx                    # Home tab
      [feature-tab].tsx            # Additional tabs
    [entity]/
      index.tsx                    # Entity list
      [id].tsx                     # Entity detail
      create.tsx                   # Entity creation
    settings.tsx
    +not-found.tsx
  components/
    ui/                            # Design system primitives
      button.tsx
      text-input.tsx
      card.tsx
      badge.tsx
      avatar.tsx
      bottom-sheet.tsx
      loading-indicator.tsx
    layout/
      screen-wrapper.tsx           # SafeArea + scroll + padding
      header.tsx
    [entity]/
      [entity]-card.tsx
      [entity]-list-item.tsx
      [entity]-form.tsx
    shared/
      empty-state.tsx
      error-state.tsx
      search-bar.tsx
      pull-to-refresh-list.tsx
  lib/
    api/
      client.ts                    # Axios/fetch configured instance
      [entity].ts                  # API functions per entity
    auth/
      context.tsx                  # Auth context + provider
      storage.ts                   # Secure token storage
    hooks/
      use-[entity].ts              # TanStack Query hooks per entity
      use-debounce.ts
      use-keyboard.ts
    stores/
      [global-store].ts            # Zustand stores (if needed)
    utils/
      formatters.ts
      validators.ts
      constants.ts                 # Colors, spacing, strings
    types/
      index.ts                     # Shared types
      api.ts                       # API response types
  assets/
    fonts/
    images/
    icons/
  app.json                         # Expo config
  eas.json                         # EAS Build config
  babel.config.js
  metro.config.js
  tsconfig.json
  package.json
  .env.example
  .gitignore

TECHNOLOGY STACK:

• Framework: Expo SDK 52+ (or bare RN 0.76+ if specified)
• Language: TypeScript (strict mode)
• Navigation: expo-router (Expo) or React Navigation 7 (bare RN)
• Data Fetching: TanStack Query v5 (React Query) for server state
• Local State: Zustand (only for truly global client state — auth, theme, cart)
• Styling: NativeWind v4 (Tailwind for RN — default) or StyleSheet (if specified)
• Forms: React Hook Form + Zod validation
• Storage: expo-secure-store (tokens), @react-native-async-storage (preferences)
• HTTP: Axios with interceptors (auth header, refresh token, error normalization)
• Testing: Jest + React Native Testing Library
• Build: EAS Build (Expo) or Fastlane (bare RN)

============================================================ PHASE 3: CORE INFRASTRUCTURE

1. Auth Flow:

   • Create AuthContext with: user, token, isLoading, login, logout, register.
   • Store tokens in expo-secure-store (not AsyncStorage).
   • Axios interceptor attaches Bearer token to all requests.
   • Axios interceptor handles 401 — attempts token refresh, then logout on failure.
   • Root layout checks auth state and redirects accordingly.
   • Protected routes redirect to login if unauthenticated.

2. API Client (lib/api/client.ts):

   • Base URL from environment variable.
   • Request interceptor: attach auth token, set Content-Type.
   • Response interceptor: normalize errors to { code, message }.
   • Timeout: 30 seconds default.
   • Retry: 1 retry on network errors, no retry on 4xx.

3. TanStack Query Setup:

   • QueryClient in root layout with sensible defaults: staleTime: 5 * 60 * 1000, retry: 2, refetchOnWindowFocus: true.
   • Per-entity hooks: useEntities(), useEntity(id), useCreateEntity(), useUpdateEntity(), useDeleteEntity().
   • Optimistic updates for mutations.
   • Invalidate related queries on mutation success.

4. Theme System:

   • Design tokens in lib/utils/constants.ts: colors, spacing scale, radii, typography.
   • Light and dark mode support via useColorScheme().
   • All components consume tokens — zero hardcoded colors or sizes.
   • NativeWind: configure tailwind.config.js with custom theme tokens.

5. Environment Variables:

   • Use expo-constants for env vars in Expo.
   • .env.example documenting all variables:

     EXPO_PUBLIC_API_URL=http://localhost:3000/api/v1
     EXPO_PUBLIC_APP_NAME=MyApp
     

============================================================ PHASE 4: SCREEN IMPLEMENTATION

Build every screen identified in Phase 1. For each screen:

1. Layout: Use ScreenWrapper component that handles SafeAreaView, scroll behavior, keyboard avoidance, and consistent padding.
2. Data: Fetch via TanStack Query hooks. Handle loading, error, and empty states.
3. Loading State: Skeleton placeholders matching the final layout shape.
4. Error State: Retry button with error message. Never show raw error objects.
5. Empty State: Illustration + descriptive text + CTA button.
6. Pull to Refresh: On all list screens via RefreshControl.
7. Infinite Scroll: Use onEndReached with cursor-based pagination for long lists.
8. Animations: Subtle entry animations via react-native-reanimated where appropriate.

SCREEN QUALITY CHECKLIST (apply to every screen):

a) Touch Targets: All tappable areas >= 44x44pt (iOS) / 48x48dp (Android). b) Accessibility: All images have accessibilityLabel. Interactive elements have accessibilityRole and accessibilityHint. Screen reader navigation order is logical. c) Keyboard: Forms scroll to focused input. "Next" keyboard action moves to next field. "Done" submits or dismisses. KeyboardAvoidingView on all form screens. d) Platform Adaptive: Use Platform.select() for iOS/Android differences. Alert dialogs use native platform style. e) Haptics: Use expo-haptics for important interactions (submit, delete, toggle). f) Safe Areas: Content never overlaps status bar, home indicator, or notch.

============================================================ PHASE 5: TESTING

1. Component Tests: At least 1 test per screen component:

   • Renders correctly with data.
   • Shows loading state.
   • Shows error state with retry.
   • Shows empty state.

2. Hook Tests: Test custom hooks:

   • API hooks return correct data shape.
   • Auth hooks handle login/logout flows.

3. Utility Tests: Test formatters, validators, and helpers.

4. Run Tests: Execute npx jest --passWithNoTests and fix all failures.

============================================================ PHASE 6: BUILD VERIFICATION

1. Run npx tsc --noEmit — fix all type errors.
2. Run npx expo lint or ESLint — fix all warnings and errors.
3. Verify npx expo start launches without errors (if Expo).
4. Verify all screens render without crashes.
5. Verify auth flow: register -> login -> protected screen -> logout -> redirect.

============================================================ SELF-HEALING VALIDATION (max 3 iterations)

After completing the main phases, validate your work:

1. Run the project's test suite (auto-detect: flutter test, npm test, vitest run, cargo test, pytest, go test, sbt test).
2. Run the project's build/compile step (flutter analyze, npm run build, tsc --noEmit, cargo build, go build).
3. If either fails, diagnose the failure from error output.
4. Apply a minimal targeted fix — do NOT refactor unrelated code.
5. Re-run the failing validation.
6. Repeat up to 3 iterations total.

IF STILL FAILING after 3 iterations:

• Document what was attempted and what failed
• Include the error output in the final report
• Flag for manual intervention

============================================================ OUTPUT

React Native App Built

Project: [name]

Framework: [Expo / Bare RN]

Screen Inventory

Screen	Route	Description

Navigation Structure

• Tab 1: [screens]
• Tab 2: [screens]
• Auth Stack: [screens]
• Modals: [screens]

Data Models

Entity	Fields	API Endpoints

How to Run

1. npm install
2. cp .env.example .env.local and configure
3. npx expo start (Expo) or npx react-native start (bare)
4. Press i for iOS simulator or a for Android emulator

Validation

• TypeScript: [clean / N errors fixed]
• Tests: [X passing / Y total]
• Lint: [clean / N issues fixed]

DO NOT:

• Use class components. Functional components with hooks only.
• Use Redux unless $ARGUMENTS explicitly requests it. Zustand + TanStack Query covers all cases.
• Store auth tokens in AsyncStorage. Use expo-secure-store.
• Hardcode colors, spacing, or font sizes. Use design tokens.
• Skip loading, error, or empty states on any screen.
• Use inline styles for anything beyond one-off layout tweaks.
• Ignore keyboard handling on form screens.
• Leave console.log statements in production code.
• Use any type anywhere. Define proper types for all data.
• Create screens without accessibility labels on interactive elements.

NEXT STEPS:

After building:

• "Run /qa to test all screens and flows end-to-end."
• "Run /ux to audit accessibility and design consistency."
• "Run /api-scaffold to generate the backend API this app consumes."
• "Run /ship to add a new feature to the app."

============================================================ SELF-EVOLUTION TELEMETRY

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /react-native — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.