Build Your App - Amazon Vega Docs

This page walks you through building an app with the Vega SDK. The SDK includes multiple templates and two build approaches: Vega Studio and Vega CLI. Vega Studio is a VS Code extension that provides commands through the command palette, while Vega CLI offers terminal-based commands. If you’re new to building apps with Vega, see Build a Hello World app.

Prerequisites

Install the Vega SDK.

All build options

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

Vega Studio
Vega CLI

Build an app with Vega Studio

Vega Studio is a VS Code extension that lets you create, build, run, test, debug, and analyze app performance. It supports Fire TV and other Vega-supported devices. This section provides steps to build Vega apps with Vega Studio.

Step 1: Create a Vega project

Open VS Code.
Select the Vega extension icon from the activity bar to open the Vega Studio panel.
Select the + (Create Vega Project) icon from the Projects section.
Choose a project template.
- helloWorld - Use this project template to create an app that depends on React Native v0.72.
- basicTurboModule - Use this project template to create a custom Turbo Module.
- idlTurboModule - Use this project template to create an app compatible with all supported React Native versions and native IDL APIs.
Select a directory for your project.
Provide a project name for your app (no spaces or special characters). For example: MySampleProject Press Enter after entering your project name.
Enter a package name for your project in this format <top-level domain>.<company_name>.<app_name>. For example: com.mycompany.vegaproject Press Enter after entering a package name for your project. Vega Studio creates your project based on your selected template. If 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 in the same VS Code window. Vega Studio adds the new Turbo Module as a dependency to your open project. If you have multiple Vega apps open, the extension prompts you to select the target app.

Step 2: Build a Vega app

Select your project from Vega Studio > Projects.
Choose your build mode (debug or release) from the Build Mode section.
Select the play button from the Devices section to start the target virtual device.
Select the build button next to your project name to start the build process.

View the build output

Go to the integrated terminal panel in VS Code.
Select the Output tab.
Choose Vega from the drop-down list. You should see info build-kepler completed.

Step 3: (Optional) Configure a custom port

If port 8081 is already in use by another process, you can specify a custom port.

Go to Code > Settings > Settings in VS Code.
Enter React Native Port in the search box.
Enter your port number.
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 4: Run and test a Vega app

On Vega Virtual Device

Navigate to Vega Studio > Devices and select VirtualDevice:Tv.
Select the Play button to start the virtual device.
Wait for the VVD window to open and the device to finish loading.
Select the Play button next to your project name. For details, see Vega Virtual Device.

On Fire TV Stick

Select your Fire TV Stick device from Vega Studio > Devices.
Select the Play button next to your project name. Your app opens on the Fire TV Stick. For details, see Fire TV Stick.

Step 5: (Optional) Stop the React Native Packager

There are two options to stop the React Native Packager: through the VS Code status bar or the VS Code Command Palette.

Option 1: Through the VS Code status bar

Choose the React Native Packager button in the VS Code status bar at the bottom. When you hover over it, you see the tooltip Stop Packager. Choose the Stop Packager tooltip button. Screenshot of the React Native Packager button in the VS Code status bar showing the Stop Packager tooltip.

Screenshot of the React Native Packager button in the VS Code status bar showing the Stop Packager tooltip.

Option 2: Through the VS Code Command Palette

Screenshot that shows the React Native Stop Packager command from the Command Palette.

Open the Command Palette: Mac: Cmd+Shift+P Linux: Ctrl+Shift+P
Enter and select React Native: Stop Packager.

Step 6: Debug a Vega app

Vega Studio provides a built-in debugger. To use it, follow the instructions in Perform Line-by-Line Debugging with Vega Studio.

Step 7: 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 template contains the files and configurations required to run your app on Vega devices. This includes manifest files, native modules, and the proper directory structure.

Project templates

To see the list of available project templates:

vega project list-templates

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

helloWorld - Use this project template to create an app that depends on React Native v0.72.
basicTurboModule - Use this project template to create a custom Turbo Module.
idlTurboModule - Use this project template to create an app compatible with all supported React Native versions and native IDL APIs.

Step 1: Generate a project

Use the vega project generate command to create an app. The command takes four arguments:
- --template - The Vega project template (for example: helloWorld).
- --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 sampleapp. The command outputs the path to your project location.
vega project generate --template helloWorld --name sampleapp --packageId com.amazondeveloper.sampleapp --outputDir sampleapp
Navigate to your new app:
cd sampleapp

Step 2: Build your app

Install the dependencies and build:

npm install

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:

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

After a successful build, verify that the build folder contains .vpkg files for your target architecture.

VPKG file location

The build generates VPKG files in the following locations:General path structure:Development build:Release build:Example:

Project name: hellovega
VPKG location: ~/workspaces
Release VPKG location (to upload for app submission): ~/workspaces/hellovega/build/armv7-release/hellovega_armv7.vpkg

Metro, React Native’s JavaScript bundler, starts in the terminal window. It takes an entry file and returns a single JavaScript file that includes all 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.

​Prerequisites

​All build options

​Build an app with Vega Studio

​Step 1: Create a Vega project

​Step 2: Build a Vega app

​View the build output

​Step 3: (Optional) Configure a custom port

​Step 4: Run and test a Vega app

​On Vega Virtual Device

​On Fire TV Stick

​Step 5: (Optional) Stop the React Native Packager

​Option 1: Through the VS Code status bar

​Option 2: Through the VS Code Command Palette

​Step 6: Debug a Vega app

​Step 7: Analyze app performance

​Build an app using the Vega CLI

​Project templates

​Step 1: Generate a project

​Step 2: Build your app

​VPKG file location

​Step 3: Set up Fast Refresh

​Step 4: Run your app on Vega Virtual Device

​Related topics