How to migrate to AndroidX?

What is Android X?

AndroidX is a major improvement to the original Support Library, which is no longer maintained. Actually, it replaces the support library with different package names, while all other classes, methods, and fields are still the same. It is shipped independently from the Android OS and it also has the same backward compatibility as the old Support Library.

Version 28.0.0 is the last release of the Support library and it will not be maintained anymore. So, you should migrate as soon as possible, since also Google from 1st November requires that all app updates target SDK 28 or newer.

Migrate to AndroidX

Before we start, we need to do a few things.

1. First of all backup project manually. I am quite sure that most of you are using some VCS tool, but it is better to have one more backup solution.
2. Work on a separate branch and try to avoid refactoring your code while doing a migration.
3. Double-check that you are using Android Studio 3.2 or newer.

If you are using Android Studio 3.2+ you will have inside Refactor menu option to Migrate to AndroidX. If you try it, most likely you will face the following error.

You will not face this error if your project is already on API 28 and it has that Gradle plugin version. So, first, let’s solve those issues.

Increase SDK version to 28 or newer

compileSdkVersion 28
buildToolsVersion "28.0.3"
targetSdkVersion 28

Increase Gradle version

Inside the project build gradle file increase gradle version to 3.4.2 or a newer and press Sync.

dependencies {
    classpath 'com.android.tools.build:gradle:3.4.2'
}

You will probably face a Gradle wrapper error like this. This can be easily solved just by pressing Fix Gradle wrapper and re-import project.

Update gradle.properties

Add the following properties to gradle.properties file.

android.useAndroidX=true

The Android plugin uses the appropriate AndroidX library instead of a Support Library.

android.enableJetifier=true

The Android plugin automatically migrates existing third-party libraries to use AndroidX by rewriting their binaries.

Migrate to AndroidX, again

Now we should have everything ready for the migration, so let’s go to try Refactor > Migrate to AndroidX. You should see the following message to a backup project as a zip file.

I would recommend also to be even more sure and backup it once more as a zip file. After that, you should click Do Refactor as it is shown on the image.

What could go wrong?

A lot. Android Studio really helps a lot with this feature regarding migration, but still, a lot of things can go wrong. So, you will probably end up manually fixing a lot of stuff that was not properly converted from the Support Library to AndroidX. This really depends on your project and what things you are using from the support library and other third-party libraries, but here I will mention a few common messages that I got since I did this process a few times already and it seems that some errors are very common.

Error inflating class

This  was the most common error message for one of the following elements for me:

• DrawerLayout
• Toolbar
• ViewPager
• CardView
• RecyclerView

You can solve it by looking HERE at the full list of mappings between the support library and AndroidX. So, if you have any errors like inflating the wrong classes, just go to that link and compare package names and replace them. The easiest way to do it with COMMAND + SHIFT + R and enter first the old package and then a new package name and Replace All. You can see one example in the image below.

Those mappings errors can be in both Java and XML code, so you need to double-check everything and replace wrong mappings with the AndroidX variant.

ButterKnife and other annotation processors

If you use some annotation processor library like ButterKnife you will probably face the error from the image below. You can easily solve it by using the latest version of ButterKnife library or that other library. This is the error:

The given artifact contains a string literal with a package reference ‘android.support.v4.content’ that cannot be safely rewritten. Libraries using reflection such as annotation processors need to be updated manually to add support for androidx.

Run, test, release

After you fix all errors, you should run the app and go through all screens and test the functionality to be sure that everything still works properly after migration. This is really important to avoid fatal crashes that could be not so obvious during migration. I would also recommend releasing the app with a staged rollout to monitor crashes and user feedback.

Conclusion

This is one the biggest migration in Android and it is not so hard, but it should be planned and execute correctly since a lot of things are changed. So, here are my final conclusion tips:

• Backup your project.
• Do it on the separate branch.
• Stop major development work.
• Use Android documentation.
• Google and StackOverflow are your friends as always.

Good luck.

 

If you are interested in topics like this about development, you can follow me on Twitter @Zookey90.