expo / skills

expo-web-to-native

Migrate a web React app (Next.js, Vite, CRA) to a native iOS and Android app with Expo, mapping web idioms like the DOM, CSS, React Router and localStorage to native.

View source Expo React Native React Architecture

Install

npx skills add https://github.com/expo/skills --skill expo-web-to-native

False Friends: web idioms → native

Disclosed reference for expo-web-to-native. A false friend is a web idiom that looks portable but isn't - it compiles in your head, then breaks (or silently no-ops) on native. Each row is web idiom → native equivalent → the gotcha. Reach for this in steps 3–5 of a migration, and whenever you're learning native after the web.

This is the single source of truth for the mapping; the SKILL.md steps name a few high-traffic swaps but defer the full list here.

Elements & text

Web	Native	Gotcha
`<div>`, `<section>`, `<span>`	`<View>`	`View` is the only generic container; no semantic element variants.
`<p>`, `<h1>`, raw text in JSX	`<Text>`	All text must sit inside `<Text>`. Bare strings in a `View` throw.
`<img src>`	`<Image>` / `expo-image`	`expo-image` adds caching, blurhash, transitions. Remote images need an explicit `width`/`height` or a flex parent.
`<button>`, `<a>`	`<Pressable>`	No default styling, no hover. Wrap label text in `<Text>`.
`<input>`	`<TextInput>`	Controlled via `value` + `onChangeText` (not `onChange`/`e.target.value`).
`<ul>/<li>` rendered with `.map()`	`<FlatList>` / `<FlashList>`	`.map()` over a long list mounts every row at once → jank. Use a virtualized list with `data` + `renderItem`.

Events & interaction

Web	Native	Gotcha
`onClick`	`onPress`	Also `onLongPress`, `onPressIn/Out`. There is no click.
`onChange={e => e.target.value}`	`onChangeText={text => ...}`	The handler receives the string directly, not an event.
`onSubmit` (form)	`onPress` / `onSubmitEditing`	No `<form>` element and no submit event; wire the button/keyboard return key.
`:hover`, `:focus`	press/focus state	No hover on touch. Track state and style from it, or use `Pressable`'s state callback.
`e.preventDefault()`	—	No default actions to prevent; remove it.

Styling & layout

Web	Native	Gotcha
`className` / CSS files	`StyleSheet.create` or NativeWind	Plain RN has no className. For Tailwind muscle memory use NativeWind.
CSS cascade & inheritance	none	Styles don't inherit (except a few `Text` props like `color`/`fontSize` to nested `Text`). Style each node.
`display: flex` opt-in, default `row`	flex always on, default `column`	Biggest layout surprise: flex is the only layout model and the main axis is vertical by default.
`px`, `rem`, `%`	unitless numbers (dp)	`padding: 16` = density-independent pixels. `%` works in some props; no `rem`/`em`/`vh`.
`@media` queries	`useWindowDimensions()` / `Platform`	No media queries. Branch on dimensions or platform at runtime.
`position: fixed`	`position: absolute` + safe area	No `fixed`. Pin with `absolute` and respect insets (`react-native-safe-area-context`).
`z-index`	`zIndex` (+ `elevation` on Android)	Works mostly, but Android shadow/stacking also needs `elevation`.
CSS transitions / `@keyframes`	`Animated` / Reanimated	No CSS animation. Reanimated is the standard; gestures via `react-native-gesture-handler`.
`gap`, flexbox	`gap`, flexbox	These largely transfer — flexbox is the one big win for web devs.

Web	Native	Gotcha
React Router / Next.js routes	Expo Router (file-based)	File-based like Next App Router; `react-router` concepts map but the API differs.
`<a href>` / `<Link>`	`expo-router` `<Link href>`	Works in DOM components too.
`useNavigate()` / `router.push`	`useRouter()` from `expo-router`	`router.push/replace/back`.
`useParams` / `useSearchParams`	`useLocalSearchParams()`	Note: doesn't work inside a DOM component - read in the native parent, pass as props (see `expo-dom`).
`window.location`	`usePathname()` / router	No `location` object.
Deep links / `myapp://`	URL scheme + universal links	Configure `scheme` in app config; native gives you real deep linking and (with AASA) app links - see `expo-app-clip` for the AASA file.

React architecture & data (Next.js / SSR apps)

Web	Native	Gotcha
Async Server Component (`async function Page()`)	client component + data fetch	No RSC on native (Expo's is experimental and different). Split into a client component that fetches via the API + a presentational child before porting.
Server actions (`'use server'`)	API route + `fetch`	No server actions. Expose an endpoint and call it.
`cookies()` / `headers()` (server)	token in `expo-secure-store`	Server-only. Auth moves to a bearer token sent as a header.
ORM / DB client in a page (Drizzle, Prisma)	server only - call over HTTP	The device never talks to the DB. Keep the backend deployed, or move routes to EAS Hosting (`eas-hosting`); the app fetches.
`next/navigation` (`notFound`, `redirect`)	`expo-router`	`redirect()` → `router.replace`; `notFound()` → a native `+not-found` route.
`_layout` as a DOM component	always native	Layout routes can't be DOM components — they are the native shell. Rewrite web-only layout logic (theme scripts, providers) with native APIs.

Storage, state & sessions

Web	Native	Gotcha
`localStorage` / `sessionStorage`	`expo-sqlite` (`globalThis.localStorage`)	`import 'expo-sqlite/localStorage/install';` polyfills the global `localStorage`, so existing code works as-is (or `expo-sqlite/kv-store`). No `sessionStorage` equivalent — native has no session concept.
Cookies / `document.cookie`	`expo-secure-store` + headers	No cookie jar by default. Store tokens in SecureStore; send as auth headers.
Auth via session cookie	token in SecureStore	Redesign auth around bearer tokens, not browser sessions.
In-memory React state	same	`useState`/`useReducer`/`useContext` transfer unchanged.

Browser & platform APIs

Web	Native	Gotcha
`window`, `document`	none	Don't exist. Guard web-only libs, or keep them in a DOM component (`expo-dom`).
`window.matchMedia('(prefers-color-scheme: dark)')`	`useColorScheme()`	Hook from `react-native`, reactive to the system theme. Web theme bootstrap scripts in the layout don't run.
`window.innerWidth/Height`	`useWindowDimensions()`	Reactive hook; updates on rotation.
`navigator.*`, Web APIs	Expo SDK modules	e.g. camera → `expo-camera`, geolocation → `expo-location`, clipboard → `expo-clipboard`.
`alert()` / `confirm()` / `prompt()`	`alert()` works; `Alert.alert(...)` for the rest	RN provides a global `alert()`; `confirm()` / `prompt()` don't exist — use `Alert.alert` with a button array.
`process.env.X`	`process.env.EXPO_PUBLIC_X`	Only `EXPO_PUBLIC_`-prefixed vars are inlined into the client bundle.
`console.log`	`console.log`	Works — shows in the dev tools/terminal.
`dangerouslySetInnerHTML`	—	No DOM to inject into. Render data, or use a DOM component / WebView.
inline SVG	`react-native-svg`	No native `<svg>`; the library mirrors the element API.

Networking

Web	Native	Gotcha
`fetch('/api/x')` (relative)	absolute URL	Native has no origin — relative paths fail. Use a configured base URL (`EXPO_PUBLIC_API_URL`).
CORS	n/a	No browser CORS, but you still need a reachable absolute host.
`fetch`, React Query, SWR	same	The libraries themselves work on native - see `expo-data-fetching`.
Next.js API routes	Expo Router API routes	Move server endpoints to Expo API routes on EAS Hosting - see `eas-hosting`.
Streaming responses (SSE, AI SDK `useChat`)	`expo/fetch` with `textStreaming`	RN's built-in `fetch` can't read a streaming response body. Use `expo/fetch` (streams, and works with the Vercel AI SDK) or an XHR-based polyfill.

Third-party services & SDKs

Browser SDKs don't run on native — each needs a native equivalent. The canonical, version-matched integrations live in the expo-examples skill (the expo/examples repo); reach for those instead of wiring from scratch.

Web service	Native	Gotcha
Stripe.js — digital goods / subscriptions	store In-App Purchase via RevenueCat (`react-native-purchases`)	Policy, not just an SDK swap. Apple & Google require IAP for in-app digital goods and take ~15–30%; shipping Stripe for them gets the app rejected. Decide at assess time — it can change the business model.
Stripe.js — physical goods / services	`@stripe/stripe-react-native` (PaymentSheet, Apple/Google Pay)	Stripe's RN SDK is allowed for physical goods; see `expo-examples` `with-stripe`.
Google Maps JS	`react-native-maps`	A native map view, not an embedded iframe.
Web Push	`expo-notifications` (APNs / FCM)	Different delivery + permission model.
OAuth redirect flow	`expo-auth-session` (deep-link OAuth), or a native auth SDK (Clerk, Supabase…)	No browser redirect — an app deep link completes the flow.
GA / Segment.js analytics	native SDK (`posthog-react-native`, Segment RN)	The web JS snippet won't load; swap for the native SDK.
`<input type=file>` / `getUserMedia`	`expo-image-picker` / `expo-camera` / `expo-document-picker`	Native pickers + runtime permissions.

Scrolling, keyboard & safe area

Web	Native	Gotcha
Body scrolls by default	`<ScrollView>` / `<FlatList>`	Nothing scrolls unless you make it. Wrap overflowing content explicitly.
`overflow: scroll`	`<ScrollView>`	Don't nest a `ScrollView` inside a `FlatList` of the same axis.
Keyboard overlaps inputs	`KeyboardAvoidingView`	The keyboard covers inputs by default; wrap forms to push content up.
Notch / status bar	`react-native-safe-area-context`	Content flows under the notch/home indicator unless you apply safe-area insets.
`:focus` ring, tab order	manual	No automatic focus management; wire `ref`/`focus()` and `returnKeyType`.

Design engineering

Frameworks & libraries