November 2, 2021
  • All
  • Announcements
  • Product
  • Capacitor

Automated Capacitor Project Configuration with Capacitor Configure

Max Lynch

CEO

Many developers need to script and automate the configuration of their Capacitor projects. For example, apps that generate multiple versions of themselves for whitelabeling, automated tooling that needs to update version and build numbers, or plugins that need to automatically configure user projects to correctly run and use the plugin.

Until now, developers had to manually write scripts to read and write complex iOS and Android project settings, resulting in error-prone code and extra project maintenance. Today, we are releasing the first version of a utility that should make managing Capacitor projects through code or configuration much easier: Capacitor Configure.

Capacitor Configure comes with two useful packages that developers can use depending on their needs: @capacitor/project, a JavaScript/TypeScript library and API used for writing custom configuration scripts, and @capacitor/configure, an automated configuration tool based on a YAML file spec. Both have similar functionality but are targeted at two different use cases.

Let’s explore the Project API first:

Project API

The Project API is useful for writing complex, custom project management scripts, and handles the messy bits of managing Xcode pbxproj files, Android Manifest/Gradle files, and more.

To use it, install and import from the @capacitor/project package and initialize it:

import { CapacitorProject } from '@capacitor/project';
import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  ios: {
    path: 'ios',
  },
  android: {
    path: 'android',
  },
};

const project = new CapacitorProject(config);
await project.load();

Then, operations on the iOS and Android portions of the project can be performed. Here’s a small example of setting and incrementing build numbers and versions on iOS and Android:

project.ios.setBuild(targetName, buildName, 42);
project.ios.incrementBuild(targetName, buildName);
project.ios.setVersion(targetName, buildName, '1.2.3');


await project.android.setVersionName('1.0.2');
await project.android.setVersionCode(11);
await project.android.incrementVersionCode();

There are many other operations, see the project readme to explore the capabilities of the Project API.

Configuration Tool

The @capacitor/configure package provides a YAML-based configuration tool that uses the Project API under the hood, and is particularly well suited to plugin configuration and other scenarios where a set of well-defined configuration changes must be made against a project. The tool has some additional features, such as variable support, interactive mode to confirm changes, and dry run mode.

In fact, the configuration tool was the initial focus of this project as the Ionic team has built and shipped some very complicated plugins, like Microsoft Intune, that require considerable amounts of configuration which we wanted to make much easier.

Here’s an example of a YAML file that declares a set of configuration options that will be made against a project:

vars:
  BUNDLE_ID:
    default: io.ionic.greatStarter
  PACKAGE_NAME:
    default: io.ionic.greatStarter
  REQUIRED_VARIABLE:

platforms:
  ios:
    targets:
      App:
        bundleId: $BUNDLE_ID
        version: 16.4
        incrementBuild: true
        productName: Awesome App
        displayName: My Awesome App

 android:
    packageName: $PACKAGE_NAME
    versionName: 1.2.3
    incrementVersionCode: true

    manifest:
      - file: AndroidManifest.xml
        target: manifest/application
        attrs:
          android:name: com.ionicframework.intune.IntuneApplication

This is just a small sampling of the options available in the configuration file. See the full example file for all the different options supported in the YAML configuration file.

To run the tool, install it and then run

npx cap-config run config.yml

Getting Started

This is a new project and we want your feedback on problems you’re trying to solve through automation, to make sure this tool is truly achieving the goal of liberating developers from writing custom configuration scripts that work with low-level native project configuration files and project structure.

We are also working on documentation for the tool and integration into the standard Capacitor workflow and integration into Appflow once the project matures.

Give it a try today and let us know what you think!

P.S. We’re hiring!

Capacitor has been growing quickly lately and powering thousands of app store apps. We’re looking for a Lead Engineer to help take Capacitor to the next level. Is that you? Learn more here.

Max Lynch

CEO

Related Posts