Vega Build Flavors

Vega Open Beta Knowledge Base
1

Build flavors let you create different versions of an application from a single codebase. They allow customization of features, resources, and configurations to target different audiences, environments, or requirements.

Key features:

  1. Environment-Specific API Endpoints: Each environment can have its own API base URL
  2. Configurable Logging: Different log levels per environment (debug, info, warn, error)
  3. Debug Mode Control: Enable/disable debug features per environment
  4. Type Safety: Full TypeScript support with proper type definitions
  5. Easy Integration: Simple imports to use environment configuration anywhere in your app
  6. Automatic Environment Detection: Helper functions to check current environment
  7. Environment-Aware Logging: Logging that respects the configured log level

How to add build flavors in Vega

One way of adding build flavors for use in a Vega app is covered in this walkthrough. We use react-native-dotenv, which transforms imports at build time using Babel config for ease of access from the JS side.

Let’s use the Vega Video Sample App for this demo.

Download extract_build_flavors.py.zip (8.5 KB) and copy extract_build_flavors.py to the root of your project.

Untitled
Untitled405×299 31.6 KB

Open a new terminal window at your project root and run:

python3 extract_build_flavors.py --extract-all

Available commands for later use:

# Show help and all options
python3 extract_build_flavors.py --help
# Extract all build flavor files (recommended for first-time setup)
python3 extract_build_flavors.py --extract-all
# Switch to specific environment
python3 extract_build_flavors.py --environment qa
python3 extract_build_flavors.py --environment beta
python3 extract_build_flavors.py --environment prod
# Show current environment configuration
python3 extract_build_flavors.py --show-current
# Enable verbose output
python3 extract_build_flavors.py --extract-all --verbose

Once you run the script, the project will have the necessary files to build targeted binaries for dev, QA, beta, or production.

Let’s look at the result of script execution.

1. Environment files created at project root:

  • .env — Default development environment
  • .env.qa — QA environment with debug logging
  • .env.beta — Beta environment with info logging
  • .env.prod — Production environment with error-only logging

Use these files to add information specific to your build environment. For example, .env.prod:

# Production environment
API_BASE_URL=https://api.example.com
ENVIRONMENT=production
DEBUG_MODE=false
LOG_LEVEL=error

Make sure you add the correct API endpoints, environment details, and debug modes to the rest of your environment files.

2. Directory structure created:

  • src/config/, src/services/, types/, build/qa/, build/beta/, build/prod/

3. TypeScript configuration files added:

  • src/config/Environment.ts — Environment configuration utilities [inspect and extend this further based on your project]
  • types/env.d.ts — Type declarations for environment variables
  • src/services/ApiService.ts — API service with environment-aware endpoints
  • src/components/EnvironmentInfo.tsx — React component to display environment info

4. package.json updated with build scripts:

  • Build scripts for all environments (QA, debug, beta, prod)
  • Both debug and release build options
  • Complete build, install, and launch commands

5. Documentation added:

  • BUILD_FLAVORS.md — Quick reference guide
  • PYTHON_SCRIPT_USAGE.md — Explains how to use the extract_build_flavors.py script

6. Project structure after running the script:

build_flavors_package/
├── .env
├── .env.qa
├── .env.beta
├── .env.prod
├── extract_build_flavors.py
├── BUILD_FLAVORS.md
├── PYTHON_SCRIPT_USAGE.md
├── src/
│   ├── config/
│   │   └── Environment.ts
│   ├── services/
│   │   └── ApiService.ts
│   └── components/
│       └── EnvironmentInfo.tsx
└── types/
    └── env.d.ts

7. Sample run output:

user@machine123 KeplerVideoSampleApp % python3 extract_build_flavors.py --extract-all
🚀 Extracting build flavor files...
📁 Project root: /path/to/project
✓ Created directory: src/config
✓ Created directory: src/services
✓ Created directory: src/components
✓ Created directory: types
✓ Created directory: build/qa
✓ Created directory: build/beta
✓ Created directory: build/prod
✓ Created environment file: .env
✓ Created environment file: .env.qa
✓ Created environment file: .env.beta
✓ Created environment file: .env.prod
✓ Created config file: src/config/Environment.ts
✓ Created config file: types/env.d.ts
✓ Created config file: src/services/ApiService.ts
✓ Created config file: src/components/EnvironmentInfo.tsx
✓ Added 12 build flavor scripts to package.json
✓ Created BUILD_FLAVORS.md documentation
✅ Build flavor extraction completed!
📋 Next steps:
1. Update API endpoints in .env.qa, .env.beta, .env.prod
2. Run 'python3 extract_build_flavors.py --environment qa' to switch to QA
3. Run 'npm run build:qa' to build for QA environment
4. Run 'npm run app:build:qa' to build, install & launch QA version
📋 Current Environment Configuration:
API_BASE_URL=https://dev-api.example.com
ENVIRONMENT=development
DEBUG_MODE=true
LOG_LEVEL=info

8. Using build flavors in your code:

Once the setup is complete, here’s how to use it in your app’s entry point:

import { getApiEndpoint, isProduction, envLog } from './src/config/Environment';
import { ApiService } from './src/services/ApiService';

// Get environment-specific API endpoint
const endpoint = getApiEndpoint('/content');

// Environment-specific behavior
if (isProduction()) {
  // Production-only code
}

// Environment-aware logging
envLog.debug('This only shows in debug mode');

// Use the API service (automatically uses correct endpoint)
const content = await ApiService.getContent();

The script creates starter template files that you then customize with your actual URLs. Once your .env files are set up with the correct settings, you can build targeted versions of your app by triggering the specific build scripts from package.json (see section d.2 in Manual Mode below).

9. Troubleshooting

  1. Permission denied: Run chmod +x extract_build_flavors.py
  2. Python not found: Make sure Python 3 is installed: python3 --version
  3. Files not created: Check if you have write permissions in the project directory
  4. Script doesn’t run: Ensure you’re in the correct project directory and the script file exists
  5. react-native-dotenv not working:
    • Check that npm install was run after dependency addition
    • Verify babel.config.js has the react-native-dotenv plugin
    • Ensure .env files exist and have correct format
  6. TypeScript compilation errors:
    • Check TypeScript compilation with npm run typecheck
    • Verify that types/env.d.ts exists and is properly configured
  7. Babel configuration issues:
    • Check if babel.config.js.backup was created
    • Restore from backup if needed: cp babel.config.js.backup babel.config.js

10. Debugging

Run the script with verbose output:

python3 -v extract_build_flavors.py --extract-all

Check current environment configuration:

python3 extract_build_flavors.py --show-current

Parallel installs with environment-specific package identifiers

The setup above handles environment-specific API endpoints and logging. Now let’s look at how to test multiple environments (QA, Beta, Production) in parallel on the same device using unique package identifiers.

With this approach, com.yourcompany.app.qa and com.yourcompany.app.beta can point to different endpoints and carry different levels of logging while both installed on the same device.

Using the Vega Video Sample App, download extract_build_flavors_v2.zip (16.6 KB) and extract it to your project root.

Run the script:

# Automatic package ID detection
python3 extract_build_flavors.py --extract-all
# Install dependencies
npm install

The script automatically:

  • Detects the base package ID from manifest.toml
  • Creates environment-specific configurations
  • Updates build configurations
  • Adds necessary build scripts
  • Enables installation of multiple app versions on the same device

Switch environments and build:

# QA environment
python3 extract_build_flavors.py --environment qa
npm run app:build:qa:debug
# Beta environment
python3 extract_build_flavors.py --environment beta
npm run app:build:beta
# Production release
python3 extract_build_flavors.py --environment prod
npm run app:build:prod

If your Vega device is connected, the vpkg will be pushed and installed. The system generates environment-specific files:

QA Environment (.env.qa):

API_BASE_URL=https://qa-api.example.com
ENVIRONMENT=qa
DEBUG_MODE=true
LOG_LEVEL=debug
PACKAGE_ID=com.amazondeveloper.keplervideoapp.qa
COMPONENT_ID_PREFIX=com.amazondeveloper.keplervideoapp.qa
APP_NAME=Keplervideoapp QA

Production Environment (.env.prod):

API_BASE_URL=https://api.example.com
ENVIRONMENT=production
DEBUG_MODE=false
LOG_LEVEL=error
PACKAGE_ID=com.amazondeveloper.keplervideoapp
COMPONENT_ID_PREFIX=com.amazondeveloper.keplervideoapp
APP_NAME=Keplervideoapp

Verify the updates to manifest.toml for each environment:

[package]
id = "com.amazondeveloper.keplervideoapp.qa"
title = "Keplervideoapp QA"
[[components.interactive]]
id = "com.amazondeveloper.keplervideoapp.qa.main"
[[processes.group]]
component-ids = ["com.amazondeveloper.keplervideoapp.qa.main"]

The troubleshooting steps from the section above still apply.

Manual Mode (skip if you used the script above)

Although the process above is automated via scripting, you can also step through it manually if you want to create and customize everything yourself.

Download the required package: build_flavors_package.zip (21.9 KB)

a. Unzip the package

b. Copy to your project

Copy the extracted files to your project root, maintaining the directory structure:

# Copy environment files to project root
cp .env* /path/to/your/project/
# Copy Python script and documentation to project root
cp extract_build_flavors.py BUILD_FLAVORS.md PYTHON_SCRIPT_USAGE.md /path/to/your/project/
# Copy TypeScript files maintaining directory structure
cp -r src/ /path/to/your/project/
cp -r types/ /path/to/your/project/

Follow the same directory structure shown in step 6 above.

c. Install dependencies

npm install react-native-dotenv --save-dev

Update babel.config.js to add the plugin:

module.exports = api => {
  const plugins = [
    // ... other plugins
    ['module:react-native-dotenv'],
    // ... other plugins
  ];
  return {
    presets: [
      // your presets
    ],
    plugins,
  };
};

d. Update package.json

  1. Add "react-native-dotenv": "~3.4.11" to "devDependencies"
  2. Add the following to the "scripts" section:
"build:qa": "cp .env.qa .env && npm run build:release",
"build:beta": "cp .env.beta .env && npm run build:release",
"build:prod": "cp .env.prod .env && npm run build:release",
"build:qa:debug": "cp .env.qa .env && npm run build:debug",
"build:beta:debug": "cp .env.beta .env && npm run build:debug",
"build:prod:debug": "cp .env.prod .env && npm run build:debug",
"app:build:qa": "npm run build:qa && npm run app:install && npm run app:launch",
"app:build:beta": "npm run build:beta && npm run app:install && npm run app:launch",
"app:build:prod": "npm run build:prod && npm run app:install && npm run app:launch",
"app:build:qa:debug": "npm run build:qa:debug && npm run app:install:debug && npm run app:launch",
"app:build:beta:debug": "npm run build:beta:debug && npm run app:install:debug && npm run app:launch",
"app:build:prod:debug": "npm run build:prod:debug && npm run app:install:debug && npm run app:launch"

At this point you’re set to update your app’s entry point to handle build-level settings as shown in step 8 above, and trigger builds using the scripts in d.2.

To avoid disruption while replicating this on your existing build pipeline, please back up your work. It is strongly recommended that you work off a new branch until the desired outcome is verified.

Last updated: Mar 11, 2026

1 Like