Getting Started

To configure projects using Trapeze's configuration-driven experience, install the @trapezedev/configure package.

npm install @trapezedev/configure

note

For Android: Java must be on PATH or JAVA_HOME must be set to use Gradle operations. This is because the Gradle modification functionality uses a Java utility under the hood for accuracy, as Gradle is a Groovy DSL and Groovy is a JVM language. If you have Android Studio installed, you can use the JDK bundled with it. Note: JAVA_HOME should be set to the root of the JDK installation, not the /bin folder.

Usage

Then, assuming you have a Trapeze YAML configuration file to use, use the run command to process it.

npx trapeze run config.yaml --android-project android --ios-project ios/App

Where --android-project is the relative path to your Android project, and --ios-project is the relative path to your iOS Xcode project folder.

Here's a basic example YAML file:

config.yaml

platforms:
  android:
    versionName: 5.2.1
  ios:
    version: 16.4

Changes can be previewed using the --diff flag to see a unified diff of the changes to each file.

CLI options

By default run lists the changed files and then asks for confirmation before writing them. The following options are available:

Option	Description
-y	Apply the changes without asking for confirmation. Use this in CI, where nobody can answer the prompt.
--dry-run	Report the changes without writing them to disk.
--no-commit	Report the changes without writing them to disk, same as --dry-run.
--diff	Print a unified diff of the changes to each file.
--verbose	Print debug output for every file that is read and modified.
--quiet	Do not print the operations and the changed files.
--ios	Only run iOS operations. Project-level operations still run.
--android	Only run Android operations. Project-level operations still run.
--ios-project <path>	Path to the root of the iOS Xcode project (default: ios/App).
--android-project <path>	Path to the root of the Android project (default: android).

npx trapeze --version prints the installed version, and npx trapeze run --help prints this list for the version you have installed.

Writing Configuration Files

Configuration files are written in YAML. New to YAML? Read Learn YAML in five minutes.

See an Example Yaml Configuration for a real-world example using many of the supported features.

YAML anchors and merge keys (<<) are supported and can be used to share configuration between sections.

Variables and Environment Variables

Variables defined in the yaml vars section can be automatically supplied through environment variables of the same name, or interactively input by the user if not found in the environment and lacking a default value.

For example:

vars:
  MY_APP_ID:
  THIS_HAS_A_DEFAULT:
    default: true

In this case, MY_APP_ID has no default value, so MY_APP_ID must be found in the environment or an interactive prompt will display asking the user to input a value. THIS_HAS_A_DEFAULT will use the default value of true unless a value is provided in the environment.

Here's one example of providing an environment variable to the command:

MY_APP_ID="com.awesome.app" npx trapeze

JSON Variables

Variables can be strings or any JSON-parsable value. This makes them capable of being used for more complex configuration. Additionally, variable substitution also applies to any JSON values so references to other variables can be made:

vars:
    KEYCHAIN_GROUPS:
      default:
        [
          '$BUNDLE_ID',
        ]

platforms:
  ios:
    targets:
      App:
        entitlements:
          - keychain-access-groups: $KEYCHAIN_GROUPS

Variables as keys

Variables can also be used as map keys, which is useful for configuration that is keyed by a value such as the bundle id:

platforms:
  ios:
    targets:
      App:
        plist:
          - file: exportOptions.plist
            entries:
              - provisioningProfiles:
                  $BUNDLE_ID: $PROVISIONING_PROFILE

Variable types

Since: 7.0.3

Since environment variables are always strings, values that are meant to be numbers can be incorrectly processed. To specify the exact type a variable must have, use the type field when defining variables:

vars:
    NUMBER_VALUE:
      type: number

The supported types are string, number, array, and object.

string values will be consumed as-is, number values will be passed through parseInt(v, 10), and both array and object will be passed through JSON.parse(v).

Next steps

Follow the Android, iOS, and Project-level guides to see the full set of operations available for each platform.