Trapeze Documentation

Trapeze is a mobile project configuration toolbox designed to automate the management of native iOS and Android projects. It allows developers to automate modifications to files such as pbxproj, plist, XML, Gradle, JSON, resources, and properties files using a simple YAML configuration.

Trapeze supports several mobile frameworks, including:

• Traditional Native (iOS/Android)
• Ionic
• Capacitor
• React Native
• Flutter
• .NET MAUI

The goal of Trapeze is to enable fully immutable native mobile projects by moving configuration away from manual edits and into version-controlled configuration files.

Trapeze is a utility for managing native iOS and Android projects. It provides two primary ways to interact with mobile projects:

1. Configuration-driven tool: A CLI-based tool that processes a YAML configuration file to perform various project operations. It supports environment variables for dynamic configuration.
2. Node.js-based Project API: A programmatic API that abstracts common iOS and Android project management operations, allowing you to build custom automation scripts.

Trapeze supports traditional iOS and Android projects, as well as cross-platform frameworks like Ionic/Capacitor, React Native, and Flutter.

The Trapeze Configuration tool uses the Project API to perform automated modifications to mobile projects via a YAML configuration file. Key capabilities include:

• Android: Modifying AndroidManifest.xml files, modifying Gradle (Groovy) files using accurate AST-based modifications, and creating Android resource files.
• iOS: Configuring iOS project build settings with full support for targets, and updating .plist files and entitlements.

Variables are defined in the vars section of your YAML configuration. Trapeze attempts to resolve these in the following order:

1. An environment variable with the same name.
2. A default value specified in the YAML.
3. An interactive prompt (if no environment variable or default is found).

Variables can be strings or any JSON-parsable value (arrays, objects, etc.). You can also reference other variables using the $ prefix.

vars:
  MY_APP_ID:
  THIS_HAS_A_DEFAULT:
    default: true

# Example of variable substitution and JSON values
vars:
    KEYCHAIN_GROUPS:
      default:
        ['$BUNDLE_ID']

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

The Trapeze API operates on a virtual filesystem (VFS). No changes are written to your actual disk until you explicitly call project.commit(). You can preview pending changes by accessing project.vfs.all().

// Preview changes
const changedFiles = project.vfs.all();
changedFiles.forEach((f) => {
  console.log(f.getFilename(), f.getData());
});

// Save changes to disk
await project.commit();

You can automate Capacitor project configuration using a YAML file and the @trapezedev/configure package. Define your platform-specific changes (such as Android manifest injections or iOS target versions) in a YAML file, then run the Trapeze CLI to apply them.

Example config.yaml structure:

platforms:
  android:
    manifest:
      - file: AndroidManifest.xml
        target: manifest/application
        inject:
          <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  ios:
    targets:
      App:
        version: 16.4

npm install @trapezedev/configure
npx trapeze run config.yaml

Trapeze allows you to automate the configuration of Flutter projects for iOS and Android using a YAML configuration file. You can define platform-specific changes, such as injecting permissions into the Android Manifest or updating the iOS App version.

To use the configuration-driven experience:

1. Create a config.yaml file defining your desired changes.
2. Install the @trapezedev/configure package.
3. Run the Trapeze CLI pointing to your config file.

platforms:
  android:
    manifest:
      - file: AndroidManifest.xml
        target: manifest/application
        inject:
          <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  ios:
    targets:
      App:
        version: 16.4

npm install @trapezedev/configure
npx trapeze run config.yaml

Use the run command to process a Trapeze YAML configuration file. You must specify the paths to your Android and iOS projects using the --android-project and --ios-project flags.

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

When using @trapezedev/project in a TypeScript environment, ensure the dom library is enabled in your tsconfig.json under compilerOptions.lib.

{
  "compilerOptions": {
    "lib": ["dom", "esnext"]
  }
}

To automate Android project configuration using the configuration-driven experience, create a YAML file defining your operations. For example, you can inject permissions into the AndroidManifest.xml by targeting the manifest/application node.

First, install the configuration package and then run the Trapeze CLI pointing to your YAML file.

npm install @trapezedev/configure
npx trapeze run config.yaml