Skip to main content
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

OptionDescriptionDefault
--port <number>Port to run Metro on8081
--host <string>Host to run Metro onlocalhost
--projectRoot <path>Path to the project rootCurrent 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 processesCPU cores
--transformer <string>Custom transformer module pathDefault transformer
--reset-cacheReset Metro bundler cachefalse
--resetCacheAlias for —reset-cachefalse
--custom-log-reporter-path <string>Path to custom log reporterNone
--httpsEnable HTTPS serverfalse
--key <path>Path to custom SSL keyNone
--cert <path>Path to custom SSL certificateNone
--config <string>Path to Metro config filemetro.config.js
--no-interactiveDisable interactive modefalse

​
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:
KeyAction
rReload the app
dOpen Developer Menu
iRun on iOS
aRun on Android
jOpen debugger
cClear Metro cache and reload
qQuit 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

Use source maps only in development:
metro.config.js
module.exports = {
  transformer: {
    getTransformOptions: async () => ({
      transform: {
        experimentalImportSupport: false,
        inlineRequires: true,
      },
    }),
  },
};
Limit worker processes:
npx react-native start --max-workers 4
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

Build docs developers (and LLMs) love

Get started for freeTalk to us