Wzorce rozwoju Expo

Praca z Expo w Claude Code, Codeksie lub Cursorze działa, gdy agent zna dwa fakty, zanim napisze kod: przypiętą wersję Expo SDK (26.09.2026 aktualne na npm jest SDK 57) oraz to, czy aplikacja działa w Expo Go, czy w development buildzie. Dodaj oficjalne skille Expo, pipeline EAS sterowany fingerprintem i flow Maestro, a każdą zmianę zweryfikujesz bez czytania każdej linii.

Ta strona jest dla programistów i liderów technicznych, którzy wypuszczają aplikację Expo do sklepów. Ktoś z zespołu dodaje react-native-vision-camera, Expo Go przestaje ładować aplikację, a agent dalej pisze kod pod ten wariant, który akurat zgadł. Tydzień później aktualizacja over-the-air (OTA) melduje sukces, a żaden telefon jej nie pobiera, bo jest przeznaczona dla wersji runtime, której nie ma żaden zainstalowany build.

Zanim zaczniesz: strona zakłada podstawy React Native (nawigacja, stan, moduły natywne) z wzorców rozwoju React Native oraz agenta, który potrafi instalować skille, jak opisuje tekst o tym, jak instalować skille i nimi zarządzać.

Co skonfigurujesz na tej stronie

• Konfigurację agenta z oficjalnymi skillami Expo i serwerem MCP, instalowaną osobno dla każdego narzędzia
• Prompt do szkieletu aplikacji, który przypina SDK i typ buildu, żeby agent przestał zgadywać
• Gotowy prompt na bramkę logowania w Expo Router oraz flow Maestro, który dowodzi, że działa
• Pipeline EAS Workflows sterowany fingerprintem, który sam decyduje: build do sklepu czy aktualizacja OTA
• Etapowe wdrażanie OTA z poleceniami do obserwacji i wycofania
• Mapę awarii: aktualizacje SDK, rozjazd Expo Go, poświadczenia i niedopasowany runtime

Jakie wersje Expo zakłada ta strona?

Podaj agentowi wersje. Jego dane treningowe obejmują kilka SDK, a każde SDK zmienia API, klucze konfiguracji i wersję React Native pod spodem. Tabela pokazuje, co npm serwował 26.09.2026.

Pakiet	Wersja 26.09.2026	Uwaga
expo	57.0.25 (SDK 57, wydane 30.06.2026)	dist-tag sdk-56 nadal dostaje poprawki; SDK 58 jest na dist-tagu next, więc przed przypięciem sprawdź npm view expo dist-tags
react-native / react	0.86.3 / 19.2.3	wersje przypięte w bundledNativeModules.json SDK 57
expo-router	57.0.23	Stack.Protected przyjmuje prop guard
eas-cli	24.8.0	polecenia fingerprint, workflow i rolloutu aktualizacji używane niżej
nativewind	4.2.7	5.0 to release candidate (5.0.0-rc.0); przypnij jedną wersję główną

Nie pozwalaj agentowi wpisywać wersji do package.json ręcznie. npx expo install <pakiet> wybiera wersję zgodną z twoim SDK, a npx expo install --check wypisuje każdy pakiet, który się rozjechał.

Skonfiguruj skille Expo i serwer Expo MCP

Expo publikuje własne skille dla agentów w expo/skills (około 2,6 tys. gwiazdek na GitHubie 26.09.2026). Plugin Expo dla Claude Code i Codeksa (1.13.7 na 26.09.2026) zawiera 24 skille, m.in. expo-router, expo-upgrade, eas-update i eas-workflows. Rejestruje też zdalny serwer MCP Expo pod adresem https://mcp.expo.dev/mcp. Skille ładują się na żądanie, więc kosztują mało kontekstu, dopóki zadanie ich nie potrzebuje. Serwery MCP kosztują kontekst za każde narzędzie. Claude Code i Codex odkładają definicje narzędzi za mechanizmem tool search, więc koszt jest tam niższy, ale każdy podłączony serwer nadal go zwiększa.

Claude Code

# Skille + serwer Expo MCP w jednym pluginie
claude plugin install expo@claude-plugins-official

Aby dodać sam serwer MCP, uruchom claude mcp add --transport http expo https://mcp.expo.dev/mcp, a potem otwórz /mcp w sesji i dokończ logowanie, jeśli serwer o nie poprosi. Bez --transport http Claude Code 2.1.283 zapisuje URL jako polecenie stdio i połączenie pada dopiero później.

Codex

# Skille + serwer Expo MCP w jednym pluginie
codex plugin add expo@openai-curated

Aby dodać sam serwer MCP, uruchom codex mcp add expo --url https://mcp.expo.dev/mcp, a potem codex mcp login expo, jeśli serwer poprosi o OAuth. Nie rób obu rzeczy naraz: plugin już rejestruje ten serwer.

Cursor

Zainstaluj skille wieloagentowym CLI do skilli (skills 1.7.0 na npm):

npx skills@latest add expo/skills --skill '*' -a cursor

Następnie dodaj serwer MCP do .cursor/mcp.json:

{
  "mcpServers": {
    "expo": { "url": "https://mcp.expo.dev/mcp" }
  }
}

Pułapki pluginu Expo

• Skille eas-* obsługują płatne Expo Application Services (EAS). Każdy zaczyna się od uwagi o kosztach. Build, submit czy uruchomienie workflow zużywa minuty z twojego planu, więc trzymaj te polecenia za swoją akceptacją.
• Plugin instaluje hooki PostToolUse i UserPromptExpansion, które rejestrują użycie skilli (tylko w Claude Code). Plugin 1.13.7 nic nie wysyła, dopóki nie włączysz telemetrii przez EXPO_SKILLS_TELEMETRY=1; EXPO_SKILLS_TELEMETRY=0 albo DO_NOT_TRACK=1 ją wyłącza.
• Instalacja wszystkich skilli przez --skill '*' jest w porządku w repozytorium Expo. W monorepo z aplikacją webową instaluj tylko te, których używasz. Opisy skilli konkurują o uwagę agenta.

Porównanie skilli i serwerów MCP znajdziesz w tekście o tym, jak instalować skille i nimi zarządzać, oraz w przeglądzie skilli frontendowych.

Postaw szkielet aplikacji Expo, którego agent nie zrozumie opacznie

Prompt znaczy mniej niż dwa fakty, które przypina. Zapisz je też w AGENTS.md (lub CLAUDE.md), żeby każda kolejna sesja je dziedziczyła.

Prompt do skopiowania: szkielet aplikacji Expo SDK 57

Scaffold a new Expo SDK 57 app with `npx create-expo-app@latest` (TypeScript).
Constraints:
- We ship a development build, not Expo Go: add expo-dev-client, because we
  will add third-party native modules.
- Use Expo Router with typed routes.
- Create eas.json with development (developmentClient: true, internal
  distribution), preview (internal), and production profiles.
- In app.json set "runtimeVersion": { "policy": "fingerprint" }.
- Install every dependency with `npx expo install`, never by editing
  package.json versions.
- Write an AGENTS.md that states: Expo SDK 57, development build, package
  manager, and the check command below.
- Run `npx expo lint` once to set up eslint-config-expo, and install
  jest-expo with `npx expo install jest-expo jest`, before you add the
  check script.
- Add a "check" script to package.json:
  tsc --noEmit && expo lint && jest --ci && expo install --check
Stop and show me eas.json and app.json before running any `eas` command.

Polityka runtime version fingerprint przyda się później. Liczy hash wszystkiego, co natywne w projekcie, więc każda zmiana natywna sama tworzy nową wersję runtime. To usuwa najczęstszy wypadek przy OTA: aktualizację JavaScriptu, która woła moduł natywny, którego zainstalowany build nie ma.

Claude Code

Uruchom claude --permission-mode manual w pustym katalogu i wklej prompt. Skill expo-overview kieruje zadanie do expo-project-structure i expo-dev-client. W trybie Manual każde polecenie eas czeka na twoją zgodę. Od wersji 2.1.283 (kanał latest) Claude Code startuje sesje interaktywne w trybie auto, w którym polecenia zatwierdza za ciebie klasyfikator.

Codex

Uruchom codex w pustym katalogu i wklej prompt. Żeby Codex edytował pliki i uruchamiał lokalne polecenia, ale pytał przed wszystkim poza workspace’em, uruchom go przez codex --sandbox workspace-write -a on-request.

Cursor

Wklej prompt do czatu Agent. Przejrzyj diff eas.json i app.json, zanim zaakceptujesz zmianę: te dwa pliki decydują o każdym kolejnym buildzie.

Expo Go czy development build?

Expo Go uruchamia tylko moduły natywne, które ma w sobie. Gdy tylko dodasz zewnętrzny moduł natywny albo config plugin, aplikacja potrzebuje development buildu (npx expo run:ios, npx expo run:android lub eas build --profile development). Jeśli agent nie wie, którego wariantu używasz, pisze kod działający w Expo Go i padający w development buildzie albo odwrotnie.

Zbuduj layout Expo Router chroniony logowaniem

Większość błędów w Expo Router siedzi w bramce logowania. Przekierowanie przed zamontowaniem głównego layoutu daje ostrzeżenie „navigate before mounting the Root Layout”. Przekierowanie w renderze na jedną klatkę pokazuje chronioną treść. Stack.Protected usuwa oba problemy, bo router w ogóle nie rejestruje chronionych ekranów, dopóki strażnik zwraca fałsz.

Prompt do skopiowania: zakładki za logowaniem ze Stack.Protected

Build the auth layout for this Expo SDK 57 app with Expo Router.
- app/_layout.tsx: a SessionProvider (React context, `useSession`) that loads
  the token from expo-secure-store. Keep the splash screen up with
  SplashScreen.preventAutoHideAsync() until the token has loaded.
- Gate routes with <Stack.Protected guard={isSignedIn}> around the (tabs)
  group and <Stack.Protected guard={!isSignedIn}> around the (auth) group.
- Do not call router.replace or <Redirect> in render or in a useEffect.
- (auth): login.tsx. (tabs): index.tsx and profile.tsx with a sign-out button.
- Add testID props: login-email, login-password, login-submit, tab-profile,
  sign-out.
- Write a Maestro flow in .maestro/auth.yaml that signs in, opens the
  profile tab, signs out, and asserts that the login screen is visible again.
Show the file tree first, then the files. Run `npm run check` at the end.

Agent powinien wygenerować takie drzewo:

app/
  _layout.tsx        # SessionProvider + strażnicy Stack.Protected
  (auth)/
    _layout.tsx
    login.tsx
  (tabs)/
    _layout.tsx      # Tabs
    index.tsx
    profile.tsx
.maestro/
  auth.yaml

Nie musisz czytać layoutu, żeby go przyjąć. Wyszukaj w nim router.replace i <Redirect: trafienie w ścieżce renderowania oznacza, że wraca migotanie przy przekierowaniu, więc odeślij kod z poleceniem „move the guard into Stack.Protected”. Potem uruchom flow Maestro na symulatorze z zainstalowanym development buildem (maestro test .maestro/auth.yaml). Flow jest kryterium akceptacji: logowanie, chroniona zakładka i wylogowanie albo przechodzą na prawdziwym runtime, albo nie.

CLI Maestro instalujesz raz na maszynę poleceniem curl -fsSL "https://get.maestro.mobile.dev" | bash z README Maestro (gałąź main repozytorium ustawia 26.09.2026 wersję CLI 2.11.0). Wymaga Javy 17 lub nowszej, a maestro test potrzebuje uruchomionego symulatora lub emulatora z już zainstalowanym development buildem.

Trzymaj style w jednym motywie z NativeWind

Typowa porażka z NativeWind to ściana wartości className="bg-[#1d4ed8]". Rebranding dotyka wtedy każdego ekranu. Poproś o semantyczne tokeny, żeby kolory żyły w jednym miejscu.

Prompt do skopiowania: typowany motyw NativeWind

Configure NativeWind (keep the major version already in package.json) for
this Expo SDK 57 app. Define primary, surface, and danger as CSS variables in
global.css with light and dark values, and map them in tailwind.config.js so
`bg-primary` follows the colour scheme. Build a typed
<Button variant="primary" | "danger" loading?> on Pressable with a pressed
opacity state. Then add a lint check: fail `npm run check` if any file under
app/ or components/ contains a hex colour literal in a className.

Ostatnie zdanie zamienia regułę stylu w bramkę. Przestajesz przeglądać kolory wzrokiem, bo sprawdzenie pada na pierwszej wpisanej na sztywno wartości hex. Więcej przepisów na UI w React Native i Flutterze zebraliśmy w recepturach UI dla urządzeń mobilnych.

Wydawaj przez pipeline EAS sterowany fingerprintem

Najbardziej ryzykowna decyzja w wydaniu Expo brzmi: „build do sklepu czy aktualizacja OTA?”. Agent nie powinien jej podejmować na wyczucie. eas-cli 24.8.0 zawiera szablon workflow do wdrożeń, który podejmuje ją mechanicznie: eas workflow:create zapisuje go domyślnie jako .eas/workflows/deploy.yml, na wzór przykładu deploy-to-production z dokumentacji Expo. Job fingerprint liczy hash projektu natywnego, a job get-build szuka istniejącego buildu produkcyjnego z tym hashem. Jeśli taki jest, workflow publikuje aktualizację. Jeśli nie, buduje aplikację i wysyła ją do sklepów.

Prompt do skopiowania: workflow EAS dla produkcji

Use the eas-workflows skill. Start from the `eas workflow:create` deploy
template and save it as .eas/workflows/deploy.yml, triggered on pushes to main:
1. a `fingerprint` job;
2. per platform, a `get-build` job with the fingerprint hash and the
   production profile;
3. if no build matches: a `build` job, then a `submit` job;
4. if a build matches: an `update` job on branch production.
Also create .eas/workflows/pull-request.yml that runs `npm run check` and
publishes a preview update to a branch named after the PR.
Validate both files with `npx eas-cli@latest workflow:validate <path>` and
show me the output. Do not run `eas workflow:run`, `eas build`, or
`eas submit`.

Pipeline weryfikujesz bez czytania każdego klucza YAML:

1. workflow:validate przechodzi dla obu plików.
2. Plik produkcyjny zawiera joby typu fingerprint, get-build, build, submit i update, a warunek if: każdego joba update sprawdza, czy jego job get-build zwrócił build_id. Szukaj po type:, a nie po nazwach jobów: szablon nazywa je get_ios_build, build_android i tak dalej.
3. Zanim scalisz zmianę, która wygląda na natywną, porównaj drzewo robocze z ostatnim buildem produkcyjnym. Identyfikator buildu da ci eas build:list --platform ios --build-profile production --limit 1 --json, a potem uruchom eas fingerprint:compare --build-id <BUILD_ID> (w CI dodaj --non-interactive). Dla Androida powtórz eas build:list z --platform android i porównaj z tym identyfikatorem buildu. Samo eas fingerprint:compare otwiera interaktywny wybór, więc agent ani krok CI nie uruchomią go bez nadzoru. Inny hash oznacza, że następny push uruchomi build do sklepu, a nie aktualizację OTA.

Jeśli twój zespół używa GitHub Actions, zachowaj tę samą logikę decyzji i każ agentowi najpierw przeczytać istniejące workflow przez serwer GitHub MCP. Ogólne wzorce pipeline’ów opisuje strona o pipeline’ach CI/CD z agentami.

Wdrażaj aktualizację OTA etapami

Aktualizacja OTA dociera do każdego użytkownika kanału w kilka minut, więc wydawaj ją tak jak zmianę na serwerze: najpierw na wycinek ruchu.

1. Opublikuj aktualizację dla 10% użytkowników na gałęzi production:

   eas update --branch production --message "Fix checkout total rounding" --rollout-percentage 10

2. Obserwuj uruchomienia i crashe grupy aktualizacji:

   eas update:insights <GROUP_ID> --days 1

3. Jeśli liczby zgadzają się z poprzednią aktualizacją, rozszerz rollout przez eas update:edit <GROUP_ID> --rollout-percentage 100.

4. Jeśli crashy przybywa, cofnij rollout przez eas update:revert-update-rollout albo wróć do wcześniejszej aktualizacji lub wbudowanego bundla przez eas update:rollback.

GROUP_ID to identyfikator grupy aktualizacji, który wypisuje eas update. Przekaż agentowi tę sekwencję jako runbook, a nie jako pozwolenie. Agent może przygotować polecenia i odczytać update:insights, a każde rozszerzenie rolloutu zatwierdza człowiek. Ogólny wzorzec opisuje strona o stopniowym wdrażaniu (progressive delivery).

Podłącz powiadomienia push od początku do końca

Agenci zwykle kończą na prośbie o uprawnienia. Działająca konfiguracja wysyła też token do backendu, odświeża go i kieruje dotknięte powiadomienie na właściwy ekran.

Prompt do skopiowania: powiadomienia push w Expo od początku do końca

Implement push notifications with expo-notifications in this Expo SDK 57 app
(development build).
- On sign-in, get a token with getExpoPushTokenAsync (pass the EAS projectId
  from expo-constants) and POST it to /api/devices; register again when the
  token changes and delete it on sign-out.
- Call Notifications.setNotificationHandler so banners show in the
  foreground.
- Create the Android notification channel before requesting the token.
- Use useLastNotificationResponse to deep-link a tapped notification with
  data.url to that Expo Router route, including a cold start.
- Add a Jest test for the URL-to-route mapping and a Maestro flow that opens
  the app from a deep link and asserts the target screen.
List any credentials I must add in EAS (APNs key, FCM service account)
instead of guessing them.

Test w Jest dowodzi mapowania z payloadu na trasę. Flow Maestro dowodzi, że trasa otwiera się na urządzeniu. Samo doręczenie nadal wymaga jednej ręcznej wysyłki na fizyczne urządzenie dla każdej platformy, bo symulatory nie odtwarzają każdej ścieżki push.

Jak zweryfikować wynik agenta bez czytania każdej linii

Expo daje dość sygnałów sprawdzalnych maszynowo, żeby review stało się sprawdzeniem dowodów, a nie kodu.

Bramka	Polecenie	Co wyłapuje
Typy, lint, testy jednostkowe	npm run check (tsc --noEmit, expo lint, jest --ci)	złe kształty API, martwe importy, regresje w logice
Rozjazd zależności	npx expo install --check i npx expo-doctor	wersje spoza zakresu SDK, zduplikowane moduły natywne
Zmiana natywna	eas fingerprint:compare --build-id <BUILD_ID> --non-interactive	PR „tylko w JavaScripcie”, który zmienił runtime
Zachowanie	flow Maestro w .maestro/	bramki logowania, deep linki i nawigacja na prawdziwym runtime
Kondycja wydania	eas update:insights i Sentry	crashe i nieudane uruchomienia na grupę aktualizacji

Każ agentowi dołączać wynik każdej bramki do pull requesta. Recenzent czyta wtedy, co zmieniło się w zachowaniu, wynik Maestro i to, czy fingerprint się przesunął. To ten sam pakiet dowodów, którego używa reszta serwisu. Przy analizie crashy config plugin @sentry/react-native wysyła source mapy podczas buildów EAS, a serwer Sentry MCP (https://mcp.sentry.dev/mcp) pozwala agentowi samodzielnie przeczytać zsymbolizowany stack trace. Testy na urządzeniach wykraczające poza Maestro, takie jak farmy urządzeń i kontrole wizualne, opisuje strona o testowaniu aplikacji mobilnych.

Co psuje się w projektach Expo i jak z tego wyjść?

• Aktualizacja SDK zostawia zależności natywne w tyle. Podbicie expo to łatwa część. Uruchom npx expo-doctor, wklej cały wynik i użyj promptu: „We upgraded to Expo SDK 57. Use the expo-upgrade skill. Fix each mismatch with npx expo install --fix, and list every third-party package with no SDK 57 support instead of forcing a version.” Potem przebuduj development client, bo stary już nie pasuje.
• Działa w Expo Go, a nie działa w development buildzie, albo odwrotnie. Przyczyną prawie zawsze jest moduł, którego nie ma w Expo Go, albo config plugin stosowany tylko podczas prebuild. Powiedz agentowi, które środowisko pada, i poproś, by sprawdził, czy moduł wymaga wpisu config pluginu w app.json i nowego development buildu.
• eas build pada na podpisywaniu. Wklej log buildu i poproś agenta, by wskazał wadliwe poświadczenie, na przykład wygasły certyfikat dystrybucyjny albo brakujący klucz push. Nie pozwól mu generować poświadczeń na nowo: eas credentials zmienia współdzielony stan podpisywania całego zespołu, więc uruchamia je człowiek.
• Aktualizacja „się udała”, ale żadne urządzenie jej nie dostało. Runtime version aktualizacji nie pasuje do żadnego zainstalowanego buildu. Pobierz identyfikator ostatniego buildu ze sklepu przez eas build:list --platform ios --build-profile production --limit 1 --json i uruchom eas fingerprint:compare --build-id <BUILD_ID>. Jeśli hashe się różnią, zmiana wymaga buildu do sklepu, a workflow sterowany fingerprintem by go wygenerował.
• Zła aktualizacja jest już na produkcji. Uruchom eas update:revert-update-rollout, jeśli wciąż trwa etapowy rollout, a w przeciwnym razie eas update:rollback. Potem dodaj flow Maestro, który odtwarza błąd, żeby następny pull request padł, zanim trafi do użytkowników.

Następne kroki

• Wzorce rozwoju React Native: nawigacja, stan offline, wydajność list i moduły natywne bez usług Expo
• Receptury natywne: iOS i Android, gdy schodzisz do Swifta lub Kotlina po własny moduł
• Wzorce programowania we Flutterze, jeśli porównujesz stosy wieloplatformowe
• Wzorce projektowania API dla endpointu /api/devices i API synchronizacji, z którego korzysta aplikacja