Metro, the Bundler

When you run npx expo start for Sprout, a terminal fills with a QR code and a line that says Metro is waiting. Your phone never opens your source files directly. Something has to collect them and hand them over. That something is Metro.

The rule

Metro gathers every file into one bundle and serves it to the app.

Metro is the JavaScript bundler made for React Native. It does three jobs:

1. Resolve. Starting at your entry file, it follows every import and require, including packages in node_modules and images in assets/.
2. Transform. It compiles JSX and TypeScript into plain JavaScript the engine can run, using Babel.
3. Serve. In development it runs a local server (port 8081 by default) and sends the bundle to the app on your phone or simulator.

In a bare CLI project the command is npx react-native start, and the cache flag is --reset-cache.

Because Metro watches your files, a save triggers a quick rebuild of just what changed, and Fast Refresh pushes it to the running app. For a release build, Metro produces one bundle that is packed inside the app, so the store version needs no server.

Metro also understands platform extensions: if both Header.ios.js and Header.android.js exist, import Header from './Header' picks the right one for each platform. You will use that in the platform section.

The shortcut

When the app shows old code or a "module not found" error, walk Metro's three jobs in order: resolve, transform, serve. The problem is almost always at one of those steps.

The trap is thinking the phone app "contains" your code during development. It does not; it downloads the bundle from Metro. If your phone and laptop are on different networks, the app cannot reach Metro and loading fails.

Drills

Answer fast — trust the rule.

Remember

• Metro gathers every file into one bundle and serves it to the app.
• Debug in order: resolve, transform, serve.
• Trap: in development the phone needs to reach Metro on your computer.