Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
AWS
Documentation
Support
Contact Us
My Cases

Console

as

Get Started
Design and Develop
Publish
Reference
Support

Build Your App

This page walks you through the steps to build an app with the Vega SDK. The SDK includes multiple templates to structure your app and two build approaches: Vega Studio and Vega CLI. Vega Studio is a VS Code extension that runs commands to create, build, and run the app from the command palette. The Vega CLI provides the commands you can run directly in a terminal session.

If you are new to building apps with Vega, see Build a Hello World app. To explore all templates and build options, see All build options.

Build a Hello World app

This tutorial walks you through creating, building, and running your first Vega app using Vega Studio, the Vega SDK's VS Code extension. This example creates an app called Hello, Vega based on a React Native app template and runs in the Vega Virtual Device, a simulated Fire TV Stick included in the Vega SDK.

Step 1: Create a new app from template

First you need to create a new app using a Vega template.

  1. Launch VS Code.

  2. Click the Vega extension icon in the activity bar to the extension.

    Vega Studio icon

  3. Click the + icon to create a new project.
  4. Select the template hello-world (React Native 0.72-based template)
  5. Choose a project directory

  6. Name the app. This example uses the following names:

    App name: VegaProject

    Package name: com.mycompany.VegaProject

Step 2: Build the app

Next, build the app in a test mode.

  1. In the Vega extension, locate and select the VegaProject in your workspace.
  2. Set build mode to Debug. This enables fast-refresh by default, so any saved changes to your app are reflected on your app in real-time.

  3. Select the build button next to VegaProject.

  4. Check the Output tab in VS Code for the build success message.

Step 3: Run in Vega Virtual Device (VVD)

Finally, run the app in Vega's Fire TV Stick simulator, the Vega Virtual Device (VVD).

  1. In the extension panel, locate VirtualDevice:Tv under Devices and press the play button.
  2. Wait for the VVD window to open.
  3. Click the Play button next to VegaProject.

When the app runs, you'll see the VVD update with the Hello World app.

Congratulations! You've successfully created and run your first Vega app. Try changing some of the text in your App.tsx to see the changes reflected live on the running app.

All build options

Vega offers multiple pathways for you to create your customs app based on your specific requirements. You can choose from the following build approaches:


Build an app with Vega Studio

Vega Studio is an integrated development environment (IDE) that lets you create, build, run, test, debug, and analyze app performance on Fire TV and other Vega-supported platforms. This section provides steps to build Vega apps with Vega Studio.

Prerequisites

Step 1: Create a Vega project

  1. Open Visual Studio Code (VS Code) and select the Vega extension icon from the activity bar to open the Kepler Studio panel:

    Vega Studio icon

    The Kepler Studio panel has the following sections:

    • Projects
    • Build Modes
    • Devices
    • App Performance Tools
    • Help and Feedback

  2. Click the + (Create Vega Project) icon from the Projects section.

  3. Choose a project template.

    • hello-world - Use this project template to create an app that depends on React Native v0.72.
    • basic-turbo-module - Use this project template to create a custom Turbo Module.
    • idl-turbo-module - Use this project template to create an app compatible with all supported React Native versions and native IDL APIs.
  4. Select a directory for your project.

  5. Provide a project name for your app (no spaces or special characters).

    For example: My3PSample

    Press Enter after entering your project name.

  6. Enter a package name for your project in this format <tld>.<company_name>.<app_name>.

    For example: com.org.vegaproject

    Press Enter after entering a package name for your project.

Vega Studio creates your project based on your selected template. When you select a basic-turbo-module or idl-turbo-module template with an open project, Vega Studio creates a multi-root workspace. The new project appears as a folder, so you can use the Turbo Module as a dependency and develop both in the same VS Code window. Vega Studio adds the new basic-turbo-module as a dependency to your open project. If you have multiple Vega apps open during basic-turbo-module creation, the extension prompts you to select the target app.

Step 2: Build a Vega app

  1. Select your projects under Projects section.

    Screen shows where to select a project
    Select a project

  2. Choose your build mode (debug or release) from the Build Mode section.

    Screen shows the build mode options
    Build mode options

  3. Click the play button from the Devices section to start the target device.

  4. Click the build button next to your project name to start the build process.

View the build output

  1. Go to the integrated terminal panel in VS Code.
  2. Select the Output tab.
  3. Choose Kepler from the drop-down list.

You should see Kepler build completed or Kepler build failed. If the build fails, identify the issue by expanding the error messages.

Step 3: Set up Fast Refresh

Fast Refresh is automatically enabled in Vega Studio when using Debug mode. This feature lets you see code changes instantly without rebuilding your entire app.

For complete instructions on using Fast Refresh, see Use Fast Refresh for real-time development.

Step 4: (Optional) Configure a custom port

You can specify a custom port other than port 8081.

  1. Go to Code > Settings > Settings in VS Code.
  2. Enter React Native Port in the search box.
  3. Enter your port number.
  4. Reload VS Code when prompted.

When you start a debug session, Vega Studio automatically configures shared preferences on the device in /data/shared_preferences.json.

Step 5: Run and test a Vega app

You can run and test your Vega app on Fire TV Stick or Vega Virtual Device.

On Fire TV Stick:

  1. Select your Fire TV Stick device from the Kepler Studio panel under Devices.

  2. Click the "play" button next to your project name.

    For details, see Fire TV Stick.

On Vega Virtual Device

  1. Navigate to Kepler Studio > Devices and select VirtualDevice:Tv.
  2. Click the play button to start the virtual device.
  3. Click the play button next to your project name.

For details, see Vega Virtual Device.

Step 6: (Optional) Stop the React Native Packager

There are two options to stop the React Native Packager:

Option 1: Through the VS Code status bar

Screen shows where to stop the React Native Packager from VS Code
Stop React Native Packager from the status bar

Click the React Native Packager button in the VS Code status bar at the bottom. When you hoover it, you see the tooltip Stop Packager.

Option 2: Through the VS Code Command Palette

Screen shows where to stop the React Native Packager from VS Code Command Palette
Stop React Native Packager from the Command Palette

  1. Open Command Palette:

    Mac: Cmd+shift+P Linux: Ctrl+Shift+P

  2. Enter and select React Native: Stop Packager.

After stopping the Packager (using either option), you can restart your app through Kepler Studio panel. Click the play button to the right of your app name.

Screen shows where to restart your app through Vega Studio panel
Restart your app

Step 7: Debug a Vega app

The Vega Studio provides a built-in debugger. To use it, follow the instructions in Debug with Vega Studio.

Step 8: Analyze app performance

Vega Studio provides tools to help you analyze and optimize your app's performance. For details, visit the following pages:


Build an app using the Vega CLI

The Vega command-line interface (CLI) provides pre-built project templates with core functionalities to accelerate your development. Each project template contains all necessary files and configurations required to run your app on Vega devices, including manifest files, native modules, and the proper directory structure.

Prerequisites

Project templates

To see the list of available project templates:

Copied to clipboard.

kepler project list-templates

After you run kepler project list-templates, you see the following project templates:

  • hello-world - Use this project template to create an app that depends on React Native v0.72.
  • basic-turbo-module - Use this project template to create a custom Turbo Module.
  • idl-turbo-module - Use this project template to create an app compatible with all supported React Native versions and native IDL APIs.

Step 1: Generate a project

  1. Use the kepler project generate command to create an app.

    The command takes four arguments:

    • --template - The Vega project template (for example: hello-world).
    • --name - Your app name (no spaces or special characters).
    • --packageId - Your app's unique identifier
    • --outputDir (optional) - Your project location. If you don't specify a project location, the system creates your project location in your current working directory.

    Example command:

    The following example command creates a new app named keplersampleapp. The command outputs the path to your project location.

    Copied to clipboard.

    kepler project generate --template hello-world --name keplersampleapp --packageId com.amazondeveloper.keplersampleapp --outputDir keplersampleapp

  2. Navigate to your new app:

    Copied to clipboard.

    cd keplersampleapp

Step 2: Build your app

Install the dependencies and build:

Copied to clipboard.

npm install

Copied to clipboard.

npm run build:app

The commands install necessary NPM dependencies, build the native code, then bundle the JavaScript using the Metro bundler.

The build creates a build folder with your app's package vpkg:

├── keplersampleapp
│   ├── build
│   │   ├── x86_64-release
│   │   |   ├──keplersampleapp_x86_64.vpkg #use the path to this file to run your app on the virtual device for x86 machines
│   │   ├── armv7-release
│   │   |   ├──keplersampleapp_armv7.vpkg #use the path to this file to run your app on the Fire TV Stick
│   │   ├── aarch64-release
│   │   |   ├──keplersampleapp_aarch64.vpkg #use the path to this file to run your app on the virtual device for M-series machines

Metro, a React Native’s JavaScript bundler, starts at the command prompt window. Metro takes in an entry file and returns a single JavaScript file with all of your code and dependencies.

Step 3: Set up Fast Refresh

Fast Refresh is a React Native function that lets you see changes in your app without rebuilding. Unlike Vega Studio which enables Fast Refresh automatically, Vega CLI requires manual setup.

For complete setup instructions, see Set Up Fast Refresh with Vega CLI.

Step 4: Run your app on Vega Virtual Device

The Vega SDK includes the Vega Virtual Device, which lets you run and test your apps without needing a physical device.

See Run Your App on Vega Virtual Device for complete instructions.

Last updated: Sep 30, 2025

Follow us:
amazon_developer_logo

© 2010-2025, Amazon.com, Inc. or its affiliates. All Rights Reserved.

Terms

Amazon Developer Blog

Contact Us