Wzorce rozwoju React Native

Agent AI dobrze radzi sobie z React Native, gdy zna przypięte wersje bibliotek, a każda zmiana przechodzi bramki niewymagające ludzkiego czytelnika: sprawdzenie typów, lint, Jest z React Native Testing Library, flow Maestro na urządzeniu i build release. Z tymi bramkami agent może przejąć dane offline, wydajność list i uwierzytelnianie biometryczne.

Ta strona jest dla programistów i liderów technicznych, którzy wypuszczają aplikację React Native do App Store i Google Play. Twój FlatList zacina się na średniej klasy Androidzie, gdy lista przekroczy kilkaset wierszy. Build release ulega awarii na module natywnym, którego build deweloperski nigdy nie załadował. Ekran offline z zeszłotygodniowego demo gubi zapisy, gdy sieć się zrywa. Nic z tego nie widać w symulatorze na laptopie, a wszystko to jest pracą zależną od konkretnych bibliotek, którą agent wykonuje dobrze, gdy wie, o którą bibliotekę i wersję chodzi.

Dopiero zaczynasz konfigurować agenta do pracy mobilnej? Zacznij od przeglądu rozwoju aplikacji mobilnych, który opisuje wybór stosu, instalację jego skilli i weryfikację na symulatorach.

Co dają ci wzorce React Native z tej strony

• Tabelę wersji i blok instrukcji projektu, które powstrzymują agenta przed pisaniem API ze starszej wersji głównej
• Prompt do szkieletu, który daje aplikację Expo z testami i bramkami od pierwszego dnia
• Prompt offline-first dla react-native-mmkv v4 i TanStack Query, z mutacjami, które przetrwają zabicie aplikacji
• Prompt do FlashList v2 i polecenie dla Androida, które dowodzi, że zacinanie zniknęło
• Prompt do bramki biometrycznej, która przełącza na kod zamiast blokować użytkownika
• Tabelę weryfikacji: która bramka czego dowodzi i kto zatwierdza zmianę
• Mapę awarii, których nigdy nie widać w symulatorze, z krokami naprawy

Jakie wersje React Native zakłada ta strona?

Agenci mieszają API z kilku wersji głównych, bo ich dane treningowe obejmują je wszystkie. Podaj wersje w prompcie albo w instrukcjach projektu. Tabela pokazuje, co npm serwował 26.09.2026.

Pakiet	Wersja 26.09.2026	Co zmienia się dla agenta
react-native	0.87.1 (Expo SDK 57 przypina 0.86.3)	Nowa Architektura jest jedyną architekturą: 0.82 usunęło możliwość jej wyłączenia (changelog React Native)
expo	57.0.25	Pakiety natywne instaluj przez npx expo install, nigdy przez ręczną edycję wersji
@shopify/flash-list	2.3.2 (SDK 57 przypina 2.0.2)	v2 działa tylko na Nowej Architekturze i nie przyjmuje szacunków rozmiaru
react-native-mmkv	4.3.2	v4 to Nitro Module: createMMKV() i storage.remove(), a nie new MMKV() i storage.delete()
@tanstack/react-query	5.104.0	Utrwalanie przez @tanstack/react-query-persist-client i @tanstack/query-sync-storage-persister
@testing-library/react-native	14.0.1	v14 porzuca React 18, zmienia render i renderHook na asynchroniczne i wymaga pakietu test-renderer jako peer dependency
jest-expo	57.0.5	Preset Jest, który Expo dokumentuje dla testów jednostkowych; mockuje natywną stronę Expo SDK

Nową aplikację zaczynaj na Expo. Domyślny szablon create-expo-app to TypeScript z Expo Router. Szczegóły SDK, EAS i aktualizacji over-the-air opisuje strona wzorce rozwoju Expo; ta strona obejmuje pracę z React Native, która wygląda tak samo z Expo i bez niego.

Daj agentowi kontekst React Native przed pierwszym promptem

Trzy rzeczy zmieniają wynik agenta bardziej niż jakiekolwiek sformułowanie promptu: powyższa tabela wersji, lista bramek, które agent musi uruchomić, oraz skille dziedzinowe lub serwery MCP, dzięki którym sprawdzi swoją pracę na urządzeniu.

Instrukcje projektu. Wstaw ten blok do CLAUDE.md dla Claude Code, do AGENTS.md dla Codeksa i do reguły projektu w Cursorze. Treść jest identyczna we wszystkich trzech narzędziach.

## React Native rules
- Expo SDK 57, React Native 0.86 (New Architecture only). Add native packages with `npx expo install`.
- react-native-mmkv v4: `createMMKV()`, `storage.remove()`. FlashList v2: no `estimatedItemSize`.
- Tests: Jest via `jest-expo` + @testing-library/react-native v14 with `test-renderer` (`await render(...)`). Not Vitest.

## Before you say a task is done
1. `npx tsc --noEmit`
2. `npx expo lint`
3. `npx jest --ci`
4. `npx expo install --check`
5. For UI changes: run the matching Maestro flow in `.maestro/` and paste the result.

Skille. Expo publikuje oficjalne skille w expo/skills (2612 gwiazdek na GitHubie 26.09.2026); instalację dla każdego narzędzia opisuje strona o Expo. Callstack, firma konsultingowa specjalizująca się w React Native (skille społecznościowe, nie od Meta), publikuje produkcyjne skille, takie jak react-native-best-practices i upgrading-react-native, w callstackincubator/agent-skills. CLI skills (1.7.0), działające z wieloma agentami, instaluje je tak samo dla Claude Code, Codeksa i Cursora:

npx skills@latest add callstackincubator/agent-skills --skill react-native-best-practices

Skille ładują się tylko wtedy, gdy zadanie ich potrzebuje, więc kosztują mało kontekstu. Zobacz instalowanie skilli i zarządzanie nimi.

Serwery MCP. CLI Maestro ma wbudowany serwer MCP (maestro mcp), dzięki któremu agent w trakcie pracy stuka, przewija i sprawdza asercje na żywym emulatorze, symulatorze albo urządzeniu z Androidem. Buildy i symulatory iOS obsługuje MobileBuildMCP (dawniej XcodeBuildMCP), opisany na stronie MCP serwerów deweloperskich. Każdy serwer MCP dodaje swoją listę narzędzi do każdej sesji, więc podłączaj Maestro tylko w repozytorium aplikacji.

Claude Code

# after installing the Maestro CLI (Java 17+)
claude mcp add maestro -- maestro mcp

Codex

codex mcp add maestro -- maestro mcp

Cursor

Dodaj serwer do .cursor/mcp.json:

{
  "mcpServers": {
    "maestro": { "command": "maestro", "args": ["mcp"] }
  }
}

README Maestro (pobrane 26.09.2026) dokumentuje maestro mcp; powyższe linie dla poszczególnych klientów używają standardowej składni stdio każdego narzędzia. Jeśli twój klient potrzebuje dodatkowych opcji, sprawdź dokumentację konfiguracji MCP w Maestro.

Postaw szkielet aplikacji React Native z bramkami od pierwszego dnia

Poproś o środowisko testowe (harness) i bramki już w prompcie do szkieletu. Aplikacja, która startuje bez nich, nigdy ich nie dostaje, a każda późniejsza zmiana agenta jest wtedy nieweryfikowalna.

Prompt do skopiowania: szkielet weryfikowalnej aplikacji Expo

Scaffold a React Native app with `npx create-expo-app@latest` using the default
template (TypeScript, Expo Router). Then:
1. Add the tsconfig path alias `@/*` -> `src/*`.
2. Install `jest-expo`, `jest`, `@types/jest` with `npx expo install ... -- --dev`,
   plus `@testing-library/react-native` v14 and its peer `test-renderer` as dev dependencies,
   and configure Jest with the jest-expo preset.
3. Write one test that renders the home screen with `await render(...)` and asserts
   on visible text via `screen.getByText`.
4. Add package.json scripts: `typecheck` (tsc --noEmit), `lint` (expo lint), `test` (jest --ci).
5. Create `.maestro/smoke.yaml` that launches the app and asserts the home title is visible.
Do not run `expo prebuild` and do not commit `ios/` or `android/`.
Finish by running typecheck, lint, and test, and paste the output.

Prompt jest taki sam w każdym narzędziu; różni się tylko sposób wywołania. Zapisz powyższy prompt jako scaffold-prompt.txt i uruchom z nim agenta.

Claude Code

claude "$(cat scaffold-prompt.txt)"

Od wersji 2.1.283 (oba kanały wydań, stan na 2026-10-12) sesje interaktywne startują w trybie auto, w którym każdą akcję ocenia klasyfikator; sesje z ustawionym disableAutoMode, modele, których tryb auto nie obsługuje, oraz claude -p (z wyjątkiem zewnętrznych dostawców i wyłączonej telemetrii, gdzie od v2.1.285 startuje w trybie auto) startują w trybie Manual i pytają przed każdym poleceniem powłoki. W obu przypadkach instalacje npx są oczekiwane, a zapis poza projektem nie.

Codex

codex "$(cat scaffold-prompt.txt)"

Szkielet pobiera pakiety, więc zatwierdź żądania sieciowe, gdy Codex o nie zapyta. Nie uruchamiaj go z --dangerously-bypass-approvals-and-sandbox poza jednorazowym kontenerem z ograniczoną siecią.

Cursor

Wklej prompt do panelu agenta. Cursor uruchamia polecenia w swoim terminalu i pokazuje każdą edycję pliku do przeglądu. Trzymaj wynik terminala na widoku: wynik testów z ostatniego kroku jest twoim dowodem akceptacji.

Czysty React Native bez Expo (tzw. bare workflow, npx @react-native-community/cli@latest init) wybieraj tylko wtedy, gdy potrzebujesz kodu natywnego, którego nie wyrażą config plugins. Wtedy to ty utrzymujesz projekty ios/ i android/, a opisane niżej awarie dryfu natywnego stają się twoje.

Zbuduj warstwę danych offline-first, która przetrwa zabicie aplikacji

„Dodaj obsługę offline” daje wrapper na AsyncStorage, który gubi zakolejkowane zapisy. Nazwij silnik przechowywania, warstwę cache i wymaganie trwałości.

Prompt do skopiowania: TanStack Query offline-first z MMKV v4

Build an offline-first data layer with react-native-mmkv v4 and TanStack Query v5.
- Storage: `createMMKV({ id: 'query-cache' })`. Wrap it in a sync storage adapter
  (getItem/setItem/removeItem) and pass it to `createSyncStoragePersister`
  from @tanstack/query-sync-storage-persister.
- Wrap the app in `PersistQueryClientProvider`; in `onSuccess`, call
  `queryClient.resumePausedMutations()`.
- Wire `onlineManager.setEventListener` to @react-native-community/netinfo.
- Register every offline mutation with `queryClient.setMutationDefaults` so a
  paused mutation can resume after the app is killed (functions are not persisted).
- Example: `useAddTask` with an optimistic update and rollback in `onError`.
- Tests (jest-expo): (1) a mutation made offline is persisted and replays once when
  online; (2) a replayed mutation is not sent twice; (3) rollback restores the cache.
Run the tests and paste the output.

Kod spinający persister nie powinien być dłuższy niż ten poniżej. Jeśli agent pisze więcej, prawdopodobnie wymyśla persister od nowa:

import { createMMKV } from 'react-native-mmkv';
import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister';

const storage = createMMKV({ id: 'query-cache' });

export const persister = createSyncStoragePersister({
  storage: {
    getItem: (key) => storage.getString(key) ?? null,
    setItem: (key, value) => storage.set(key, value),
    removeItem: (key) => {
      storage.remove(key);
    },
  },
});

Agent najczęściej myli się w kwestii trwałości: co się stanie, gdy aplikacja zostanie zabita w trakcie synchronizacji i otwarta ponownie offline? Bez setMutationDefaults przywrócona mutacja nie ma funkcji do wywołania i po cichu nigdy się nie odtworzy. Test 1 z promptu pada dokładnie na tym błędzie i właśnie dlatego jest w prompcie. Jeśli potrzebujesz dwukierunkowej synchronizacji relacyjnej zamiast odtwarzanego cache’u, to decyzja o silniku synchronizacji (na przykład WatermelonDB); zanim poprosisz o nią agenta, potwierdź, że wybrana wersja wspiera Nową Architekturę.

Napraw FlatList, który zacina się na Androidzie

Zamiana najczęściej przewijanej listy na @shopify/flash-list ponownie wykorzystuje (recykluje) widoki wierszy zamiast montować osobny widok dla każdego wiersza. Wersja 2 zmieniła zasady: nie przyjmuje szacunków rozmiaru i działa tylko na Nowej Architekturze. Jak wcześniej, prowadzi osobną pulę recyklingu dla każdej wartości getItemType; v2 polega na niej bardziej, bo sama mierzy wiersze. Agent wytrenowany na v1 dodaje estimatedItemSize, którego v2 już nie potrzebuje.

Prompt do skopiowania: FlatList na FlashList v2

Convert the FlatList in src/screens/ProjectList.tsx to @shopify/flash-list v2
(install with `npx expo install @shopify/flash-list`).
- Do not add estimatedItemSize or any other v1 estimate prop.
- Wrap the row in React.memo, give it a stable keyExtractor, and memoize renderItem.
- Return getItemType for the three row kinds (header, project, ad) so each recycles
  into its own pool.
- Wire onEndReached to my useInfiniteQuery hook with cursor pagination.
- Before changing anything, list the props that forced re-renders in the old list.
- Update the RNTL test so it still asserts the first and last visible rows.
Run typecheck and tests and paste the output.

Zielony test dowodzi, że lista się renderuje, a nie że jest płynna. Aby udowodnić poprawę wydajności, zmierz build release na prawdziwym urządzeniu z Androidem ze średniej półki przed zmianą i po niej:

npx expo run:android --variant release
adb shell dumpsys gfxinfo com.example.app reset
# scroll the list for 20 seconds, then:
adb shell dumpsys gfxinfo com.example.app | grep -i "janky frames"

Zastąp com.example.app identyfikatorem swojej aplikacji. Wklej obie liczby do pull requesta. Jeśli wiersze różnych typów nie mają getItemType, v2 wstawia widok wysokiej karty w miejsce niskiego wiersza i widzisz miganie albo złe wysokości: to wersja v2 dawnego zacinania przy złym szacunku.

Dodaj bramkę biometryczną, która nie blokuje użytkowników

Face ID działa w symulatorze z włączonym Enrolled. Na prawdziwym telefonie bez zarejestrowanej biometrii albo po zbyt wielu nieudanych próbach naiwna bramka blokuje użytkownika. authenticateAsync z expo-local-authentication może się nie powieść, bo użytkownik anuluje, biometria nie jest zarejestrowana, brakuje sprzętu, użytkownik jest zablokowany albo monit wygasa.

Prompt do skopiowania: bramka biometryczna ze ścieżką awaryjną

Build a `useBiometricGate` hook with expo-local-authentication and expo-secure-store.
- Store the refresh token with `SecureStore.setItemAsync(key, token, { requireAuthentication: true })`.
- On app open: `hasHardwareAsync()`, `isEnrolledAsync()`, then `authenticateAsync()`.
- If hardware is missing, nothing is enrolled, the user cancels, or the user is
  locked out, route to the passcode screen. Never leave the user on a blank gate.
- If reading the token fails after a biometric change, clear it and ask for a normal
  sign-in rather than retrying in a loop.
- Tests (jest-expo, mock expo-local-authentication): one test per branch above,
  each asserting which screen the user lands on.
Run the tests and paste the output.

Testy jednostkowe dowodzą rozgałęzień. Potem sprawdź każdą platformę raz na fizycznym urządzeniu, bo symulator nie odtwarza blokady.

Zbuduj funkcję od początku do końca w krokach do przeglądu

Gdy budujesz funkcję od zera, prowadź agenta przez uporządkowane kroki zamiast jednego wielkiego promptu. Każdy krok kończy się bramką, więc akceptujesz go na podstawie dowodów i nigdy nie czytasz całego diffu na końcu.

1. Ekran i typy. „Create a ProjectList route with a typed useProjects() TanStack Query hook that returns mock data.” Bramka: npm run typecheck przechodzi.

2. Prawdziwe dane i każdy stan. „Replace the mock with a fetch to /api/projects. Add a loading skeleton, an empty state, and an error state with a Retry button that calls refetch().” Bramka: testy RNTL dla ładowania, wierszy, stanu pustego ([]) i ponowienia, uruchomione przez npm test.

3. Wydajność. Wklej prompt do FlashList. Bramka: liczby janky frames z gfxinfo przed zmianą i po niej, na buildzie release.

4. Zachowanie na urządzeniu. „Write .maestro/project-list.yaml that opens the list, scrolls to the end, and asserts the last row. Add an Android-only flow that runs setAirplaneMode: enabled, pulls to refresh, and asserts the error state and Retry.” Bramka: maestro test .maestro/ przechodzi. Polecenia trybu samolotowego w Maestro działają tylko na Androidzie, bo symulatory iOS go nie obsługują.

Jak zweryfikować wynik agenta w React Native bez czytania każdej linii?

Każda bramka odpowiada na jedno pytanie. Każ agentowi uruchomić wszystkie i dołączyć wynik do pull requesta: to ten sam pakiet dowodów, którego używa reszta serwisu.

Bramka	Polecenie	Czego dowodzi
Typy	npx tsc --noEmit	Nie wślizgnęło się API ze złej wersji głównej (new MMKV() tu pada)
Lint	npx expo lint	Reguły hooków i nieużywany kod
Testy jednostkowe i komponentów	npx jest --ci	Rozgałęzienia: odtwarzanie offline, ścieżki awaryjne biometrii, stany puste i błędu
Zgodność zależności	npx expo install --check	Żaden pakiet natywny nie odjechał od wersji przypiętej przez SDK
Zachowanie na urządzeniu	maestro test .maestro/	Nawigacja, gesty i stany offline w prawdziwym środowisku uruchomieniowym
Build release	npx expo run:ios --configuration Release, npx expo run:android --variant release	Ścieżka kodu, którą uruchamiają użytkownicy, z __DEV__ ustawionym na false
Wydajność	adb shell dumpsys gfxinfo <application-id>	Janky frames przed zmianą i po niej, na nazwanym urządzeniu

Kto zatwierdza. Programista, który zlecił zadanie, odpowiada za kryteria akceptacji i flow Maestro. Zmiana istniejącego flow lub testu wymaga zatwierdzenia przez drugą osobę, bo agent, który edytuje test, żeby przeszedł, usunął dowód; zobacz chroń wyrocznię. Macierze urządzeń i farmy urządzeń opisuje strona testowanie aplikacji mobilnych.

Prompt do skopiowania: zakończ zadanie z dowodami

Before you report this task done, run in order: `npx tsc --noEmit`, `npx expo lint`,
`npx jest --ci`, `npx expo install --check`, and `maestro test .maestro/` against the
running development build. Paste each command's last 20 lines. If any gate fails,
fix the code, not the test or the flow. If you believe a test or flow is wrong,
stop and explain why instead of editing it.

Debuguj błędy widoczne tylko w release za pomocą React Native DevTools

React Native DevTools to domyślny debugger dla aplikacji na Hermes; w React Native 0.76 zastąpił przepływ z Chrome DevTools. Naciśnij j w terminalu, w którym działa Metro lub Expo. Flipper nie jest odpowiedzią: jego README podaje v0.239.0 jako ostatnie wydanie ze wsparciem React Native. Reactotron (reactotron-react-native 5.3.1 na npm) to popularny dodatek do trwałych logów sieci i stanu.

Prompt do skopiowania: żądanie, które działa w dev, a nie w release

The app calls /api/sync on launch. It works in the development build but never
fires in a release build (`npx expo run:ios --configuration Release`).
1. Search for `__DEV__` checks, console-stripping Babel plugins, and environment
   variables read at build time on the path from app start to that request.
2. List the three most likely causes, ranked, with the file and line for each.
3. Add a log line that survives a release build (not console.log) and tell me
   exactly what to look for in React Native DevTools or the device log.
Do not change code until I confirm the cause.

Wysyłaj buildy React Native do TestFlight i Google Play

Na Expo natywną kompilację, dane uwierzytelniające i upload do sklepów obsługują EAS Build i EAS Submit; pipeline sterowany fingerprintem i etapowane aktualizacje over-the-air opisuje strona wzorce rozwoju Expo. W projekcie bez Expo sam podłączasz Fastlane do CI, a agent napisze dużo YAML-a. Ogranicz go:

Prompt do skopiowania: workflow release dla bare React Native

Create a GitHub Actions workflow that runs on version tags only. Jobs: build the iOS
app with Fastlane and upload to TestFlight; build an Android App Bundle with Gradle and
upload to the Play internal track. Requirements:
- `actions/checkout@v7` with `persist-credentials: false`, and an explicit
  top-level `permissions: contents: read`.
- Signing keys and store API keys come only from repository secrets; list each
  secret name I must create. Never echo a secret.
- Run typecheck, lint, and tests before any build step.
Explain each job in two sentences.

Zanim scalisz workflow, porównaj go z wzorcami pipeline’ów CI/CD. Nigdy nie pozwól agentowi uruchomić produkcyjnego uploadu, żeby przetestować workflow.

Co psuje się w React Native, czego symulator nigdy nie pokaże?

Uwaga

Metro serwuje nieaktualny kod. Edycje się nie pojawiają albo moduł, który istnieje, jest „not found”. Zanim zrobisz cokolwiek innego, zrestartuj przez npx expo start --clear (npx react-native start --reset-cache w bare React Native) i powiedz agentowi, że już to zrobiłeś, żeby nie odsyłał cię w kółko.

Dev i release zachowują się inaczej. W release __DEV__ ma wartość false, wywołania console mogą zostać usunięte, a zmienne środowiskowe czasu budowania mogą nie być ustawione. Odtwórz błąd na buildzie release, a potem użyj powyższego promptu do debugowania.

Stara biblioteka natywna wysypuje się przy starcie. React Native 0.82 usunął możliwość wyłączenia Nowej Architektury, więc biblioteka, która nigdy nie przeszła migracji, ulega awarii albo renderuje pusty ekran. Poproś agenta o sprawdzenie wsparcia biblioteki dla Nowej Architektury i znalezienie utrzymywanej wersji albo zamiennika. Downgrade React Native nie jest rozwiązaniem.

Buildy natywne dryfują. Ktoś podbija zależność natywną i na wszystkich innych maszynach build przestaje działać. Na Expo uruchom npx expo install --check, a potem npx expo prebuild --clean zamiast ręcznie edytować ios/ lub android/. W bare React Native uruchom cd ios && pod install --repo-update oraz cd android && ./gradlew clean.

Agent pisze API ze starszej wersji głównej. new MMKV(), storage.delete(), estimatedItemSize albo synchroniczne render() z RNTL 13. Sprawdzenie typów łapie pierwsze dwa; wskaż agentowi tabelę wersji i blok instrukcji projektu.

Testy E2E są niestabilne tylko w CI. Zwykle to kwestia timingu, a nie błąd. Poproś agenta, żeby zastąpił stałe opóźnienia oczekiwaniem na element, i potwierdź, że CI testuje ten sam artefakt buildu, który testowałeś lokalnie.

Dokąd dalej z React Native

• Wzorce rozwoju Expo: skille i MCP od Expo, bramki logowania w Expo Router, pipeline EAS i etapowane aktualizacje
• Receptury UI dla React Native i Fluttera: dwanaście promptów do UI z dowodami z urządzenia dla każdego
• Testowanie aplikacji mobilnych: Detox, Maestro i macierze urządzeń
• Receptury natywne: iOS i Android: gdy funkcja wymaga Swifta lub Kotlina
• Wzorce rozwoju Fluttera: jeśli rozważasz Darta zamiast React Native