Expo - Semantic Release

An Expo implementation for semantic release, so you don't have to bother.

How it works

Semantic release will first determine a new version based on your likings. This plugin will then search for your Expo manifest(s) and update it accordingly. Not only will this update the version property within the manifest. It will also update the Android versionCode and iOS buildNumber platform too, based on the configuration.

Verify Conditions

Before such a smooth, carefree release can take place, the plugin must validate the existence of a manifest. This check takes place in the verify condition step of semantic release. The name of the Expo app, defined in the name property, is dumped to console to provide some feedback for successful validation.

Prepare

This plugin writes the actual changes to the manifest during preparation. After this step, you can publish to Expo, create a new build or add the changes in a release commit. The version property within the manifest is always updated. All of the platform specific changes are only applied when the platform is enabled.

It is highly recommended to add the Expo manifest (app.json) to the list of assets to include in the release commit.

Usage

Here is an example configuration with automated changelogs, package.json versions, Expo and git release commits.

{
    "verifyConditions": [
        "semantic-release-expo",
        "@semantic-release/changelog",
        "@semantic-release/git",
        "@semantic-release/npm"
    ],
    "prepare": [
        "semantic-release-expo",
        "@semantic-release/changelog",
        "@semantic-release/npm",
        {
            "path": "@semantic-release/git",
            "assets": [
                "CHANGELOG.md",
                "package.json",
                "package-lock.json",
                "app.json"
            ]
        }
    ],
    "publish": false,
    "success": false,
    "fail": false
}

Configuration

By default this plugin uses configuration that should work straight out of the box. Unfortunately, all apps are different and sometimes requires a specific release flow. To satisfy these needs, you can customize some of these settings below.

Multiple manifests

Normally, an Expo app should have a single manifest located at /app.json. But you might have good reasons to use non-standard or multiple manifests. For example, if you need to create multiple versions/flavours and allow then to work side-by-side, you need multiple manifests. To configure this plugin, you can provide a list of manifests to update.

{
    "prepare": [
        {
            "path": "semantic-release-expo",
            "manifests": [
                "app.test.json",
                "app.staging.json",
                "app.production.json",
            ]
        }
    ]
}

manifests accepts either a single string, or a list of strings.

Version templates

Unfortunately, right now there is no "universal" versioning which can be used across all platforms. For exmaple, iOS can simply use the exact semantic version (e.g. 2.5.1) but Android can't. To allow multiple "tactics" or personal favorites, you can change the so called "versioning templates". These templates uses lodash template to build new versions. Every version string, version, Android versionCode and iOS buildNumber can be modified independently.

{
    "prepare": [
        {
            "path": "semantic-release-expo",
            "versions": {
                "version": "${next.raw}",
                "android": "${code}",
                "ios": "${next.raw}"
            }
        }
    ]
}

versions accepts either a single string for all versions, or a (partial) object with templates. By default the ${recommended} template is used.

Version templates variables

Currently the following variables are available within the templates.

name	type	description
expo	SemVer	The semver-coerced Expo SDK version
last	SemVer	The semver-coerced last release version
next	SemVer	The semver coerced next release version
code	Number	The (Android) version code, using the versioning approach by Maxi Rosson
increment	Number	An incremented number of the previous version, discouraged because of non-deterministic behaviour.
recommended	String or Number	differs per versioning/platform, listed below

Recommended per version type

version	example	description
version	1.2.3	The "raw" next release version (also available in ${next.raw})
Android versionCode	290010203	The versioning approach by Maxi Rosson (same as ${code})
iOS buildNumber	1.2.3	The "raw" next release version (also available in ${next.raw})

In these examples Expo SDK 29.x.x and SemVer 1.2.3 is used.

License

The MIT License (MIT). Please see License File for more information.

---

with ❤️ byCedric & Contributors