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. |
Navigation & URLs
| 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. |