Developing cross platform apps with Ionic Capacitor - part 1

March 26, 2018, 6:50 am Categories:


If you've been visiting the Ionic website in recent weeks you'll no doubt have heard of Capacitor - the team's latest innovation for developing web applications that run natively across iOS, Android, Electron and the Web.

Seen as a step in the next evolution beyond hybrid apps Capacitor provides developers with:

  • Access to native device features on supporting platforms using API's that adhere as closely to Web Standards as possible
  • Development support for desktop, web and mobile platform delivery
  • Integration with Xcode and Android Studio
  • Plugin API for developing iOS/Android and Web plugins
  • Backward compatibility (as far as is possible) with many existing Apache Cordova plugins

Seen as a spiritual successor to Apache Cordova and Adobe PhoneGap Capacitor allows developers to create applications that can be deployed for use in desktop, mobile or mobile environments.

The team at Ionic have described apps built with Capacitor as Native Progressive Web Applications although terms such as cross platform mobile apps and Universal Web Applications are also being bandied around.

Buzzwords and tech jargon aside (and isn't this industry so in love with every latest, much-hyped "unicorn"?) the software and its development potential sounds pretty exciting doesn't it?

It definitely is....but, as usual where software and their features are concerned, there are certain caveats that you need to be aware of.

System requirements

Firstly you'll need to ensure the following software dependencies are in place for any Capacitor development:

  • Node v8.6+
  • NPM v5.6+
  • iOS development - Requires a Mac with Xcode 9, CocoaPods and Xcode Command Lines Tools installed
  • Android development - Java8 JDK installed (as of March 2018 Java 9 does NOT work) along with Android SDK & Android Studio

iOS development caveats

Currently (as of March 2018) you WILL need a Mac to use Capacitor to develop iOS applications BUT Ionic Pro support is planned for the near future which will open up iOS development opportunities for Windows/Linux users too.

As a rule of thumb the latest version of Capacitor always provides support for the last 2 versions of iOS - currently iOS 10 and 11.

IMPORTANT - when developing for iOS you WILL need to update CocoaPods PRIOR to starting a new project with the following command:

pod repo update

Android development caveats

Currently Capacitor support for Android devices is targeted at API level 21+ (Android 5.0 - Lollipop).

Additionally with Chrome version 50 and above Capacitor requires an Android WebView.

Desktop development

Currently Electron support isn't ready so those developers looking to implement Capacitor functionality in their Electron based desktop applications are going to have to wait for the go ahead from Ionic on that front.

As a result we won't be covering desktop development in this tutorial.

Capacitor basics

Capacitor can be added to an existing project in one of two ways:

  • Added to an existing front-end project (this is the recommended approach)
  • Creating a fresh project from scratch

Although Capacitor provides a native mobile runtime and API layer for web apps it does NOT come with any UI components/controls. This is why the team at Ionic recommend developers add Capacitor to an existing front-end project using a mobile framework of their choice.

Unsurprisingly we'll be making use of Ionic over the course of this tutorial (as if you couldn't have guessed!)

Capacitor currently, as of the alpha release, provides the following Native API's (or core plugins) which cover much of the functionality normally provided by Cordova plugins:

  • Accessibility
  • App
  • Background Task
  • Camera
  • Clipboard
  • Console
  • Device
  • Filesystem
  • Geolocation
  • Haptics
  • Keyboard
  • Modals
  • Motion
  • Network
  • Share
  • Splash Screen
  • Status Bar
  • Storage

It's important to also note that despite Capacitor being seen as a spiritual successor to Apache Cordova and Adobe PhoneGap developers can still install and use Ionic Native/Cordova plugins in Capacitor projects if they so wish.

We'll see how such plugins are installed with capacitor in the following section (as this differs from the usual Ionic/Cordova installation process).

Creating a Capacitor project

Capacitor is installed for a project with the following command (this assumes you are within the root directory of that project AND that you have installed ALL the required dependencies listed in the System requirements section above):

npm install --save @capacitor/core @capacitor/cli

Once installed you will then initialise the project with Capacitor using the following command:

npx cap init

This will prompt you for the following information:

  • App Name
  • App Package ID (must be a valid Java package)

The App Package ID value is simply a reverse domain name identifier for the application such as com.saintsatplay.locator for example. Simply follow this pattern substituting your organisation/own name and app name where appropriate.

Notice the npx utility in the above command? This isn't a spelling mistake on my part where npm should have been used as the npx utility was introduced with npm 5.2.0 and is responsible for:

  • Avoids global installs allowing binaries to be executed locally on a project-by-project basis
  • Executing one-off commands
  • Developing npm run-scripts interactively

The npx utility will feature quite heavily with Capacitor development as we'll soon see with the available commands for installing platforms, generating project builds etc.

Once the Capacitor project has been initialised a capacitor.config.json file is created in the root of your project directory with the following minimal configuration values:

  "appId": "com.saintsatplay.location",
  "appName": "Ionic Location",
  "bundledWebRuntime": false,
  "webDir": "www"

Notice the webDir entry? This declares the directory where your project's stylesheets, scripts, images (and possibly additional assets you include for use in your project) are published to.

Upon project creation this directory will need to be generated with the following command:

ionic build

Bear in mind that all subsequent changes to project files will necessitate this build command being run again to ensure said changes are published to the www directory.

Psst....the npm run build command can also be used but because Ionic offers use of the ionic build command we use that instead. To be honest I've used both commands in my projects and have seen no difference in performance/outcome either way.

Additional development platforms are able to be added to the project with the following commands (the www directory MUST exist before running any of these though):

npx cap add android
npx cap add ios
npx cap add electron

Every time changes are made to the project assets these will need to be published to the www directory (as explained above) and then copied to all installed platforms as follows:

ionic build
npx cap copy

To install Ionic Native plugins and their wrappers we would run the following commands:

npm install name-of-ionic-native-plugin
npx cap update

It's worth mentioning at this point that we will need to uninstall the Cordova Splashscreen Plugin that is installed by default with every CLI generated Ionic project as this conflicts with Capacitor (which provides its own Splashscreen plugin).

To do this we simply run the following:

npm uninstall --save cordova-plugin-splashscreen

Once project assets have been published to the www directory AND copied to each installed platform, we can run the following commands to open each platform's respective IDE (Xcode for iOS and Android Studio for Android):

npx cap open ios
npx cap open android

Finally, it's important to note that updating dependencies and installing new plugins for a Capacitor app can be managed with the following command:

npx cap update

It's a good idea to perform such 'maintenance' on a regular basis (but be sure to test that no breaking changes have been introduced into your application afterwards!)

The Capacitor workflow

To quickly condense the different commands and processes from the previous section then our Capacitor workflow - when developing with Ionic - would look something like the following:

// 1. Create your Ionic project
ionic start your-project-name your-choice-of-project-template

// 2. Do NOT integrate Cordova when prompted by the Ionic CLI - Answer NO
Would you like to integrate your new app with Cordova to target native iOS and Android? 

// 3. Change into root directory of newly created project
cd your-project-name

// 4. Install Capacitor for project
npm install --save @capacitor/core @capacitor/cli

// 5. Initialise Capacitor
npx cap init

// 6. Uninstall Cordova Splashscreen plugin
npm uninstall --save cordova-plugin-splashscreen

// 7. Build www directory on project creation/PRIOR to copying assets to platforms 
ionic build

// OR you can use
npm run build

// 8. Add necessary platforms
npx cap add ios
npx cap add android
npx cap open electron

// 9. Copy build assets to ALL platforms EVERY time there are changes to be included 
npx cap copy

// 10. Open project in Xcode
npx cap open ios

// 11. Open project in Android Studio
npx cap open android

// 12. Perform project maintenance at regular intervals (I.e. fortnightly, monthly etc)
npx cap update

Let's make use of this workflow over the course of the application that we'll be developing throughout this tutorial series.

The Ionic Camera application

As we're interested in learning about Capacitor and seeing how the software can be used in an Ionic project the application that we'll be developing is very simple - consisting of the following features:

  • Use of the Capacitor Camera and SplashScreen APIs
  • Allows the user to select an image (via device camera/photolibrary on mobile or through HTML5 Filereader API for web) and render that to the screen
  • Able to be deployed across iOS, Android and Web platforms

This project - imaginatively named snappa - will, when published to iOS, look like the following:

Ionic Camera application showing splash screen and initial state with camera application requested by user

Ionic Camera application image selection by user and display of image on screen

Let's begin creating the initial foundations for this project.

Laying the foundations

Open your system command line utility, navigate to where you would normally create/store your digital projects and issue the following command to create a new project named ionic-camera:

ionic start ionic-camera blank

When prompted with the following question answer with No.

Would you like to integrate your new app with Cordova to target native iOS and Android? (y/N)

Change into the root of the newly created ionic-camera project directory and generate the following service (which we'll use to handle all image selection/parsing for the application):

ionic g provider image 

Once the service has been generated run the following commands to set up Capacitor, prepare the project environment, install the necessary platforms and copy build assets to these installed native platforms:

npm install --save @capacitor/core @capacitor/cli
npx cap init
npm uninstall --save cordova-plugin-splashscreen
ionic build
npx cap add ios
npx cap add android
npx cap copy

At this point we have everything we need in place to start the actual coding for the application - but we'll proceed with that in the second part of this tutorial.

In summary

Capacitor, although still in alpha release (as of March 2018 - that status may have changed by the time you read this tutorial though), brings some exciting opportunities for developing cross platform mobile applications. It's fast, offers an intuitive command line syntax, provides build generation functionality and allows iOS/Android and Web application development from a single codebase.

As a spiritual successor to both Apache Cordova and Adobe PhoneGap Capacitor the initial Core Plugin offerings are reasonable but the absence, for example, of a Google Maps or In-App Purchase plugin make this a little limited for immediately replacing the use of Ionic Native plugins.

That said I'm sure that over the next 6 - 12 months this situation will change fairly quickly though.

In the second part of this instalment of tutorials on working with Capacitor we'll see how to develop the ionic-camera application and make use of the Capacitor SplashScreen and Camera APIs.

If you've enjoyed what you've read and/or found this helpful please feel free to share your comments, thoughts and suggestions in the comments area below.

I explore different aspects of working with the Ionic framework in my e-book featured below and if you're interested in learning more about further articles and e-books that I'm writing please sign up to my FREE mailing list.



Post a comment

All comments are welcome and the rules are simple - be nice and do NOT engage in trolling, spamming, abusiveness or illegal behaviour. If you fail to observe these rules you will be permanently banned from being able to comment.