Set Up Fast Refresh to Build Apps Using Vega CLI
Fast Refresh is a React Native feature that lets you see code changes instantly without rebuilding your app. Fast Refresh works in both Vega Studio and Vega command-line interface (CLI) environments. While Vega Studio automatically enables Fast Refresh if building in Debug mode, you must manually configure Fast Refresh when building apps using Vega CLI. Follow the instructions on this page.
Prerequisites
- Install the Vega SDK.
-
Complete setup of either:
Connect your Vega Virtual Device to Metro Server
Have your app's directory path ready:
- Open two terminal windows (A and B).
-
Start the Vega Virtual Device in terminal A:
kepler virtual-device start -
Navigate to your app’s directory in terminal B:
cd <your app directory> // Example output cd keplersampleapp -
Install the dependencies:
npm install -
Build the app:
npm run build:debug -
Start the Metro Server in terminal B:
npm startThe Metro Server loads dependencies and displays its logo.
Metro Server -
Return to terminal A and start port forwarding:
kepler device start-port-forwarding --device <DEVICE_NAME> -p <PORT> --forward false // Example output kepler device start-port-forwarding --device VirtualDevice -p 8081 --forward false -
Run your app using the debug build:
kepler run-kepler <PATH_TO_VPKG> <com.amazondeveloper.YOUR_APP_NAME.main> -d VirtualDevice # To run `keplersampleapp` on x86 Vega Virtual Device, the command is: kepler run-kepler build/x86_64-release/keplersampleapp_x86_64.vpkg com.amazondeveloper.keplersampleapp.main -d VirtualDeviceTip: You can find your id in the manifest.toml file at your project root and customize the fully qualified domain name (FQDN) to one you prefer.
Use a custom Metro Bundler port
Metro Bundler supports changing the default port.
-
Start Metro on a custom port:
npm start -- --port=<new_port>Tip: Replace<new_port>with your preferred port number (for example, 8082). -
Reverse-port-forward the custom port on the host:
vda reverse tcp:8081 tcp:<new_port>
End the Fast Refresh session
When you finish working on your app with Fast Refresh, you can:
-
Close your app.
kepler device terminate-app --device <DEVICE_NAME> --appName <com.amazondeveloper.YOUR_APP_NAME.main> # The command to close the `keplersampleapp` on the Vega Virtual Device is: kepler device terminate-app --device VirtualDevice --appName com.amazondeveloper.keplersampleapp.main -
Press Ctrl+C to stop the Metro Server.
-
Stop port forwarding:
kepler device stop-port-forwarding --device <DEVICE_NAME> -p <PORT> --forward false # The command to stop port forwarding for the `keplersampleapp` on the Vega Virtual Device is: kepler device stop-port-forwarding --device VirtualDevice -p 8081 --forward false -
Stop the Vega Virtual Device:
kepler virtual-device stop
Connect your Fire TV Stick to Metro Server
-
Connect your Fire TV Stick to your computer.
If you're a macOS user, you see a security prompt when connecting your Fire TV Stick to your computer. Click Allow.
Allow accessory to connect To avoid future prompts:
a. Go to Configuration > Privacy & Security.
b. Set Allow accessories to connect to Always.
Allow accessories to connect - Open two terminal windows (A and B).
-
Navigate to your app’s directory in terminal A:
cd <your app directory> // Example output cd keplersampleapp -
Start the Metro Server in terminal A:
npm startThe Metro Server loads dependencies and displays its logo.
Metro Server - Press r in the Metro Server window.
-
Start port forwarding in terminal B:
kepler device start-port-forwarding --device <DEVICE_NAME> -p <PORT> --forward false # For example, if your device serial number is `GXX2A1234567890A`, the full command would be: kepler device start-port-forwarding --device GXX2A1234567890A -p 8081 --forward falseImportant: After you run the command, a deprecation warning appears. Continue to the next step.To check for your device's serial number, run the following command:
kepler device list -
Install the dependencies:
npm install -
Build your app:
npm run build:app -
Run your app:
kepler run-kepler <PATH_TO_VPKG> <com.amazondeveloper.YOUR_APP_NAME.main> --deviceId <DEVICE_NAME> # To run the `keplersampleapp` app with the device serial number `GXX2A1234567890A`, the command would be: kepler run-kepler build/armv7-release/keplersampleapp_armv7.vpkg --deviceId GXX2A1234567890A
Use a custom Metro Bundler port
Metro Bundler supports changing the default port.
-
Start Metro on a custom port:
npm start -- --port=<new_port>Tip: Replace<new_port>with your preferred port number (for example, 8081). -
Reverse-port-forward the custom port on the host:
vda reverse tcp:8081 tcp:<new_port>
End the Fast Refresh session
When you finish working on your app with Fast Refresh, disconnect the device.
Troubleshooting
If you encounter an issue while setting up Fast Refresh, visit Resolve Fast Refresh Issues.
Related topics
Last updated: Sep 30, 2025
