Skip to content

chore: upgrade to Expo SDK 58 - #172

Open
fernandatoledo wants to merge 10 commits into
masterfrom
chore/expo-sdk-58
Open

fernandatoledo wants to merge 10 commits into
masterfrom
chore/expo-sdk-58

Conversation

@fernandatoledo

@fernandatoledo fernandatoledo commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

What does this do?

Upgrades the template from Expo SDK 54 to SDK 58 (React Native 0.88, React 19.3, TypeScript 6, Jest 30).

Dependencies

  • expo install --fix aligned every Expo-managed package with SDK 58. Notable majors: react-native-gesture-handler 3, react-native-webview 14, react-native-reanimated 4.7, react-native-worklets 0.13.
  • react-native-mmkv 4.0 → 4.3 and react-native-nitro-modules 0.31 → 0.37. Expo doesn't manage these, and the old versions crash at startup on RN 0.88 ("Failed to install Nitro"). MMKV 4.3 reads data written by 4.0, verified on an existing Android install.
  • Removed react-native-edge-to-edge (flagged as unmaintained by expo-doctor; edge-to-edge is built into RN now). FocusAwareStatusBar now renders expo-status-bar plus expo-navigation-bar, so both system bars follow the theme as SystemBars did.
  • jest-environment-jsdom 30, ts-jest 29.4 (supports Jest 30), and @types/node declared explicitly.

Config

  • iOS deployment target 16.0 → 16.4 (required by SDK 58).
  • Removed newArchEnabled (default) and the explicit Reanimated Babel plugin (babel-preset-expo adds the worklets plugin).
  • tsconfig: dropped baseUrl (deprecated in TS 6) and set types: ["jest", "node"] (TS 6 no longer auto-includes @types). nativewind-env.d.ts now references expo/types so a freshly generated project (no expo-env.d.ts yet) still type-checks.
  • Node 22: .nvmrc → v22.14.0 and the EAS "Validate new version" step reads it instead of hard-coding Node 20 (Expo 58 / RN 0.88 require ^22.13.0).
  • ESLint and Jest ignore .claude/worktrees/ so local Claude Code worktrees don't break pnpm lint / pnpm test.
  • Jest uses Reanimated's official resolver (react-native-reanimated/jest/resolver) so Reanimated 4.7 / Worklets 0.13 load their JS implementations in tests.

Code

  • @react-navigation/* imports moved to expo-router entry points (required since SDK 56); unstable_settings.initialRouteName → anchor.
  • Stack.Protected guards now have an explicit redirectTo, computed by getFallbackRoute (unit-tested for every onboarding/auth state). In SDK 58 a failed guard with no redirectTo falls back to the first unguarded route by file order, which sent users to www ("Invalid Url") instead of onboarding.
  • iOS 26+ stack headers are now transparent (Liquid Glass) by default, so content rendered under the header. Forgot Password, Sign Up and Update Password now use a ScrollView with contentInsetAdjustmentBehavior="automatic", wrapped in keyboard-controller's KeyboardAvoidingView with automaticOffset (without it the offset is measured relative to the parent, so on Android the opaque header height was missing and the keyboard covered the last field); the www WebView gets the same inset behavior.
  • Ref and style typings updated for RN 0.88's stricter generated types.

Why did you do this?

Keep the template on a supported SDK. SDK 55 and 56 were skipped on purpose: SDK 55 with Hermes V1, SDK 56, and SDK 57 before 57.0.9 have a Hermes V1 memory regression with Reanimated/Worklets.

Who/what does this impact?

  • Xcode 27.1 is required for iOS builds. SDK 58 needs the Swift 6.4 compiler (Xcode 26.x fails in expo-modules-jsi), and expo-dev-launcher 58.0.21 doesn't compile on Xcode 27.0: it calls axisBehavior, an iOS 27.1 SDK API, behind #if compiler(>=6.4), which Xcode 27.0 passes while shipping the iOS 27.0 SDK. Xcode 27.1 needs macOS Tahoe 26.6+.
  • Node 22.13+ is required locally and in CI.
  • iOS 16.0–16.3 users can no longer install apps built from the template.
  • Projects created from the template inherit the Liquid Glass header behavior. Screens with a native stack header need a ScrollView with automatic content insets, or headerTransparent: false.

Risk: risk:high

Large dependency jump (4 SDKs, RN 0.81 → 0.88), native modules, and auth routing guards.

How did you test this?

  • Merged latest master (analytics). pnpm type-check, pnpm lint, pnpm lint:translations and pnpm test (178 tests) pass; expo-doctor 20/20.

  • Generated a new project from this branch with the local CLI (cli-runner/run-local-cli.js, cloning the branch, not the published package): install, type-check and lint pass; built and smoke-tested on iOS and Android (onboarding fallback, validation, Sign Up layout and keyboard, MMKV persistence, analytics screen events).

  • iOS bundle and Android bundle export.

  • Tested on iOS (iPhone 17 Pro simulator, iOS 27, clean build with Xcode 27.1 and unmodified dependencies): fresh install → onboarding → sign in; MMKV persistence across restarts; empty-form validation; Forgot Password and Sign Up below the header; Sign Up keyboard.

  • Tested on Android (Pixel 8 emulator, Android 14): launch; existing MMKV data read; onboarding → sign in; validation; Sign Up layout and keyboard (focused field stays above the keyboard).

  • Tested on a small device

  • Tested on a real device

  • Tested all flows related with this PR changes. Logged-in screens weren't reachable (no backend in .env).

  • Tested accessibility

  • Added tests

Compared against master built with the same Xcode and simulator to confirm the header overlap was introduced by SDK 58.


Notes:

  • Known issue – KeyboardAwareScrollView: with keyboard-controller 1.22.7 (Expo's pinned version) and Reanimated 4.7, its worklet handlers don't attach ("view tag can not be resolved"), so it doesn't react to the keyboard. modal-keyboard-aware-scroll-view (bottom sheets) is likely affected; not verified on device. 1.23.1 doesn't change that code path.
  • progress-bar.test.tsx types getAnimatedStyle locally: Reanimated 4.7 exposes the native signature only in its .native.d.ts, so TypeScript picks the web stub.
  • Android navigation bar checked with 3-button navigation in light and dark mode.
  • Pre-existing, unchanged here: header titles show raw route names (forgot-password, sign-up); Sign Up reuses the "Password" label for the confirmation field; the "Forgot Password" link on Sign In is nearly invisible in dark mode.

🤖 Generated with Claude Code

- Bump Expo to SDK 58 (RN 0.88, React 19.3, TypeScript 6) and align native deps
- Raise iOS deployment target to 16.4 (required by SDK 58)
- Bump react-native-mmkv to 4.3 and nitro-modules to 0.37 (old ones crash on RN 0.88)
- Replace react-native-edge-to-edge with expo-status-bar (edge-to-edge is built in)
- Move @react-navigation imports to expo-router entry points
- Add explicit redirectTo on Stack.Protected guards (SDK 58 changed the fallback)
- Adopt iOS 26 transparent headers: header screens use ScrollView with content insets
- Fix RN 0.88 strict types for refs and styles
- Update Jest setup for Jest 30, Reanimated 4.7 and Worklets 0.13
- Use Reanimated's official Jest resolver instead of mocking private paths
- Restore the progress bar test that checks setProgress updates the width
- Extract the guard fallback route and cover every auth/onboarding state
- Style the Android navigation bar with expo-navigation-bar
- Use contentContainerClassName in the sign-up form
@fernandatoledo
fernandatoledo requested a review from a team as a code owner November 18, 2026 21:49
@fernandatoledo fernandatoledo added the risk:high Auth, payments, migrations, security-sensitive code. label Nov 18, 2026
@fernandatoledo
fernandatoledo requested review from amaury901130 and asdolo and a balanced review from Copilot November 18, 2026 21:49

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The unchanged .nvmrc selects Node 20 for the documented setup, but the upgraded Expo 58 and React Native 0.88 packages require a newer supported runtime.

1 open issue
What changed in this PR

Overall Review: ai:serious

Upgrades the mobile template from Expo SDK 54 to SDK 58, adapting its navigation, native UI, TypeScript types, and test tooling.

Changes:

  • Updates Expo, React Native, React, and development dependencies; raises the iOS minimum to 16.4.
  • Adds explicit guard redirects and adjusts forms and WebView content for transparent headers.
  • Migrates system bars and navigation imports, updates component typings, and adapts tests.
File Description
tsconfig.json Removes baseUrl and explicitly includes Jest and Node types.
src/​lib/​use-theme-config.tsx Moves theme imports to Expo Router entry points.
src/​lib/​test-utils.tsx Removes the standalone navigation container from test wrappers.
src/​lib/​auth/​get-fallback-route.ts Selects fallback routes from onboarding and authentication state.
src/​components/​ui/​text.tsx Uses inferred flattened style types.
src/​components/​ui/​modal-keyboard-aware-scroll-view.tsx Uses inferred animated component types.
src/​components/​ui/​input.tsx Updates the input ref type.
src/​components/​ui/​focus-aware-status-bar.tsx Replaces edge-to-edge system bars with Expo components.
src/​components/​ui/​button.tsx Updates the button ref type.
src/​components/​sign-up-form.tsx Adds automatic scroll insets and changes keyboard avoidance.
src/​components/​settings/​item.tsx Updates the settings item ref type.
src/​components/​forgot-password-form.tsx Adds scrolling, automatic insets, and keyboard padding.
src/​app/​www.tsx Enables automatic WebView content insets.
src/​app/​update-password.tsx Adds scrolling, automatic insets, and keyboard padding.
src/​app/​_layout.tsx Migrates navigation imports and adds explicit guard redirects.
package.json Upgrades the SDK, native modules, and development tooling.
jest.config.js Adds the Reanimated resolver, transform support, and worktree exclusions.
eslint.config.mjs Excludes local Claude worktrees from linting.
babel.config.js Removes the explicit Reanimated plugin.
app.config.ts Raises the iOS minimum and removes obsolete configuration.
AGENTS.md Updates documented dependency compatibility versions.
__tests__/​lib/​auth/​get-fallback-route.test.ts Covers all onboarding and authentication state combinations.
__tests__/​components/​ui/​progress-bar.test.tsx Adds a local animated-style helper type.
__tests__/​components/​settings/​item.test.tsx Simplifies the press-event target.

Review effort: Balanced

Comment thread package.json Resolved
# Conflicts:
#	package.json
#	pnpm-lock.yaml
#	src/app/_layout.tsx
#	src/lib/test-utils.tsx
@github-actions

Copy link
Copy Markdown

✅ Good news! We ran Expo Doctor for this PR and everything looks good, Great job!

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

💯 Test Coverage

Lines Statements Branches Functions
Coverage: 62%
62.04% (456/735) 62.91% (207/329) 57.77% (171/296)

😎 Tests Results

Tests Skipped Failures Errors Time
178 0 💤 0 ❌ 0 🔥 31.925s ⏱️
👀 Tests Details • (62%)
File% Stmts% Branch% Funcs% LinesUncovered Line #s
All files62.0462.9157.7762.25 
src/app0000 
   _layout.tsx000025–134
   www.tsx000011–39
src/app/(app)37.544.442037.5 
   _layout.tsx70.5810037.570.5817–29, 83
src/components97.510087.597.5 
   sign-up-form.tsx10010075100 
src/components/ui72.9471.2269.6972.56 
   button.tsx100100100100 
   input.tsx100100100100 
   select.tsx77.7767.8573.3377.14180, 230–251
   text.tsx1008010010034
src/lib707571.4277.77 
   test-utils.tsx88.8810080100 

Expo 58 and React Native 0.88 require Node ^22.13.0.
Point .nvmrc at v22.14.0 and have the EAS version check read it
instead of hard-coding Node 20.
KeyboardAvoidingView measured its position relative to its parent, so on
Android the opaque stack header height was missing from the padding and
the keyboard covered the last Sign Up fields. automaticOffset reads the
view's position in the window instead.
@fernandatoledo fernandatoledo added the ai:minor Style issues, minor suggestions label Nov 20, 2026
Keeps CI on the same Node version as local development and the EAS version check.

@devs-rootstrap devs-rootstrap left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 AI review by Mate, requested by Fernanda Toledo in Slack (thread) and published by Guillermo Machado. It only comments: a person decides.

Re-review at 9b110a5. The only new commit makes setup-node-pnpm-install read .nvmrc, which resolves the Node version consistency point.

Still open:

  1. Logged-in flows are untested. The guards now use redirectTo and the (app) tab bar picks up the SDK 58 Liquid Glass defaults, but the checklist still notes logged-in screens weren't reachable. Please smoke-test on iOS 26+ the tabs, Settings, Update Password, and sign-out (authenticated → unauthenticated should land on /sign-in), even with a mocked API.
  2. ModalKeyboardAwareScrollView ships broken. The known keyboard-controller 1.22.7 / Reanimated 4.7 issue means generated projects inherit a non-working component silently. Either bump keyboard-controller to a working version, or document the limitation in the component and track it in a follow-up issue.
  3. Minor: the .claude/worktrees/ ignores in ESLint/Jest are local tooling that every generated project will inherit.

Also, the gatekeeper check is currently failing and layer4-gatekeeper is pending.

Comment thread src/app/_layout.tsx
</Stack.Protected>

<Stack.Protected guard={isAuthenticated}>
<Stack.Protected guard={isAuthenticated} redirectTo={fallbackRoute}>

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These guards now redirect via getFallbackRoute, but per the PR description logged-in screens weren't tested. Please verify on device (iOS 26+ for the Liquid Glass tab bar) the (app) tabs, Settings, Update Password, and sign-out landing on /sign-in, even with a mocked API.


const AnimatedScrollView
= Reanimated.createAnimatedComponent<KeyboardAwareScrollViewProps>(
= Reanimated.createAnimatedComponent(

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Per the PR notes, KeyboardAwareScrollView handlers don't attach with keyboard-controller 1.22.7 + Reanimated 4.7, so this component no longer reacts to the keyboard. Since it's part of the template, either bump keyboard-controller to a working version or add a comment here documenting the limitation and open a follow-up issue.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tracking this in #173. Bumping keyboard-controller to 1.23.1 doesn't change the affected code path, and no screen in the template uses this component today, so I'd rather not block the upgrade on it.

@fernandatoledo

fernandatoledo commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator Author

Smoke test of the logged-in flows with Maestro.

Setup

  • iPhone 17 Pro simulator, iOS 26.2 (Liquid Glass era), dev client built with the iOS 27.1 SDK.
  • Metro serving this branch at 9b110a5, pointed at a local mock API (POST /v1/users/sign_in, GET /v1/users, PUT /v1/users/password) so the authenticated screens are reachable.

Flow (all steps pass)

  1. Cold launch → /sign-in
  2. Sign in with mocked credentials → lands on the (app) tabs
  3. Feed / Style / Settings tabs render and switch
  4. Settings shows the mocked user (name and email)
  5. Settings → Password → Update Password: fill both fields, submit → back on Settings
  6. Logout → lands on /sign-in (authenticated → unauthenticated redirect works)
  7. Repeated sign-in after relaunch works
logged-in.mp4

Notes

  • On the Update Password screen the header back button reads "(app)" instead of "Settings". Haven't checked whether that is pre-existing.
  • Not covered: small device, real device, real backend.
  • The Maestro flow and mock server are local only, not added to the PR.
  • Screen recording available on request.

NativeWind 4.1.21 (react-native-css-interop 0.1.20) overwrote the ref
prop with undefined for components React Native 0.88 declares as plain
functions (View, ScrollView, TextInput). No host ref attached, so
KeyboardAwareScrollView handlers never registered, bottom-sheet could
not resolve its scrollable and no Modal opened.

- nativewind ^4.2.7 (css-interop 0.2.7 keeps the ref prop)
- @gorhom/bottom-sheet ^5.2.14 (5.2.8 reports the sheet open but never
  shows it)
- drop estimatedItemSize from Select: FlashList 2 removed it and the
  stricter bottom-sheet types now reject it

Closes #173

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ai:minor Style issues, minor suggestions risk:high Auth, payments, migrations, security-sensitive code.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants