I was working on a project a while back where the users had to use the app in three different places. They needed to use it on desktop computers at the office on Android tablets when they were out in the field and on iPhones when they were moving around. This was a problem because we had one team and we did not want to deal with three sets of code.

This project made me think about how to make the app work on all these devices. In this tutorial I will talk about two ways to do this: Progressive Web Apps and Capacitor. Progressive Web Apps are good because they work on a lot of devices and are not too hard to make. Capacitor is good when you need to use the devices features. I will explain when to use each one and how I have used them on projects. I will share what I have learned from my experience, with the Mobile App project.

Prerequisites

• Basic knowledge of JavaScript and HTML/CSS
• Node.js installed
• A React or vanilla JS app (examples use React but the concepts apply to any framework)

Two Approaches: PWA vs. Capacitor

Before writing code, it helps to know which direction you're heading.

Progressive Web App (PWA) runs in any browser and can be installed on Android and desktop with full support. iOS support exists but is limited — no push notifications, restricted background sync, and Apple has been slow to adopt PWA features. If your users are mainly on Android or desktop, PWA alone might be enough. If iOS is important, you'll likely want Capacitor eventually.

Capacitor wraps your web app in a native shell and gives you full access to device APIs — camera, biometrics, push notifications, file system. It requires App Store and Google Play submission, which adds time and process. But for apps where native features matter, it's the right call.

The approach I've settled on: ship as a PWA first, add Capacitor later when there's a specific reason. You get something in users' hands faster, and by the time you add the native wrapper you know exactly which native features you actually need.

Part 1: Building a PWA

Step 1: Add a Web App Manifest

The manifest tells browsers how to display your app when installed.

Create public/manifest.json:

{
  "name": "My App",
  "short_name": "MyApp",
  "description": "A cross-platform web application",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#0066cc",
  "orientation": "portrait-primary",
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any maskable"
    },
    {
      "src": "/icons/icon-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any maskable"
    }
  ]
}

Link it in your index.html:

<link rel="manifest" href="/manifest.json" />
<meta name="theme-color" content="#0066cc" />
<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-status-bar-style" content="default" />
<link rel="apple-touch-icon" href="/icons/icon-192.png" />

The Apple-specific meta tags are needed because iOS handles PWAs differently from the manifest spec. Without them the app won't install correctly on iPhone.

Step 2: Register a Service Worker

The service worker handles offline support and caching.

Create public/service-worker.js:

const CACHE_NAME = 'myapp-v1';
const ASSETS_TO_CACHE = [
  '/',
  '/index.html',
  '/manifest.json',
  '/icons/icon-192.png',
  '/icons/icon-512.png',
];

self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => cache.addAll(ASSETS_TO_CACHE))
  );
  self.skipWaiting();
});

self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then((keys) =>
      Promise.all(keys.filter((k) => k !== CACHE_NAME).map((k) => caches.delete(k)))
    )
  );
  self.clients.claim();
});

self.addEventListener('fetch', (event) => {
  if (event.request.method !== 'GET') return;

  event.respondWith(
    caches.match(event.request).then((cached) => {
      if (cached) return cached;
      return fetch(event.request).then((response) => {
        if (response && response.status === 200) {
          const clone = response.clone();
          caches.open(CACHE_NAME).then((cache) => cache.put(event.request, clone));
        }
        return response;
      });
    })
  );
});

Register it in your app's entry point:

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker
      .register('/service-worker.js')
      .then((reg) => console.log('SW registered:', reg.scope))
      .catch((err) => console.error('SW registration failed:', err));
  });
}

Step 3: Test Your PWA

Open Chrome DevTools → Application tab → Manifest to verify your manifest is loading. Check Application → Service Workers to confirm the service worker is active.

Run the Lighthouse audit (DevTools → Lighthouse → Progressive Web App) and aim for a score above 90. On Android, Chrome will prompt users to install once your score is high enough. On iOS, users install via Share → Add to Home Screen.

Part 2: Adding Native iOS and Android with Capacitor

Step 1: Install Capacitor

npm install @capacitor/core @capacitor/cli
npx cap init

When prompted:

• App name: My App
• App ID: com.mycompany.myapp (reverse domain format)
• Web directory: build or dist (your build output folder)

Step 2: Add iOS and Android Platforms

npm install @capacitor/ios @capacitor/android
npx cap add ios
npx cap add android

This creates ios/ and android/ folders — native Xcode and Android Studio projects that wrap your web app.

Step 3: Build and Sync

Every time you change your web app, build and sync:

npm run build
npx cap sync

Step 4: Open in Native IDEs

npx cap open ios     # Opens Xcode
npx cap open android # Opens Android Studio

From Xcode you can run on a simulator or a real device. Same from Android Studio.

Step 5: Use Native APIs

Capacitor provides plugins for common native features. For push notifications:

npm install @capacitor/push-notifications
npx cap sync

import { PushNotifications } from '@capacitor/push-notifications';

async function initPushNotifications() {
  const permission = await PushNotifications.requestPermissions();

  if (permission.receive === 'granted') {
    await PushNotifications.register();
  }

  PushNotifications.addListener('registration', (token) => {
    console.log('Push token:', token.value);
    // Send token to your backend
  });

  PushNotifications.addListener('pushNotificationReceived', (notification) => {
    console.log('Notification received:', notification);
  });
}

The same code works on both iOS and Android — Capacitor handles the platform differences.

Handling Platform Differences

Capacitor exposes the platform at runtime:

import { Capacitor } from '@capacitor/core';

const platform = Capacitor.getPlatform(); // 'ios', 'android', or 'web'

if (Capacitor.isNativePlatform()) {
  // Running inside a native app shell
} else {
  // Running in a browser
}

A pattern I use is a thin abstraction layer for features that differ by platform:

// services/storage.js
import { Capacitor } from '@capacitor/core';

export const storage = {
  async get(key) {
    if (Capacitor.isNativePlatform()) {
      const { Preferences } = await import('@capacitor/preferences');
      const { value } = await Preferences.get({ key });
      return value;
    }
    return localStorage.getItem(key);
  },

  async set(key, value) {
    if (Capacitor.isNativePlatform()) {
      const { Preferences } = await import('@capacitor/preferences');
      await Preferences.set({ key, value });
    } else {
      localStorage.setItem(key, value);
    }
  },
};

The rest of the app uses storage.get() and storage.set() without knowing which platform it's running on.

Responsive Design Essentials

.container {
  width: 100%;
  max-width: 1200px;
  margin: 0 auto;
  padding: 0 16px;
}

/* Safe areas for iPhone notch and Android punch-hole cameras */
.app {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
  padding-left: env(safe-area-inset-left);
  padding-right: env(safe-area-inset-right);
}

.grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
  gap: 16px;
}

The env(safe-area-inset-*) values handle the iPhone notch and rounded corners. If you skip this, content gets cut off on modern iPhones. I missed this on an early iOS build — testers reported the top navigation was partially hidden. One CSS fix, sorted.

Things I've Learned the Hard Way

Get your app on real devices as early as possible, not just simulators. The iOS simulator handles safe area insets differently from a real iPhone. Android emulators don't replicate every manufacturer's UI skin, and some cheaper Android devices behave very differently from a Pixel or Samsung flagship. Layout bugs I completely missed in months of simulator testing showed up in the first week on real devices.

If you're handling sensitive data on native, look at @capacitor-community/secure-storage. The default @capacitor/preferences plugin stores data unencrypted. For authentication tokens or anything sensitive, encrypted storage is one npm install away — there's no reason not to use it.

Keep your business logic in the web layer. Native plugins should only handle device I/O — camera, file system, notifications. All application logic lives in your web code. It sounds obvious but it's easy to let it drift, especially as the project grows. Once business logic splits across native code, you've lost the main benefit of this approach and now have three codebases again anyway.

Wrapping Up

Ship PWA first, add Capacitor when there's a concrete reason. The hardest part isn't the technology — it's remembering to test on real devices early. Don't skip that step.

Zia Ullah is a full-stack developer with 12+ years of experience (since 2013), specializing in web applications for healthcare and SaaS. He works at ValueAdd, a software development company based in Sweden.