[Proposal] Plugin development workflow with NativeScript 4.0

[radeva]

[Proposal] Plugin development workflow with NativeScript 4.0

As most of you know, previously we considered having breaking changes for plugins with NativeScript 4.0. The good news now is that this won’t happen!* What it means?

1. The CLI will have logic to build the plugin .aar file. The .aar will be built and saved in plugin’s platforms/android folder with filename - the plugin name (the one specified in package.json with some restrictions applied regarding the .aar files name convention).

2. The CLI will expose a command for building the .aar file in case you want to do this manually. This command will be used by the plugin authors to build the .aar file explicitly before publish. We highly recommend building your plugin .aar file and publish it with the package. Check FAQ for more information on the pros and cons of this approach.

NOTE: By using the plugin development workflow recommended in the plugin seed, there will be scripts and commands in place so that you shouldn’t care about the building of the .aar file. Also, by using tns run android --syncAllFiles, which is integrated in the seed workflow, any change you do to AndroidManifest.xml will result in rebuilding of the .aar file transparently for you.

3. The files that can be added to platforms/android are restricted to:
   AndroidManifest.xml
   Include.gradle
   *.aar
   *.jar
   *.md
   res folder
   jniLibs
   assets

Plugin's *.aar file will be built only when AndroidManifext.xml, res folder, jniLibs or assets are present in platforms/android. If the plugin's platforms/android folder contains only *.aar, *.jar - they will be consumed directly from the CLI. On the other hand include.gradle and *.md doesn't have anything to do with plugin's *aar so in this case also we won't create any *.aar file.

NOTE: In case any other native resources need to be used, the plugin author will need to create a native project and build the .aar file for the plugin explicitly. The CLI won’t handle any other files than the ones mentioned above. Practically this is something we also have today.

NOTE * For existing plugins containing resources in platforms/android folder that are not mentioned in the above list, there will be a breaking change. We are aware that this is about 1% of the existing plugins, so we will assist the plugin authors with the migration if needed.

4. We recommend specifying package name in AndroidManifest.xml by following the conventions for the package name. At some point this will become a requirement.

// Wrong

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

// Right

<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="org.nativescript.nativescriptimagepicker">

5. The plugin’s .aar file should be part of the plugin package in npm. All other files in platforms/android except for include.gradle, *.aar and *.jar can be npm ignored.

6. For plugin authors who need to use a native Android project, we will create a detailed documentation article with the recommended approach for this. In short we will recommend to:

• Have a folder (i.e. src-native) in the root of the repo containing the native project
• Copy the .aar file produced by this project to platforms/android so that the CLI can use it.

7. The development workflow provided in the NativeScript Plugin Seed will ensure that:
   • The package published always include the .aar file.
   • Using npm run demo.android from src folder watches for changes in platforms\android and rebuilds the .aar file for you.

FAQ

Why should I bother building .aar file for my plugin when the CLI can handle this out of the box?
Below you can find the Pros and Cons of both approaches:
Leave the CLI to handle building of plugin’s .aar file. With this approach the cons are for the application developers.
Pros

• No need to deal with .aar files
• No need to change my plugin development workflow

Cons (mainly for the app developers)

• If for some reason there is an error in the building of the .aar this will become visible in the customer’s app
• Building an .aar file for a plugin takes about 4 sec on SSD when an app is built for the first time (and each the platforms folder is deleted) so it affects the development workflow of the app developers. This means that having 10 plugins will add >=40sec to the app initial build time.

Build my plugin .aar file explicitly and publish it in npm. With this approach the pros are for the application developers.
Pros

• Any errors that might occur during this build will be visible to the plugin author prior to publishing the plugin
• No added time to application build time for applications using the plugin
  Cons
• Plugin development workflow is insignificantly changed.

Since building plugins aims for making the job of application developers easier, thus we recommend to plugin authors to build and publish their plugins’ .aar files.

I have an existing plugin, will I have to migrate it?
All existing plugins will continue working as is, except for the aforementioned 1% of plugins, which we will handle with plugin authors directly. In spite of this, we highly recommend to:

• Check if you’re using files different than the ones specified in point 3. If this is the case, probably you need to consider using a native project since the CLI won’t be able to handle the extra files there

NOTE: According to our research, 99% of the existing plugins use only the files listed in point 3 and using a native project won’t be required.

• Add package name to AndroidManifest.xml as explained in point 4
• Build the .aar file of your plugin using the provided CLI command as explained in point 2. This will be possible in 2 ways:
  • Run the demo of your plugin to make the CLI build the .aar file in plugin’s platforms/android folder
  • Call the CLI command for building the .aar file
  • Publish a version of the plugin. Make sure that include.gradle, *aar, *.jar are NOT npm ignored and exist in the plugin package. All other contents of platforms/android can be ignored.

I have an existing plugin. I want to build the .aar file for it and publish a package containing the .aar file as recommended. How can I do it?

It’s as easy as pie! See the previous question for the necessary steps.

I only have AndroidManifest.xml, what do I do?
All existing plugins having only AndroidManifest.xml will continue working out of the box. In spite of this, we highly recommend:

• Add package name to AndroidManifest.xml as explained in point 4
• Build the .aar file of your plugin using the provided CLI command as explained in point 2.
• Publish a version of the plugin containing the .aar file. Make sure that include.gradle, *aar, *.jar are NOT npm ignored and exist in the plugin package. All other contents of platforms/android can be ignored.

What files from platforms/android need to be part of the published package?
include.gradle, *aar, *.jar need to exist in the published package. All other files in platforms/android should be npm ignored.

Will I need to have Android Studio installed?
No, the CLI will take care to build the .aar file of your plugin.

What about the iOS project?
No changes there.

[nsplugins]

Proposal is already implemented in NativeScript 3.0