Will Capacitor replace Cordova? An overview of possibilities.

by Adrian Nowakowski

Takeaways

1. What is Capacitor and why it’s worth trying it out?

2. Getting started with Capacitor

3. Starting an application using Capacitor

4. Additional native Capacitor plug-ins

5. If Capacitor works well, what about Cordova?

6. Summary

Developer’s highlights

Takeaways

Capacitor may be treated as a natural step forward of the Ionic project.

Capacitor will be able to use Cordova plug-ins.

Cordova project should still be supported. It will be available as an alternative to Capacitor.

The Capacitor community will grow rapidly thanks to the framework’s promising capabilities (easy integration with native platforms).

In the future, Ionic4 may be shipped with Capacitor only.

1. What is Capacitor and why it’s worth trying it out?

Currently, Capacitor is available in a beta version:

https://github.com/ionic-team/capacitor

https://capacitor.ionicframework.com/

In a nutshell, how can we benefit from using Capacitor?

  • The solution works with Ionic and JavaScript.
  • It can integrate with Cordova plug-ins.
  • Has its own functionality and approach to managing interaction with an OS native shell.
  • The premium version provides additional elements (such as extra plug-ins etc.).
  • It allows to create applications based on PWA.

Capacitor is an alternative to Cordova and allows users to create applications based on Progressive Web App (PWA). We don’t need to worry about a target platform for our solution. Capacitor has a similar approach to Cordova — one source code is generated, and it is used to start an application within many platforms: mobile (Android, iOS), web (PWA), and desktop (Electron). Ionic team claims that Capacitor constitutes a mixture of Cordova and Turbolinks with a pinch of React Native. This allows us to create modern mobile applications (named by Ionic Team as ‘’Native Progressive Web Apps’’).

The combination of Capacitor and Ionic Framework breeds a very interesting and effective choice. The Ionic Framework provides a multi-platform web interface controls, and Capacitor provides access to runtime environment (Native SDK).

I suspect that soon Capacitor is going to become very common for Ionic4 projects.

In 2019 Capacitor is expected to become a mature solution — official and recommended for applications based on Ionic. Capacitor is supposed to fully replace Cordova and take care of the communication with native functionalities of an OS. It will also provide plug-ins that will allow to fully use all the possibilities of a mobile device.

The year 2019 is going to be a period of stability for Capacitor, and probably the first production release of 1.0 Capacitor version. What can we expect

  • Having Capacitor as a part of Ionic CLI.
  • Open distinction between Free and Premium versions; Capacitor will be integrated into Ionic Pro.
  • A significant growth in the community since Capacitor is going to be a recommended solution available within Ionic CLI (especially given that Cordova is not always stable and carries certain issues and problems).

Everything looks promising, so let’s delve into the practice.

2. Getting started with Capacitor

Capacitor can be installed in two ways. The first one is to use npm and then to add it to the existing front-end project (an approach recommended by the creators). The second one is to create a new project using Capacitor CLI (however, this way we will get a project with only a simple initial structure).

At a higher level, the use of Capacitor is quite similar to that of Cordova. We create a new project, e.g. using the Ionic framework, and then we install Capacitor so that it could manage the connection with a native layer of the operating system.

What’s more, thanks to PWA, Capacitor provides runtime API for web applications.

The full installation process is described and can be found here: https://capacitor.ionicframework.com/docs/getting-started/

Basic pre-installation requirement is having a Node.js > 8.6.0 and npm > 5.6.0 in the system. For iOS development, we need IOS Xcode > 9 and cocoapods (a package manager for Swift and Objective-C).

3. Starting an application using Capacitor

Next, I created a new project (Ionic4 Framework), where I added Capacitor, using npm:

$ npm install — save @capacitor/core @capacitor/cli

This is an approach recommended by the creators of Capacitor. To start Capacitor and to add its configuration, run:

$ npx cap init

The configuration process takes place in steps and leads through basic elements required by Capacitor to generate configuration in the existing projects:

The process consists of two steps:

After the configuration process, there will be a new configuration file created in the project:

capacitor.config.json

It includes the configuration entered before:

Next, to check if the configuration has been carried out properly and if the application works, I built a new production version of an application. You can do it, running a command:

$ npx cap serve

Thanks to that, I can host the application locally using Capacitor.

The application will start as a Progressive Web App in a browser.

It takes just a second, and the application works very quickly.

I added a plug-in to my trial application, which will make it possible to read my current geolocation: https://capacitor.ionicframework.com/docs/apis/geolocation (the plug-in is delivered directly by Capacitor).

A photo of the application with the location as a toast directly in the browser:

Before running an application on an existing or emulated device, we need to install all the Capacitor’s dependencies that are necessary for a given development platform. For instance, before starting an application for iOS Capacitor platform, we need the cocoapods package. CocoaPods is a dependency manager which can be used while creating an iOS application (Objective-C). All the Capacitor’s requirements for iOS can be found in the documentation: https://capacitor.ionicframework.com/docs/getting-started/dependencies/

After the installation of cocoapods we can move on and add an iOS platform to the application. In order to add a new platform by means of Capacitor, we need to use the following command:

$ npx cap add ios

The command will create a new catalogue with a project for an iOS platform, which can be open using xcode, i.e. native environment for iOS application. The project also contains basic plug-ins required by the platform and our swift-language project (we will find there the source code of our native iOS app).

Capacitor is also equipped with a useful tool sync. It can transfer changes made in an Ionic application directly to a project with an iOS platform:

$ npx cap sync

Another command that allows to start an application directly in xcode:

$ npx cap open ios

Next, we can rebuild an application in the native IDE xcode and start it in an emulator:

3.1. Testing an application on an existing device

We deal with the same installation process as in Ionic Cordova or while writing a native application. In the iOS system we need to remember about creating a new team and a temporary certificate for the application. Next, we have to mark the application as trusted directly on our device (Settings/General/Device Management/Developer app/ and choose the ‘’Trusted” option).

Then, we can start the application and test it on a mobile device:

The application remains in a debug mode, so I have access to the application’s outputs and logs.

3.2. Troubleshooting and useful tips

Capacitor uses the configuration saved in the file: capacitor.config.json, where we can find basic elements necessary for starting an application.

In the configuration file, we can find some information of where Capacitor should look for a root of an application that will be hosted as e.g. PWA in a browser.

This file will be also useful if we want to add a new platform to our application (e.g. iOS). By default, Capacitor reads files from www catalogue, which is created while building an application, after using the command: npm run build or ionic build. If we don’t rebuild the application before adding a new platform, Capacitor will crash while installing it and will display a notification that it cannot find a specific location indicated in the configuration file.

Another problem concerns iOS platform. It was very often the case that while adding a new iOS platform to my application and trying to rebuild it in Xcode, I got a message about a code error. The solution is to rebuild the catalogue for Pods once again, i.e. to delete the Pods catalogue which can be found in the following location: proj/Ios/App/Pods. Then, the problem is solved by pod install command (more can be found on: https://cocoapods.org/).

Sometimes, the application gets stuck on a SplashScreen (an application is started in an emulator or on an existing device). The problem can be solved in several ways. The first solution is to install SplashScreen and configure its lifetime in the application. The second solution is to write the correct configuration in a file capacitor.config.json and to instruct the Capacitor to ignore the SplashScreen. It’s also possible to uninstall the SplashScreenmodule from the project (command: npm uninstall — save cordova-plugin-splashscreen).

In my case, I added the correct configuration. As a result, the application ignored SplashScreen pack from Cordova.

My configuration for capacitor.config.json after changes:

Adding the correct configuration and launchAutoHide option: true solves this problem. Then, we need to rebuild the application and copy all the necessary dependencies to the iOS platform. After that, we can build and start a project once again using Xcode.

What turned out to be useful while analysing the problem was log output that was directly in Xcode, so I recommend you to read and observe what is happening with the application in runtime.

4. Additional native Capacitor plug-ins

By default, our project is supposed to have a defined mobile platform. In my case it is iOS. The plug-in which I’m going to use gives me access to a native functionality of the OS.

First, we need to make sure that the Camera plug-in includes defined authorisations in info.plist file. If we don’t define such authorisations, the operating system will block the possibility of starting and using a given native set. The info.plist file can be found in the following location: …/IOS/App/App/info.plist . In our case, the file should contain a definition of access to the camera in the form of a key-value pair:

<key>NSCameraUsageDescription</key>

<string>To Take Photos and Video</string>

Capacitor should enter this value on its own into the info.plist file. However, it’s worth knowing where to look for the definition of an access token to a device’s resource.

Another step is to implement the functionality using the plug-in. The process is described in detail in the documentation available on website: Capacitor camera.

After the implementation process is complete, we need to rebuild the application using the following command:

$ npm run build

If we skip this step, plug-in implementation information will not be built, and as a result, the plug-in will not become a part of the application. We need to rebuild the app according to guidelines mentioned in the troubleshooting section.

The next step is to run the following command:

$ npx cap copy

The command will start the process of copying the requirements from www catalogue to iOS platform catalogues. All we need to do now is to start a native runtime environment (Xcode) using a command:

$ npx cap open ios

Within Xcode context, we will be able to install an application directly on our device.

After installing the application, I can start testing the plug-in. After choosing Take Picture button, the application should ask us to confirm the access to the device’s camera.

Next, after confirming the access, we should be given access to the camera and take a photo which should be visible on the first page of the beta application.

In my case, using the camera plug-in went quite smoothly without any problems.

5. If Capacitor works well, what about Cordova?

Why did the Ionic team decide to come up with a new solution instead of focusing on increasing the stability and extending the possibilities of the very Cordova?

Cordova is an open source project, but it belongs to Apache company. It can be said that this is a kind of political stalemate. Additionally, by rebuilding the Cordova project completely, Ionic Team would need to take care of full backward compatibility. The projects that are currently using Cordova would need to adjust to a new version of the framework, and that’s why the safest and most reasonable idea would be to find a different solution in the Capacitor documentation.

6. Summary

Since this is relatively a new solution, we can’t expect to have such a big community as in the case of a long-standing Cordova project. However, at this very moment Capacitor provides very interesting opportunities and approach to mobile application development based on various mobile platforms:

  • Intuitive syntax of the command line.
  • It’s fast.
  • Based on PWA solution.
  • Makes it possible to create native solutions on popular platforms such as mobile (Android, iOS), web (PWA), and desktop (Electron).
  • Provides a full possibility to compile platforms to their native language using one base source code.

Capacitor may be treated as a natural step forward of the Ionic project. While I’m writing this article, Capacitor offers quite a limited number of plug-ins, however, it is expected to be increased in the nearest future. Owing to a bigger number of plug-ins, Capacitor will become a flexible and comprehensive solution that will reduce the need of using Cordova additionally as a provider of a specific platform.

Developer’s highlights

#firstly, you have to create a new application

$ Ionic start new-app

#in my case, I’m not integrating the application with Cordova and I choose NO option

$ Would you like to integrate your new app with Cordova to target native iOS and Android?

$ cd my-app

#npm installs packages for Capacitor in a project

$ npm install — save @capacitor/core @capacitor/cli

#initialization for capacitor configuration

$ npx cap init

#building ionic application and creating a new www catalogue

$ npm run build

Or

$ ionic build

#starting the application in the PWA context in a browser

$ npx cap serve

#adding a new IOS platform to the application

$ npx cap add ios

#copying all the necessary files to a given platform, which has been defined in the project

$ npx cap copy

#starting Xcode

$ npx cap open ios

Written by Adrian Nowakowski — Team Leader Senior Software Developer at Objectivity.

Our company values are the backbone of how we work. Our goal for the next 25 years is not straying from this path. https://www.objectivity.co.uk/