Convert an app to a base feature module

This guide describes how to convert an existing, full-feature app to a base feature module, or a feature module that's bundled in every instant app that you create. It then walks you through the process of extracting shared code into a minimal APK module.

After completing the process, your app's build process is separated from your app's logic, making it possible to convert part of the logic-based module to an instant app.

Designate your app as a base feature module

When you create an app, it automatically contains a module called "app". This section describes how to declare your app's logic as part of a base feature module.

To move your app's logic into a base feature module, complete the following steps:

  1. Rename your module to something like my_base_feature_module.
  2. Open your module's my_base_feature_module/build.gradle file and designate the module as a feature module by making the following change:

    my_base_feature_module/build.gradle

    // replace
    // apply plugin: 'com.android.application'
    // with
    apply plugin: 'com.android.feature'
  3. This module represents your app's base feature module, so mark it as such by setting the baseFeature flag to true:

    my_base_feature_module/build.gradle

    android {
        ...
        baseFeature true
        ...
    }

    Note: If your app has only one feature module, it must be designated as the base feature module.

Create an APK module

In the previous section, you created a module that contains some or all of your app's code. This section describes how to create a minimal app module, also known as the APK module, which contains the shared code necessary to build your app's APK file.

To create the APK module, complete the following steps:

  1. Select File > New > New Module...
  2. In the Create New Module dialog that appears, choose Phone & Tablet Module. Click Next.
  3. In the Phone & Tablet Module window, choose a module name and package name. This guide uses my_apk_module as the module name.

    Click Next.

  4. In the Add an Activity to Mobile window, select Add No Activity. Click Finish.

Android Studio finishes creating the APK module and loads it in the project window.

Associate the APK module with feature modules

You've created a feature module, but Android Studio doesn't include it in your app's APK file unless you associate it with your app's APK module. To do so, complete the following steps:

  1. Because an app's application ID declaration must always live within the Gradle module that declares com.android.application, the applicationID line needs to move from a feature module to the APK module.

    To do so, follow the instructions in these code snippets:

    my_base_feature_module/build.gradle

    android {
       defaultConfig {
           // remove this line
           // applicationId "com.mycompany.example"
           ...
       }
       ...
    }

    dependencies { // Add this line application project(":my_apk_module") }

    my_apk_module/build.gradle

    android {
        ...
        defaultConfig {
            // replace
            // applicationId "com.mycompany.example.my_apk_module"
            // with
            applicationId "com.mycompany.example"
            ...
        }
        ...
    }
  2. The APK module needs to build each of your app's feature modules. To do so, update the compilation dependencies, as shown in the following code snippet:

    my_apk_module/build.gradle

    dependencies {
        implementation project(':my_base_feature_module')
        // If your app contains feature modules other than the base
        // feature module, add dependency lines that are similar to the
        // following:
        // implementation project(':my_feature_module_1')
        // implementation project(':my_feature_module_2')
    }
  3. In the base feature module, update the AndroidManifest.xml file so that it contains the following contents:

    my_base_feature_module/src/main/AndroidManifest.xml

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
              xmlns:tools="http://schemas.android.com/tools"
              package="com.mycompany.example">
    ...
    </manifest>
  4. Each of your app's manifest files must reference a unique package, so update the name in your APK's AndroidManifest.xml as follows:

    my_apk_module/src/main/AndroidManifest.xml

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
              package="com.mycompany.example.app">
    </manifest>