Tooling, Metro, and Project Structure

Metro is React Native’s bundler. It does for a React Native app what Vite or webpack does for a web app — start from an entry file, follow every import, and produce one JavaScript artifact — but it is built around the constraints a mobile app has and a web page does not: two platforms compiled from one source tree, no network-loaded chunks by default, and a development loop where the whole graph is rebuilt incrementally on every keystroke.

Metro’s work splits into three stages that always run in the same order.

Metro delegates the actual per-file transformation to Babel, configured by babel.config.js at the project root. A fresh project’s file is one line of substance:

babel-preset-expo wraps @react-native/babel-preset (which a Community CLI project uses directly) and adds the framework’s own transforms. Application code rarely needs to touch this file at all; the cases that do are narrow and each comes from a library that ships a Babel plugin: `react-native-reanimated’s plugin, which must be listed last, and the React Compiler, both introduced on Performance. Adding a plugin here changes the transform cache key, so the next Metro start is a cold one.

One distinction worth keeping straight: Babel is not what type-checks Places. It erases TypeScript’s type annotations without reading them, which is why a type error never fails a Metro build — type checking is a separate tsc --noEmit step, as covered on TypeScript.

Adding a React Native library has two halves: the JavaScript half, which is an ordinary npm install, and the native half, which has to end up compiled into the iOS and Android apps.

In an Expo project, the install command is npx expo install <package> rather than npm install. The difference is that expo install resolves the version of the package that is compatible with the project’s Expo SDK version (SDK 57 for Places) instead of the latest published one, which is what prevents a library built against a different React Native version from being pulled in. npx expo install --fix retroactively realigns every already-installed package to its SDK-compatible version, and npx expo-doctor reports mismatches without changing anything.

ESLint 9 uses flat configuration: a single eslint.config.js / .mjs file exporting an array of configuration objects, replacing the older .eslintrc cascade. Each object in the array optionally narrows itself with files, and later objects override earlier ones, so the order of the array is the whole configuration model. @react-native/eslint-config remains the shareable config carrying React Native’s own rule set (React, React Hooks, and the React-Native-specific rules) and is consumed from a flat config through FlatCompat; an Expo project can use `eslint-config-expo’s flat entry point directly instead.

Prettier handles formatting — quote style, trailing commas, line width — and is deliberately not an ESLint concern: eslint-config-prettier, placed last, switches off every stylistic ESLint rule so the two tools cannot disagree, and Prettier runs on its own (npx prettier --write ., plus an editor-on-save integration and a CI --check run). Both belong in the same CI job as the type check, covered on Testing.

A project does not have to start from the bare template. Boilerplates — Ignite, the Obytes starter, the react-native-boilerplate family — ship an opinionated stack (navigation, state, networking, testing, CI) so the first commit already has structure. The trade-off is the usual one: the decisions are made for you, which is valuable on day one and a liability on the day you disagree with one of them, since a boilerplate is copied into your repository rather than depended on and diverges from upstream immediately. Places deliberately starts from the plain Expo template and assembles its stack page by page, so that every choice is visible.

UI libraries are a longer-lived decision than a boilerplate, because they shape the component code itself. The three most commonly reached for:

None of the three is a prerequisite: Places builds its own small component layer on the core components and the src/theme/ tokens established on Styling, which is the right default for a design system that is not Material and a team that wants to read every line of its own UI code.

The template’s flat src/ works up to roughly the point where two people edit it at once. Past that, the question is what the top-level folders are named after. Grouping by technical kind — components/, hooks/, screens/, store/ at the root — means every feature is smeared across every folder, so any change touches four directories and any deletion leaves orphans behind. Grouping by feature means one folder per piece of product, each containing whatever kinds of file it happens to need.

Places uses the feature-based layout, and it is the canonical tree every other page in this section refers to by file path:

The five non-features/ folders are the shared infrastructure that genuinely has no single owning feature: app/ boots the application, navigation/ owns the route tree because routes span features by definition, theme/ and lib/ hold what more than one feature imports, and native/ holds the Turbo Module specs that Native Modules and Components realizes on each platform. Everything else lives under its feature.

Three conventions keep the layout from decaying:

react-native-web implements React Native’s component and API surface on top of the DOM: View becomes a div, Text a span, StyleSheet styles become real CSS, and Pressable’s interaction states map onto mouse and keyboard events. That makes a third platform available to the same source tree — an Expo project runs `npx expo start --web and needs no separate bundler configuration, since Metro handles the web target too.

Most of Places is portable as-is, because it is written against core components rather than platform APIs. The parts that are not portable are the parts that touch something the web does not have, and those are exactly what the .web.tsx / .native.tsx split from the resolution table above is for. A worked example: PlaceCard’s favourite toggle fires the `HapticTap Turbo Module, which has no web equivalent, and the card’s hover affordance exists only on web.

The shared props contract lives in a plain module both implementations import, so the two files cannot drift:

Every caller keeps importing './PlaceCard' and gets the right one. Note what is not duplicated: the styles live in a third shared file, and the accessibility labels are identical on both, so a change to either happens once. The discipline that makes this scale is keeping the split at the leaves — splitting PlaceCard is cheap, splitting PlacesListScreen would mean maintaining two copies of the screen’s data-fetching logic as well.

Universality is not free: navigation needs URL-addressable routes to behave like a website (Expo Router’s file-based routing, on Navigation, gives this directly), and layout written for a phone needs real breakpoints before it is usable on a desktop viewport.

A monorepo becomes worth it when the mobile app is one of several packages that share code — a @places/core package of domain types and API clients consumed by the app, a web dashboard, and maybe a Node backend. pnpm workspaces and Yarn workspaces are both common; pnpm’s strict, non-hoisted node_modules layout is the one that most often needs Metro told about it explicitly.

Metro’s two monorepo settings both live on the resolver’s side of the pipeline:

Two failure modes account for most monorepo trouble. A duplicated React or react-native — one copy in the app, another in a shared package — produces hook-ordering errors or two incompatible renderers; the fix is to keep those packages as peerDependencies in every shared package and dependencies only in the app, so the resolver finds exactly one copy. And a shared package consumed as built output means every change to it requires a rebuild before Metro sees it; pointing the package’s entry at its TypeScript source instead lets Metro transform it directly and restores instant Fast Refresh across package boundaries.

Code that outgrows one app — Places's HapticTap Turbo Module, for example, which is useful to any app that wants a haptic on a toggle — becomes its own package. react-native-builder-bob is the standard tool for that: it scaffolds a library (npx create-react-native-library@latest) with the native project structure, the example app and the CI already in place, and then builds the publishable artifacts from src/ — compiling to ESM output, emitting TypeScript declarations, and running Codegen for a package that ships Turbo Modules or Fabric components.

Its configuration is a block in the library’s own package.json:

The details that matter most to consumers: files must include the native directories and the .podspec, or autolinking finds nothing to build; react and react-native belong in peerDependencies so the consuming app supplies the single copy; source and the exports "source" condition are what let a consuming app in the same monorepo bundle the library’s TypeScript directly instead of its build output; and codegenConfig is what makes Codegen run in the consuming app’s build, generating the native interfaces the library’s Kotlin and Swift implementations conform to — the same mechanism Native Modules and Components describes for a module living inside an app.

React Native upgrades change native project files — Gradle scripts, the Podfile, MainApplication.kt, AppDelegate.swift — not just a version number in package.json, which is why bumping the dependency alone never works for a project with an ios/ and android/ directory checked in.

The React Native Upgrade Helper is the tool for that case: it renders the exact diff of the template between any two versions, so upgrading is a matter of applying each hunk to the corresponding file in your own project, skipping the ones you have deliberately customized. A project that has diverged a lot from the template is where this is slowest, and the reason to keep native customization minimal.

An Expo project upgrades differently, because the native directories are generated rather than checked in: bump the expo package to the new SDK, run npx expo install --fix to realign every other Expo-managed dependency to that SDK’s versions, then npx expo-doctor to catch what is still mismatched, and regenerate the native projects with npx expo prebuild --clean if they exist locally. Places on Expo SDK 57 upgrades this way; the Upgrade Helper matters to it only for understanding what changed underneath.

Both paths benefit from the same discipline: upgrade one minor version at a time rather than jumping several, read the release notes for the versions being skipped over, and do it on a branch where the full test suite and a real device build both run before merging.

iOS and Android are the platforms React Native ships in its own repository. Others exist as out-of-tree platforms — separate packages that provide their own renderer and native host while reusing the same React Native core and the same component API, so View, Text and StyleSheet mean the same thing on them:

All of them run a version or two behind React Native core in practice, since each has to absorb every core change into its own renderer, so the realistic question before committing to one is which React Native version it currently supports — not whether it exists.