Whitepaper

Building
cross-platform
apps with
Capacitor
Whitepaper

contents

Introduction pages 1-2

The emergence of cross-platform development page 3

Building cross-platform apps with the web pages 4-5

Capacitor: A new approach to cross-platform

pages 6-8
development

Progressive Web App (PWA) support

CLI tooling that is version managed per app
Native and web developer collaboration
Capacitor takes a “web first” approach
Easily access native device features

When to Use Capacitor pages 9-10

Building a native mobile app on iOS and Android

Building a Progressive Web App
Adding a web-based experience to an existing
native mobile app
Deploying a legacy web app to mobile

What about the User Interface (UI) layer?

page 11
Bring your own library or framework
Use a mobile-ready UI framework like Ionic

Using Capacitor in an enterprise environment page 12

Migrating to Capacitor from Cordova page 13

Adopting Capacitor pages 14- 15

For more Ionic white papers, visit: ionic.io/resources

 Whitepaper

introduction

Capacitor was first released in 2019 as

a new and revolutionary way to deliver
native mobile apps and Progressive Web
Apps (PWAs) from the same codebase,
using web technology in place of native
programming languages.

The Ionic team created Capacitor as a Cordova was capable of. That’s due in no
spiritual successor to Apache Cordova and small part to the fact that many of the new,
Adobe PhoneGap, with inspiration from modern APIs were not available previously.
other popular cross-platform tools like
Eventually, we reached a fork in the road,
React Native and Turbolinks, but focused
and decided it would be better to forge our
entirely on enabling modern web apps to
own path, rather than iterate on top of what
run on all major platforms with ease.
Cordova had already built. It was a tough
decision; but looking back, I have no doubt
that it was the right one.

While Capacitor shares many similarities

At Ionic, we have a long history with
with Cordova and other native runtimes -
these solutions. For years, Cordova ran
and owes a tremendous debt to what
underneath the hood of every app shipped
they pioneered - we’ve made some very
on our platform. While Ionic focused
different decisions at several key points,
primarily on the UI or frontend mobile
such that the experience of the projects
experience, we left the native layer to
are very different.
Cordova. But over time, our aspirations and
visions for a native runtime outpaced what

1 For more Ionic white papers, visit: ionic.io/resources

 Whitepaper

Figure 1 - Project flow with Capacitor

For example, Capacitor embraces npm to manage plugins, Swift for iOS, Java for Android,
TypeScript, and has full support for Progressive Web Apps. Capacitor makes it possible
to build one app for iOS, Android, and the Web, all with one code base. Capacitor has
first-class support for building plugins; in fact the plugin authoring experience has been
a focus from the very beginning. Capacitor treats native projects as source-artifacts,
meaning native code can quickly be added without worrying about changes being lost.
Capacitor does away with device-ready or async plugin loading, a common source of
confusion and bugs with Cordova developers, so all plugins are available as soon as the
page starts loading. And that’s just the tip of the iceberg.

Today, Capacitor is the most cost effective path to deploying a single app to multiple
platforms.

Don’t just ask us! Since its launch, Capacitor has grown to more than 500K monthly
installs and is poised to eclipse Cordova as the #1 native runtime for hybrid apps. In other
words, developers really like Capacitor. We’re thrilled to report some notable companies
using Capacitor include Tim Horton’s, Popeye’s, and Sworkit, to name a few.

Building on the initial success of Capacitor, Ionic released Capacitor 2.0 in April 2020,
then followed up with version 3.0 in May 2021.

With the release of Capacitor 3.0, we planted a stake in the ground: Capacitor is now the
standard for web developers building mobile apps. We’re firmly committed to making
mobile development just as good as web development, and that’s exactly what Capacitor
enables. Whether you have an existing web project or are curious about starting a new
mobile project, we hope you’ll check out Capacitor.

— Max Lynch, Co-Founder and CEO of Ionic

2 For more Ionic white papers, visit: ionic.io/resources

 Whitepaper

The emergence
of cross-platform
development
Today, about 60% of all apps in the app store are cross-platform. This means apps that
run on iOS and Android from a shared codebase, using cross-platform solutions like React
Native, Ionic, and Cordova. And increasingly, Capacitor.

Given the thousands of apps released in the app stores each year, and the prodigious
appetite for mobile inside many businesses, cross-platform development approaches
have emerged as a way to meet the demand for mobile applications, by speeding up and
simplifying how development gets done. They do this in a few ways.

First, instead of writing separate code for each platform, cross-platform solutions allow
you to share code across platforms. You write your code once and it works seamlessly
across iOS and Android. That benefit alone can lead to time savings of 50% or more.

Secondly, by abstracting much of the native complexity, these solutions have made it so
that just about anyone with a basic knowledge of JavaScript, HTML, and CSS can now
build a high-quality mobile app.

For background, check out our ebook:

Hybrid vs. Native: A Comparison Guide.

3 For more Ionic white papers, visit: ionicframework.com/resources

 Whitepaper

Building cross-
platform apps
with the web
Within the cross-platform category, there are two main
categories of solutions.

So-called “cross-platform native” solutions like React Native and Xamarin are tightly
coupled with the native mobile platforms. Written and controlled largely in JavaScript or
C#, they boast solid performance and allow developers to build mobile experiences with
native UI controls.

In contrast, Cordova and Capacitor are primarily web-based in nature — often referred to
as “hybrid” solutions, in reference to the fact that they combine native runtime features
with a web UI layer. Although hybrid apps run natively on the device and interact with any
available native APIs, the UI layer of the app is executed primarily in a web browser, known
as a WebView, that is invisible to the user.

Xamarin/React Native Capacitor/Cordova

Native APIs Device OS Native APIs Device OS

4 For more Ionic white papers, visit: ionic.io/resources

 Whitepaper

What are the advantages of a hybrid

approach?
On top of all the general cross-platform benefits that we noted in the section above,
hybrid offers a few key advantages over the “cross-platform native” solutions:

• If you’re already familiar with the traditional web languages and approaches, you’ll be
right at home. There are no additional languages to learn.
• If you have an existing web project that you want to bring to mobile, you can do that
using a native runtime like Cordova or Capacitor.
• If you have a web UI library that you’d like to use in mobile - whether it’s a corporate
design system or a packaged UI library like Bootstrap - you can bring those UI
components to mobile using a hybrid approach.
• If you’re building an app that you’d like to deploy across mobile and web, including
PWAs, then a hybrid approach makes sense.

On top of that, because the UI of a hybrid application runs entirely in the browser, it’s
possible to target iOS, Android, desktop and the web, all from a single shared codebase.
That’s in contrast to cross-platform native solutions that often require separate native
code on each platform, along with a third “control” layer for any shared code across
platforms.

Of course, some will debate whether running the UI in a browser adds a big performance
hit, but the truth is that advances in native devices, browser technologies, and runtimes
like Capacitor have rendered these issues largely obsolete. For proof, just download one
of the many successful hybrid apps on the market, including Shipt, Sworkit, Sanvello — all
highly rated consumer apps serving millions of users.

5 For more Ionic white papers, visit: ionic.io/resources

 Whitepaper

Capacitor: A new
approach to cross-
platform development
Capacitor is an open source project that runs modern Web Apps
natively on iOS, Android, Electron, and Web, while providing a
powerful and easy-to-use interface for accessing Native SDKs
and Native APIs on each platform.

Capacitor delivers the same benefits of the native runtimes that

preceded it, including React Native and Cordova, but with a
modern, web-first approach.

What makes Capacitor unique?

6 For more Ionic white papers, visit: ionic.io/resources

 Whitepaper

Progressive Web App (PWA) support

Capacitor is the only native runtime to deliver first-class support for web apps and PWAs.
In fact, we’ve taken it a step further by building out a collection of UI experiences, like
Camera, that bring the native app UI experience users expect to PWAs.

Also, building plugins that offer web functionality as a fallback simply requires adding
a few files to your plugin. Capacitor will only use your web implementation if the native
one is not available, so users can use the exact same API when running on iOS, Android,
Electron, and the web. Here is the Capacitor Camera API, for example. Notice there is no
platform-specific code:

import { Camera, CameraResultType } from ‘@capacitor/camera’;

const photo = await Camera.getPhoto({

quality: 100,
resultType: CameraResultType.Uri,
allowEditing: true,
saveToGallery: true
});

Figure 2 - One API, one codebase

7 For more Ionic white papers, visit: ionic.io/resources

 Whitepaper

CLI tooling that is version managed per app Capacitor takes a “web first” approach
Capacitor provides a small CLI tool that is We believe that the core of every great cross-
installed locally to each app. That means there platform hybrid app is a quality, modern
are no global dependencies to manage and it’s Progressive Web App (PWA). This keeps your app
easy to use different versions of Capacitor across aligned with the rapidly evolving web platform
every app you build. This is a boon to teams while enabling powerful native device functionality
that are building multiple apps with potentially on platforms that support it. Capacitor has
differing dependency versions or version even convinced native developers or users of
management processes. alternative platforms that see the benefits of web
development on mobile, and customer feedback
Native and web developer collaboration indicates that Capacitor is finally providing the
Since Capacitor apps are actual native apps development experience they prefer.
and a key design consideration of Capacitor is
embracing native tooling, Capacitor enables Easily access native device features
teams that have both traditional native mobile Developers have access to the full Native SDK
and web developers to collaborate on mobile app on each platform, and can easily deploy to App
projects. Traditional native mobile developers Stores, and the web. Adding native functionality is
can use their programming languages of choice easy with a simple Plugin API for Swift on iOS, Java
(Swift/Objective-C on iOS, Java/Kotlin on on Android, and JavaScript for the web.
Android) to build UI experiences or business
Capacitor apps access native and web features
logic and then expose them to the Web layer
using a series of platform APIs (AKA plugins). While
through Capacitor’s JavaScript-to-native APIs.
the base Capacitor experience includes a series of
This also ensures an app team never gets stuck
core plugins, along with OSS contributed plugins,
implementing the functionality it needs.
you can easily add your own custom device
Cordova, in contrast, works through an functionality by writing a plugin of your own.
abstraction layer that manages the underlying
Using Capacitor, developers can build one app
native platform project and source files for
and target a single set of APIs regardless of the
you, making it harder to drop down to native
platform the app is running on, as opposed to
code or work with a traditional native mobile
managing multiple APIs for each target platform.
development process, and can result in custom
As illustrated in the example above, accessing the
changes being lost.
Camera uses the same code on iOS/Android as it
does on Electron and on the web.

8 For more Ionic white papers, visit: ionic.io/resources

 Whitepaper

When to Use Capacitor

Capacitor is a versatile solution that addresses several key use-cases related
to mobile and web application development.

Building a native mobile app on iOS and Building a Progressive Web App
Android Capacitor has first-class support for Progressive
Capacitor makes it easy to build and deploy Web Apps (PWAs) and native apps. That means
native mobile apps for iOS and Android, using that Capacitor’s plugin bridge supports running
familiar web languages, libraries, and frameworks, in either a native context or on the web, with
without the underlying complexity of the native many core plugins available in both contexts with
SDKs and iOS and Android specific code. Mobile the exact same API and calling conventions. This
applications built with Capacitor are optimized means you’ll use @capacitor/core as a dependency
for native performance and have full access to for both your native app and your Progressive Web
any native device features, including full access App, and Capacitor will seamlessly call web code
to the native SDKs when needed. The UI layer when required and native code when available.
of any Capacitor mobile app primarily runs in
Capacitor also offers a number of utilities
the browser, so that any new or existing web
for querying the current platform to provide
applications can be deployed as a native mobile
customized experiences when running natively or
application.
on the web.

9 For more Ionic white papers, visit: ionic.io/resources

 Whitepaper

Adding a web-based experience to an existing

native mobile app
Capacitor adds superpowers to the traditional
WebView control available on each platform, and
it was designed to be used anywhere a WebView
would be used. That means it can easily be
dropped into an existing native app codebase,
Deploying a legacy web app to mobile
making it possible to build certain screens of the
Traditionally, teams looking to extend their existing
app using web technology, without the need to
web apps to other platforms were faced with a
make any sweeping changes to the rest of the
conundrum: either rewrite the app using native
app codebase.
technologies or risk excluding new customers (the
This is also a great way to let other teams that majority of which are obtained through mobile
may have more of a traditional web development experiences these days!). Both decisions involve
skill set participate in the development of the app dropping years of time, money, and effort invested
without getting in the way of a traditional native or risking future company growth.
development process.
With Capacitor, there’s no need to start from
scratch. In fact, it was designed to drop into any
existing modern JavaScript web app - including
ones using UI frameworks like Bootstrap, Material
UI, or Framework7. Simply install Capacitor, add
the desired native platforms, then start using
any of Capacitor’s 23+ cross-platform APIs. Yes,
you’ll need to address several mobile-specific UI
paradigms - more on that below.

To see how to use Capacitor with your web app

framework of choice, check out the examples in
this code repository.

10 For more Ionic white papers, visit: ionic.io/resources

 Whitepaper

What about the User

Interface (UI) layer?
While Capacitor gives you the native runtime environment to run
your app on mobile, you still need to think about the UI layer of
your app. Here are a couple options to consider.

Bring your own library or framework

It’s important to note that the UI of a Capacitor app runs primarily in the browser. This
small but important distinction opens up a whole world of possibilities for web developers
and teams who want to bring their web UI components and applications to mobile.

It also means any popular UI framework like Bootstrap, Material, or Tailwind will work great
in Capacitor. While you’ll need to anticipate and address the many mobile-specific UI
paradigms (see below), your existing web-based library will now run natively on any iOS or
Android device, and on the web as a PWA.

Use a mobile-ready UI framework like Ionic

While Capacitor addresses the feasibility of bringing your web apps to mobile, there are
other hurdles to consider. Mobile styling, navigation, and performance on mobile devices
are all very tricky and can be daunting for the uninitiated.

As an alternative to rolling your own solution from scratch, you can use a mobile-ready
UI library like Ionic Framework instead. You can then incrementally add your own custom
components as needed. Or, start with your UI library as the foundation, and incrementally
add Framework components as you need them. There are a variety of options, and it’s not
an all-or-nothing proposition.

11 For more Ionic white papers, visit: ionicframework.com/resources

 Whitepaper

Using Capacitor
in an enterprise
environment
Capacitor is truly unique as an open source project in that it has a real company behind
it. That company, Ionic, is in the business of enterprise app development. That means our
sole focus is to provide teams building mission-critical apps the support and enterprise-
specific functionality they need to be successful. Ionic, the team behind Capacitor,
works with hundreds of enterprise customers, building everything from major consumer
transportation apps, fast-food retail apps, internal B2E apps, and a whole lot more.

Ionic offers dedicated support across Capacitor and its native APIs, as well as advanced
enterprise native features like secure token management, encrypted offline storage, and
OpenID Connect-powered single sign-on. Additionally, teams can build best-of-breed user
experiences on top of Capacitor using the highly popular Ionic Framework.

Capacitor is a key aspect of Ionic’s mobile infrastructure and the infrastructure of its
customers. That means security and functionality issues are discovered, fixed, and
released quickly. Capacitor has a full-time team of engineers, product management,
marketing, and customer success experts dedicated to customer and project success.

12 For more Ionic white papers, visit: ionic.io/resources

 Whitepaper

Migrating to Capacitor
from Cordova
If your team is currently using Cordova and curious about moving
to Capacitor, then you will welcome the fact that Capacitor
has backward-compatible support for a large swath of existing
Cordova plugins. Migrating to Capacitor from Cordova is well-
documented and uncomplicated.

If you’re interested in learning more about our

enterprise options, reach out to one of our team
members to schedule a free Strategy Session.

13 For more Ionic white papers, visit: ionicframework.com/resources

 Whitepaper

Adopting Capacitor
Capacitor is a key aspect of Ionic’s mobile infrastructure and the
infrastructure of its customers. To date, Capacitor is installed
over 6 million times a year, and is currently powering major
production enterprise apps with hundreds of millions of users.
Suffice to say, Capacitor is now a major force in the mobile
development ecosystem and is a major element of Ionic’s
enterprise business. Even native developers (or alternative
platforms) are recognizing the benefits of web development
on mobile, and are satisfied with the development experience
Capacitor provides.

“Capacitor’s support for the latest in security, performance, and

native platform capabilities, makes it easy to build compelling,
modern app experiences that our users want, without having to
worry about all the underlying complexity of the native SDKs and
iOS and Android specific code.”

— Rakesh Gadapa, Application Developer III at Blue Cross Blue Shield of Michigan.

14 For more Ionic white papers, visit: ionic.io/resources

 Whitepaper

Interested in learning more about

Capacitor, enterprise support
and advanced integrations, or the
Ionic platform in general? Get in
touch, we’d love to see how we
can help your organization build
market-leading apps in a fraction of
time compared to traditional app
development.

Book a strategy
session with a
Solutions Engineer
today.
15 For more Ionic white papers, visit: ionicframework.com/resources