start

The start command launches Metro, the JavaScript bundler for React Native. Metro compiles your JavaScript code and serves it to your running app with support for Fast Refresh.

Usage

npx react-native start [options]

Options

Option	Description	Default
`--port <number>`	Port to run Metro on	`8081`
`--host <string>`	Host to run Metro on	`localhost`
`--projectRoot <path>`	Path to the project root	Current directory
`--watchFolders <list>`	Additional folders to watch (comma-separated)	`[]`
`--assetPlugins <list>`	Additional asset plugins (comma-separated)	`[]`
`--sourceExts <list>`	Additional source extensions (comma-separated)	Default extensions
`--max-workers <number>`	Maximum number of worker processes	CPU cores
`--transformer <string>`	Custom transformer module path	Default transformer
`--reset-cache`	Reset Metro bundler cache	`false`
`--resetCache`	Alias for —reset-cache	`false`
`--custom-log-reporter-path <string>`	Path to custom log reporter	None
`--https`	Enable HTTPS server	`false`
`--key <path>`	Path to custom SSL key	None
`--cert <path>`	Path to custom SSL certificate	None
`--config <string>`	Path to Metro config file	`metro.config.js`
`--no-interactive`	Disable interactive mode	`false`

Examples

Basic Usage

npx react-native start

Starts Metro on the default port (8081) with interactive mode enabled.

Custom Port

npx react-native start --port 8088

Useful when port 8081 is already in use.

Reset Cache

npx react-native start --reset-cache

Clears Metro’s cache. Use this when:

You’ve made native code changes
Dependencies were updated
Experiencing unexpected bundling errors

Custom Host

npx react-native start --host 192.168.1.100

Allows devices on your network to connect to Metro.

Watch Additional Folders

npx react-native start --watchFolders ../shared-components,../common-utils

Useful for monorepo setups where code exists outside the project root.

HTTPS Server

npx react-native start --https --key ./certificates/key.pem --cert ./certificates/cert.pem

Enables HTTPS with custom certificates for secure local development.

Limit Workers

npx react-native start --max-workers 4

Limits CPU usage by restricting the number of worker processes.

Non-Interactive Mode

npx react-native start --no-interactive

Disables keyboard shortcuts and interactive features. Useful for CI/CD environments.

Interactive Mode

When Metro is running in interactive mode, you can use these keyboard shortcuts:

Key	Action
`r`	Reload the app
`d`	Open Developer Menu
`i`	Run on iOS
`a`	Run on Android
`j`	Open debugger
`c`	Clear Metro cache and reload
`q`	Quit Metro

Metro Server Output

When Metro starts successfully, you’ll see:

                ######                ######
              ###     ####        ####     ###
            ##          ###    ###          ##
            ##             #### ##             ##
            ##             ####  ##            ##
            ##           ##    ##              ##
            ##         ###      ##              ##
             ##  ####  ##       #####            ##
          ######    ##       ########            ##
       ###     ##  ##       ##    ####           ##
     ##         ## ##       ##       ###        ##
    ##           ####       ##         ###     ##
    ##           ###         ##                ##
    ##           ##           ##              ##
    ##          ##             ##            ##
     ##       ###               ####      ####
       #######                    #########

                Welcome to Metro!

     Fast - Scalable - Integrated

Loading Metro bundler at http://localhost:8081

Environment Variables

Custom Port

RCT_METRO_PORT=8088 npx react-native start

Node Environment

NODE_ENV=production npx react-native start

Common Use Cases

Development with Multiple Devices

# Start Metro
npx react-native start --host 0.0.0.0

# In another terminal, run on devices
npx react-native run-ios
npx react-native run-android

Monorepo Setup

npx react-native start \
  --projectRoot . \
  --watchFolders ../packages/shared,../packages/utils

Performance Optimization

npx react-native start --max-workers 2

Reduces CPU usage on lower-end machines.

Troubleshooting

Port Already in Use

Error: Port 8081 is already in use Solution:

# Kill process using port 8081
lsof -ti:8081 | xargs kill -9

# Or use a different port
npx react-native start --port 8088

Cache Issues

Error: Bundling errors or stale code Solution:

npx react-native start --reset-cache

Cannot Connect from Device

Error: Device shows red screen “Could not connect to Metro” Solution:

# Use your local IP address
npx react-native start --host 192.168.1.100

Watchman Issues

Error: File watching errors Solution:

watchman watch-del-all
npx react-native start --reset-cache

Performance Tips

Reduce Initial Bundle Time

Use source maps only in development:

metro.config.js

module.exports = {
  transformer: {
    getTransformOptions: async () => ({
      transform: {
        experimentalImportSupport: false,
        inlineRequires: true,
      },
    }),
  },
};

Optimize for Large Projects

Limit worker processes:

npx react-native start --max-workers 4

Speed Up Rebuilds

Enable persistent cache in metro.config.js:

module.exports = {
  cacheStores: [
    new FileStore({root: '/tmp/metro-cache'}),
  ],
};

Next Steps

Run iOS

Build and run your app on iOS

Run Android

Build and run your app on Android

Metro Config

Configure Metro bundler settings

Bundle

Create production bundles

CLI Commands

Configuration

Usage

Options

Examples

Basic Usage

Custom Port

Reset Cache

Custom Host

Watch Additional Folders

HTTPS Server

Limit Workers

Non-Interactive Mode

Interactive Mode

Metro Server Output

Environment Variables

Custom Port

Node Environment

Common Use Cases

Development with Multiple Devices

Monorepo Setup

Performance Optimization

Troubleshooting

Port Already in Use

Cache Issues

Cannot Connect from Device

Watchman Issues

Performance Tips

Next Steps

Run iOS

Run Android

Metro Config

Bundle

Build docs developers (and LLMs) love

CLI Commands

Configuration

Documentation Index

​Usage

​Options

​Examples

​Basic Usage

​Custom Port

​Reset Cache

​Custom Host

​Watch Additional Folders

​HTTPS Server

​Limit Workers

​Non-Interactive Mode

​Interactive Mode

​Metro Server Output

​Environment Variables

​Custom Port

​Node Environment

​Common Use Cases

​Development with Multiple Devices

​Monorepo Setup

​Performance Optimization

​Troubleshooting

​Port Already in Use

​Cache Issues

​Cannot Connect from Device

​Watchman Issues

​Performance Tips

​Next Steps

Run iOS

Run Android

Metro Config

Bundle

Build docs developers (and LLMs) love

Usage

Options

Examples

Basic Usage

Custom Port

Reset Cache

Custom Host

Watch Additional Folders

HTTPS Server

Limit Workers

Non-Interactive Mode

Interactive Mode

Metro Server Output

Environment Variables

Custom Port

Node Environment

Common Use Cases

Development with Multiple Devices

Monorepo Setup

Performance Optimization

Troubleshooting

Port Already in Use

Cache Issues

Cannot Connect from Device

Watchman Issues

Performance Tips

Next Steps