Support for AndroidX in NativeScript

As many of you probably know AndroidX was announced at Google I/O 2018 as the major package renaming of the Android Support library. Like the Support Library, AndroidX ships separately from the Android OS and provides backwards-compatibility across Android releases. AndroidX fully replaces the Support Library by providing feature parity and new libraries.

Why Is AndroidX Important?

You can find an introduction to AndroidX in the dedicated blog post from the Android team but here is a summary of its main advantages:

• All packages in AndroidX live in a consistent namespace starting with the string androidx. The Support Library packages have been mapped into corresponding androidx.* packages.
• Unlike the Support Library, AndroidX packages are separately maintained and updated. The androidx packages use strict. Semantic Versioning starting with version 1.0.0 thus you will be able to update AndroidX libraries in your project independently.
• All new Support Library development will occur in the AndroidX library. This includes maintenance of the original Support Library artifacts and introduction of new Jetpack components.
• Moving to AndroidX will make new features introduced by Android more accessible. One example is Material Design widgets that are actively developed with AndroidX.
  

What Does This Mean for NativeScript?

The Google/Android team recommends that all projects using the Android Support Library should be migrated to AndroidX. As the NativeScript framework (cross-platform modules, plugins, and typings) relies heavily on Support Library classes and since Android Support Revision 28.0.0 is the last feature release under the android.support.* packaging we are now planning a migration effort to androidx for NativeScript 6.0 expected later this summer.

Note that Android Support Library and AndroidX cannot be used side by side in the same project hence starting with NativeScript 6.0 AndroidX will be the official and only version of the Supported Library functionality and we want to ensure that migration path to AndroidX for NativeScript app and plugin developers is as smooth and straightforward as possible.

To this end we have now released packages that are fully migrated to AndroidX - `tns-core-modules@androidx`, `tns-core-modules-widgets@androidx`, `tns-platform-declarations@androidx` and `tns-android@androidx`. These packages can be used for testing and migration of existing projects. Both application and plugin developers can refer to these packages when migrating their projects.

Prerequisites for the Migration

Migrating to a new code library is a process that takes time and some preparations have to be done first:

• Plugins relying on Support Library namespaces should be migrated in order to work with NativeScript 6.0 apps (we recommend creating branch or package that works with the test packages from above)
• Applications with code relying on Support Library namespaces should be migrated in order to work with NativeScript 6.0

Note: These packages are intended for testing and migration purposes only. We strongly advise against developing new features and production apps with them until they are officially released with NativeScript 6.0.

Note: applications using `tns-core-modules@androidx` can only work with plugins and apps migrated to the new AndroidX namespaces. Any Support Library calls/namespaces should be changed to the new AndroidX ones.

Migration FAQs

Q: How can I start migrating my NativeScript project?

We have provided two sample apps migrated to AndroidX - sample-androidx-ts and sample-androidx-ng. These are just blank apps, with no extra plugins. If you take a look at the package.json file you'll see specific versions for some dependencies:

• "tns-core-modules": "^5.4.0-androidx-2019-XX-XX-XXXX" - NativeScript core modules package using AndroidX. >/li>
• "tns-platform-declarations": "^5.4.0-androidx-2019-XX-XX-XXXX" (optional)  - NativeScript typings supporting AndroidX
• "tns-android": "5.3.0-XXXX-XXXX-XXX” - NativeScript Runtime version for AndroidX

You can use these apps as a starting point for your application or plugin migration.

Q: I'm a NativeScript application developer. How am I affected by this AndroidX migration?

If you plan to migrate to tns-core-modules@6.0 as soon as it’s released you should evaluate whether or not your app needs to be migrated, because tns-core-modules@6.0 will enable AndroidX by default. There are a few keypoints to prepare your app:

• (mandatory) Install NativeScript AndroidX specific dependencies:
  • `npm install tns-core-modules@androidx --save-exact`
  • `tns platform add android@androidx`
  • `npm install tns-platform-declarations@androidx --save-exact` (optional if you want typings)
• (if needed) Migrate your application code to the new AndroidX namespaces. Since NativeScript framework enables access to native Android APIs through JavaScript, you should check your app code for any Support Library namespaces. For instance, you should change
  new android.support.v7.widget.Toolbar(..)
  to
  new androidx.appcompat.widget.Toolbar(..)
  if used somewhere in your javascript/typescript. It is possible to have Support Library namespaces not just in your app code but also in some .gradle or .xml files. Gradle files could request dependencies to some support library version e.g. Consider searching for namespaces in all your application files.
• (if any) Migrate your application dependencies to versions that support AndroidX. Last but not least you should review your app dependencies as it is almost certain that you are using some NativeScript plugins or Android plugins (dependencies in .gradle files) in your application. It is possible that some of the dependencies rely on Support Library, which will result in classes collision (app won’t build or it will crash, because of missing Support Library classes). You should check if all your dependencies are compatible with AndroidX. Please consider that migrating Support Library depending plugins is an ongoing process. Some plugins might not need any migration but other could need time to migrate. That is why it’s a good idea to check your application now and signal us or the plugin authors accordingly.

You can check here for the full mappings from the old namespace to the new AndroidX packages.

Q: I’m a NativeScript plugin developer. How am I affected by this AndroidX migration?

There are several things you need to do to prepare your plugin for support of AndroidX:

• Migrate your plugin code (java, javascript/typescript) to the new AndroidX namespaces.
  Your NativeScript Android plugin may contain both native java and JavaScript/TypeScript code. All Support Library namespaces presented in JavaScript/TypeScript should be migrated to the new AndroidX ones manually. When it comes to migrating the native java part of your plugin, there are a few options . You could use Android Studio (3.2 and higher) to quickly migrate the project by selecting Refactor > Migrate to AndroidX. This will search the entire native project for Support Library classes and suggest a refactoring to the new AndroidX namespaces.
  The Android Studio migration tool is a good choice, but you should also consider manually searching and replacing all namespaces with the corresponding ones for greater reliability.
  If you choose to use the Android Studio to migrate consider manually checking and comparing all the suggestions made by the migration tool, since there are some known issues (related to proper mapping of namespaces) when it comes to the auto migration tool.
• Migrate your application dependencies to versions that support AndroidX. Except the npm packages, described in the previous topic, it’s possible that your plugin depends on some other native plugins - android plugins, custom aars or jars. Consider testing if they are all compatible with AndroidX. Also consider updating your build.gradle. It’s a common practice to set some Support Library artefacts there:

   

  dependencies {

    implementation 'com.android.support:appcompat-v7:28.0.0'

    implementation 'com.android.support:recyclerview-v7:28.0.0'

  }

Q: Is there a tool that can help with the migration?

There is a tool (androidx-migration-tool) that can help you migrate Support Library namespaces and artefacts. It is a simple NodeJS package that  takes your project root directory as an argument to start the migration process. Consider using ns-androidx-migrate for project directory under source control since it will search and replace files directly. This tool will not do all the migration steps required, you still need to manually update any artefacts strings, dependencies and plugins. Please check the README before using it.