Overwrite Native Configurations¶

You can automatically overwrite your native Android and iOS project configurations before building in Capawesome Cloud. This is useful for modifying app identifiers, display names, version numbers, and other native configurations based on your build environment or branch.

This guide shows you how to use Trapeze, a mobile app configuration tool, to automate native project modifications during the build process.

Installation¶

First, install Trapeze as a development dependency in your project:

npm install --save-dev @trapezedev/configure

Configuration File¶

Create a configuration file named capawesome.yml in the root of your project. This file defines the native configurations you want to overwrite.

Here's a basic example that modifies the App ID and display name:

platforms:
  android:
    packageName: com.example.myapp
    appName: My App
  ios:
    bundleId: com.example.myapp
    displayName: My App

Platform-specific configurations

Trapeze uses platform-specific keys for similar configurations. For example, Android uses packageName while iOS uses bundleId. Refer to the Android and iOS operation guides for complete lists of available configurations.

Build Script¶

Add an npm script to your package.json that runs Trapeze for Android and iOS platforms before the web build process:

{
  "scripts": {
    "capawesome:build": "if [ \"$CI_PLATFORM\" = \"ios\" ] || [ \"$CI_PLATFORM\" = \"android\" ]; then npx trapeze run capawesome.yml -y --$CI_PLATFORM; fi && npm run build"
  }
}

Capawesome Cloud automatically calls the capawesome:build script during the build process. The script conditionally runs Trapeze only for iOS and Android platforms using the $CI_PLATFORM environment variable.

Using Environment Variables¶

You can use Capawesome Cloud's environment variables to dynamically configure your native projects. This is particularly useful for overwriting configurations based on your build environment.

Define Variables¶

First, define variables in your configuration file:

vars:
  APP_ID:
  APP_NAME:

platforms:
  android:
    packageName: $APP_ID
    appName: $APP_NAME
  ios:
    bundleId: $APP_ID
    displayName: $APP_NAME

Set Variable Values¶

Then, set the variable values in your Capawesome Cloud environment:

Navigate to the Environments page
Select your environment or create a new one
Add variables with their values:
APP_ID: com.example.myapp
APP_NAME: My App

You can create multiple environments with different values (e.g., development, staging, production) and select the appropriate environment when triggering a build.

Default values

You can provide default values for variables that will be used if no environment variable is set:

vars:
  APP_ID:
    default: com.example.default
  APP_NAME:
    default: Default App Name