From Web Application to Mobile App: An Introduction to Cross-Plaftform Development using Ionic Capacitor

Table of Content

Objective
Development Environment
Traditional Web App to Mobile App
Progressive Web App (PWA) to Android App
Progressive Web App to Standalone Windows Applications
Reference

Objective

This brief tutorial is to offer hands-on experience for cross-platform mobile development.

Develop a traditional Web application and convert it to a native Android app.
Develop a Progress Web application and convert to a native Android app.

For these two tasks, we will use Capacitor, a cross-platform tool and runtime whose design objective are to enable Web application developers to build native mobile apps, namely, Android and iOS apps and Progressive Web Apps (PWAs). Using the Ionic Framework along with a few other tools including Capacitor, the developers will only need to maintain a single code base for 5 different platforms such as

Desktop OSes: Windows, iOS
Mobile OSes: Android, iOS, and
the Web

This does not come without a cost, e.g., since the starting point is a Web application, you will likely suffer from performance penalty, especially on graphic rendering and may have limited access to the feature offered by the native APIs.

Development Environment

The tasks can be completed on either a Windows, OS X, and Linux system.

Install NodeJS.

First check if you’ve already had NodeJS installed. Open a terminal/console window, and run:
```
node -v
```
If you encounter an error that indicates the command is not found. You will need to download and install NodeJS. Follow the instruction here:

[https://nodejs.org/en/download]

Upon installing it, you should always verify whether the installation is successful:
```
node -v

npm -v
```

Traditional Web App to Mobile App

Create a Web application. For instance, here is a simple calculator application

Simple Web Calculator

The source code of the application is in a zip file that you can download from

Simple Web Calculator Source Code

In the discussion that follows, we assume the source is extracted to the www directory.
Ensure the Web application can run. For this, install a simple HTTP Sever,
```
npm install live-server -g
```
and start the server inside the www directory:
```
npx live-server
```
Convert it to a native mobile app, e.g., to an Android app. First, create a directory parallel to www. Let’s call this directory androidapp. In the parent directory of www or androidapp. If you list the content of the directory, you should see two directories:
```
androidapp
www
```

In the androidapp directory, install the Capacitor Core package and a few Capacitor packages:

npm install @capacitor/core
npm install @capacitor/cli
npm install @capacitor/android

In the androidapp directory, set up a project for the Android app:
```
npx cap init
npx cap add android
```
Open Android Studio, and build and run the app.
```
npx cap open android
```

Progressive Web App (PWA) to Android App

Traditional Web applications do not consider the unique challenges mobile apps face, such as intermittent network connections. Progressive Web Apps (PWAs) are designed to have advanced capabilities, such as

can continue working when the device is offline,
can have push notifications,
can perform periodic updates even when the application is not running, and
can access hardware features.

However, PWAs are applications that are still built using web technologies. The benefits include that can be installed and can run on multiple platforms from one codebase.

To achieve these objectives, PWAs must come with

application manifest, a JSON file that describes the application to the host operating system so that the application can be set up automatically on the host operating systems
service worker, a specialized program that can intercept network requests from the PWA, and enables scenarios, such as:
- offline support, including intermittent connections,
- advanced caching for network efficiency, and
- running background tasks such as receiving PUSH messages, adding badges to the app icon, or fetching data from a server.

In the following, we redesign the web calculator to be a PAW.

Extract the web calculator’s source code to a directory. Let’s call it pwa. In the pwa directory, you should find the index.html and the assets directory.

Create a manifest file for the PWA under the pwa directory.

Create a file in the pwa directory and call it manifest.json.

{
   "lang": "en-us",
   "name": "Web Calculator",
   "short_name": "Web Calculator",
   "description": "A simple web calculator that does basic arithmetic calculations",
   "start_url": "/",
   "orientation": "any",
   "display": "standalone",
   "icons": [
      {
            "src": "/images/icons8-calculator-512.png",
            "sizes": "512x512"
      },
      {
            "src": "/images/icons8-calculator-64.png",
            "sizes": "64x64"
      }
   ]
}

The manifest references to two app icons. These can be downloaded from icons8. There are a number of other websites that provides free or sell app icons.
- Create the images directory under pwa,
- Download two icons of size 512x512 and 64x64, and extract the icons to the images directory,
- Ensure the filenames match the manifest file.
Link the manifest in the PWA’s landing/starting page, i.e., index.html. To achieve, add the following line anywhere inside the <head> tag of the html file.
```
<link rel="manifest" href="/manifest.json">
```

Add a server worker to the PWA. Server workers are written in JavaScript, and loaded by the PWA.

For this simple PWA. Create a file called service_worker.jsin the pwa directory. The content of the file is as follows:

const CACHE_NAME = `web-calculator-v1`;

/* Pre-cache all initial resources when the app is installed.
   This is triggered by the 'install' event. This will
   speed up the loading process of the PWA. See the 2nd
   part of the logic for this. The app's icons can also be 
   pre-fetched.  */
self.addEventListener('install', event => {
event.waitUntil((async () => {
   const cache = await caches.open(CACHE_NAME);
   cache.addAll([
      '/',
      '/assets/calculator.js',
      '/assets/calculator.css'
   ]);
})());
});

/* When the PWA requests to fetch an object,
   it will first attempt to load it from the
   cache (see step 1 below). If it isn't
   in the cache (e.g., the app's icon), it
   will be fecthed over the network, and then
   the fetched object stored in the cache. 
   See steps 2 and 3.
   Next time, a fetch of the same object will
   be loaded from the cache, which speed up 
   the PWA.
*/

self.addEventListener('fetch', event => {
event.respondWith((async () => {
   const cache = await caches.open(CACHE_NAME);

   /* 1. attempt to load fetched object from the cache */
   const cachedResponse = await cache.match(event.request);
   if (cachedResponse) {
      return cachedResponse;
   } else {
      /* 2. if not found in cache, download it over the network */
      try {
         const fetchResponse = await fetch(event.request);

         /* 3. saved the downloaded object to cache */
         cache.put(event.request, fetchResponse.clone());
         return fetchResponse;
      } catch (e) {
         // Opps. handling the network failed, code not written
      }
   }
})());
});

Link the service work JavaScript file in the PWA’s landing/starting page, i.e., index.html. To achieve, add the following lines at the end of the <body> tag (inside the <body> tag, before </body>) to register your service worker:
```
<script>
if('serviceWorker' in navigator) {
   navigator.serviceWorker.register('/service_worker.js', { scope: '/' });
}
</script>
```
It is always a good practice to verify that the service worker is linked correctly.
1. Open the Web Developer Tool.
2. First, ensure that there is error shown on the Console of the Web Developer Tool. For this example, if there is any error, you’ve made a typographical error, fix it.
3. Click the Application tab, the server worker should be shown running
4. Locate the cache storage from the user interface, and expand the storage, and you should see three objects referenced there.
5. If not, for this app, you’ve made a typographical error. Fix the error.
6. Unregister the service worker, and refresh the app’s landing page.

Great. Let’s now convert this PWA to a native Android app.
1. Like before, let’s create a directory parallel to pwa, call it androidpwa`.
2. In the androidpwa directory, run:
```
npm install @capacitor/core
npm install @capacitor/cli
npm install @capacitor/android
```
3. Initialize an Android project:
```
npx cap init
npx cap add android
```
4. Open the native Android app project in Android Studio
```
npx cap open android
```
5. Run the native app, e.g., in an Android emulator.

Progressive Web App to Standalone Windows Applications

You can convert a PWA to a standalone Windows applications. You may try either one of the two tools and runtimes:

Electron https://www.electronjs.org/
NW.js https://nwjs.io/

Let’s save this for another day/semester. However, you try them yourselves.