How to Use Capacitor: The Beginner's Guide (Turn Your Web App Into a Real iOS and Android App)

CodexFuse Team · 2026-10-31T03:57:27.257Z · 15 min read

What is Capacitor, exactly?

Capacitor is an open-source native runtime that turns your existing web app into a real installable iOS and Android app. You keep writing HTML, CSS, and JavaScript exactly as you do today — Capacitor wraps your built web code in native iOS and Android projects and gives it a bridge to device features like the camera, geolocation, and push notifications. Here is how to use Capacitor, the whole beginner arc in one page: check your environment, drop it into your finished web app, add the native projects, sync your build, wire one real plugin, run on a phone, and know what the stores expect. This Capacitor tutorial targets beginners with a working web app — it does not start from an Ionic template, because the most common real-world use is adding mobile to something you already built. Most real apps also talk to a backend service, and our REST API tester is the fastest way to check the endpoints your mobile UI will call before you ever open Xcode.

Think of Capacitor as a two-part system. The core runtime (@capacitor/core) is JavaScript that lives inside your web code and exposes native features through a clean async API. The CLI (@capacitor/cli) is the command-line tool that creates the native projects, copies your built web assets into them, and keeps everything in sync. Your web app never runs in a browser on the phone — it runs in a native shell that displays your web UI and lets plugins reach real device APIs. Three things are required before it works in an existing project: a package.json file, a separate directory of built web assets (like dist or www), and an index.html at the root of that directory with a <head> tag, which Capacitor uses to inject itself.

How does Capacitor compare to Cordova and React Native?

Capacitor is the modern answer to "how do I ship my web skills as mobile apps" — but it is not the only answer, and picking the right one saves you months. Here is the honest comparison for a beginner deciding in 2026.

Capacitor vs Cordova: Cordova pioneered the hybrid model and is still maintained by the Apache Software Foundation, but in 2026 it is a maintenance choice, not a starting point. Capacitor was built by the Ionic team to modernize the same idea — faster native bridges, first-class PWA support, and an officially documented migration path for Cordova apps. Start new projects with Capacitor.

Capacitor vs React Native: React Native renders genuine native UI components, so apps feel slightly more "native," but you must learn its component model and you cannot simply reuse an existing website. Capacitor ships your actual web code, so a finished web app can become a mobile app in an afternoon — the honest trade-off is the WebView: perfect for content and business apps, wrong for games or heavy animation.

What do you need before you start?

You need three things, and the iOS one is non-negotiable: iOS builds require a Mac. Say it up front so nobody wastes a day on Windows. The official requirements for Capacitor 8, checked on October 30, 2026, are:

1. Node.js 22 or higher. Check with node --version. The docs' own example shows v22.21.1. Capacitor 8 will not run on older Node.
2. For iOS: macOS, Xcode 26.0 or higher, and the Xcode Command Line Tools (xcode-select --install). Capacitor 8 uses Swift Package Manager as the default iOS dependency manager; CocoaPods is optional. Cloud build services exist, but the docs recommend local tooling so you can actually test.
3. For Android: Android Studio 2025.2.1 or higher with an Android SDK for API 24 or greater. You do not need to install the JDK separately — Android Studio installs the right one for you.

You can target iOS only, Android only, or both — skip the section for any platform you are not building for. A plain web app plus these tools is the entire prerequisite list; there is no Ionic account, no cloud subscription, and no sign-up required to start.

How do I install Capacitor in my existing web app?

You install Capacitor by adding two npm packages to your current project and running a short questionnaire — it takes about two minutes. Do this at the root of your web app, not in a new directory:

npm i @capacitor/core
npm i -D @capacitor/cli
npx cap init

npx cap init asks for your app name and your app ID (reverse-domain style, like com.yourcompany.yourapp). The app ID is permanent — it is how the stores identify your app forever — so choose it as carefully as a domain name.

Before you touch anything else, learn the webDir rule, the number-one beginner pitfall in the Capacitor for beginners field: webDir in capacitor.config.ts must point at your bundler's real build-output folder. The official docs give the defaults: www for Angular, build for React, public for Vue. Capacitor tries to detect yours, but always verify it. A mismatched webDir is the single most common cause of a blank white screen after adding Capacitor — your app builds fine, syncs fine, and launches to nothing, because the native project copied an empty or wrong folder. Run npm run build first, confirm the folder actually exists, then set webDir to it. Teach yourself this order now: build, verify webDir, sync.

How do I add the iOS and Android projects?

You add the native projects by installing the two platform packages and running one command per platform. These commands generate real, editable Xcode and Android Studio projects — ios/ and android/ folders inside your project:

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

Then sync your web code into them:

npx cap sync

npx cap sync does two jobs at once: it copies your built web bundle (from webDir) into each native project, and it installs and configures the native side of any Capacitor plugins. Open the results with npx cap open ios and npx cap open android, which launch Xcode and Android Studio with the projects loaded.

Unlike Cordova, these native projects are first-class citizens. You can open them, read them, and even write native code in them directly — Capacitor does not hide the native layer behind a black box. Many teams commit the ios/ and android/ folders to version control so the whole project builds from one clone; if you need a refresher on that workflow, our GitHub beginner guide walks through repos, branches, and commits from zero.

What does "npx cap sync" actually do, and when do I run it?

npx cap sync copies your latest built web assets and plugin configuration into the native projects — and your daily workflow is a three-step loop: build, sync, open/run. Memorize it now, because nearly every "my changes are not showing up" report comes from skipping a step:

npm run build
npx cap sync
npx cap run android

The native projects hold a static copy of your last build, not a live reference to your source code. If you edit your web code and jump straight to Xcode, you will test yesterday's app. Every change needs npm run build followed by npx cap sync before it appears on the device.

For faster iteration during development, Capacitor has a live-reload mode: npx cap run ios -l --external points the native shell at your local dev server so edits appear instantly. It is a development workflow only — disable it before any real build, because a shipped app must never point at a dev server on your laptop.

How do I use Capacitor plugins? A camera in ten minutes

You use Capacitor plugins exactly like the core: install the npm package, sync, and call an async API from your web code. The camera is the perfect first plugin because it touches everything — JavaScript, native code, and permissions. Install it:

npm install @capacitor/camera
npx cap sync

Then take a photo from your web code:

import { Camera } from '@capacitor/camera';

const takePicture = async () => {
  const result = await Camera.takePhoto({ quality: 90 });
  document.querySelector('img').src = result.webPath;
};

That is the whole integration — the same call also works on the web, where the plugin falls back to a file picker. Two details separate beginners from stuck beginners here. First, permissions are your job: iOS requires usage descriptions in Info.plist (NSCameraUsageDescription, plus the two photo-library keys), and Android needs the matching manifest entries when saving to the gallery — declare a permission you never justify and the store review will reject you. Second, mind the 2026 API change: Capacitor 8.1.0 introduced this improved camera API and deprecated getPhoto and pickImages, so guides that teach Camera.getPhoto are already out of date. When you copy plugin code from the internet, check the method names against the current official plugin docs before trusting it.

How do I run my app on a phone or an emulator?

You run your app on an emulator first and a real device as soon as possible — emulators lie about cameras, GPS, and performance. The fastest path on Android: in Android Studio, open Device Manager, create a virtual device, and press Run. On iOS you need the Mac from step one — pick a simulator in Xcode and press Run. npx cap run android and npx cap run ios do the build-and-launch in one command.

Test on a real device before you believe anything. Android phones connect over USB with developer mode enabled; iPhones need a free Apple ID for development signing or a paid Apple Developer account for distribution. When you have a test build worth sharing — a TestFlight link, an internal Play track, or an APK download page — turn the URL into a scannable code with our QR code generator so testers can open it by pointing their phones at it instead of typing a long link.

What are Capacitor Live Updates?

Capacitor Live Updates let you ship changes to your web layer — HTML, CSS, and JavaScript — to users without a store review. Because your app's UI is web code, an update service (the best-known third-party one is Capgo) can push a new bundle to installed apps instantly. This is the superpower Cordova-era tooling could never offer cleanly.

The boundary matters, and beginners get it wrong: live updates cover web-layer changes only. Anything that touches native code, adds a new plugin, or changes platform permissions still needs a native build and a store submission. Change a button color on Tuesday, ship it Tuesday; add push notifications on Wednesday, that is a build. Design your release process around that line and you will use it well.

What do I need before submitting to the App Store and Google Play?

You need signing set up, store accounts paid for, and your permissions story airtight — the build is the easy part of store submission. The checklist, in order:

1. Developer accounts. Apple Developer Program is $99 per year; a Google Play Developer account is a $25 one-time fee.
2. Release signing. iOS: add your development team in Xcode and archive a release build. Android: create a release keystore and reference it in your build configuration — lose the keystore and you can never update that app listing again, so back it up like a password.
3. Version numbers. Bump the version in both native projects before every submission; stores reject duplicate versions outright.
4. Permission declarations. Every camera, location, or microphone permission you used must be justified in the store's privacy questionnaire and in the app itself — the Info.plist and manifest entries from the plugin section are not optional paperwork.
5. Real-device testing. Run the exact release build on at least one real iPhone and one real Android phone. Emulators will not catch camera, GPS, or memory issues.

None of this requires changing your web code — that is the point of the whole Capacitor model. Your web app stays your web app; the stores just get a native shell around it.

Frequently asked questions

Can I build games with Capacitor?

You can, but you probably should not. Capacitor runs your UI in a WebView inside a native shell, which is excellent for content apps, dashboards, forms, and business tools, but falls short for games, heavy animation, or anything needing maximum frame rates. For game-like experiences, a framework that renders natively (Flutter, React Native, or a real game engine) is the better choice.

Do I need a Mac to use Capacitor?

Only for the iOS half. Android development works on Windows, Mac, and Linux. But iOS builds require macOS and Xcode — there is no way to build, sign, or properly test an iPhone app without one, although cloud build services exist as a workaround. If you only have Windows, target Android first and add iOS when you have Mac access.

Does Capacitor work with React, Vue, Angular, and Svelte?

Yes — Capacitor is framework-agnostic and drops into any modern JavaScript web app. The only thing that changes per framework is the webDir value, which must match your bundler's real build-output folder (dist, build, www, or a static export). The init, add, sync, and plugin workflow is identical everywhere.

Is Capacitor free to use?

Yes. Capacitor is free and open source under the MIT license, maintained by Ionic (part of OutSystems) with the community. The costs around it are Apple's $99-per-year developer program and Google's $25 one-time Play fee — those belong to the stores, not to Capacitor. Optional services like live-update platforms have their own pricing.

Can I convert an existing Cordova app to Capacitor?

Yes, and there is a documented migration path. Capacitor even supports many Cordova plugins through a compatibility layer, so you can migrate in stages rather than rewriting everything at once. The typical migration initializes Capacitor in the existing project, adds the platforms, syncs, and swaps plugins over one at a time.

Sources

Facts in this guide were verified on October 30, 2026 against the following sources. No statistics, versions, or prices are claimed from memory:

• Capacitor official documentation — "Installing Capacitor" — npm i @capacitor/core / @capacitor/cli, npx cap init questionnaire, existing-app requirements (package.json, separate build directory, index.html with a <head> tag), platform install commands, npx cap sync behavior, webDir defaults (www Angular, build React, public Vue) — https://capacitorjs.com/docs/getting-started
• Capacitor official documentation — "Environment Setup" — Node.js 22 or higher; iOS requires macOS, Xcode 26.0+, Xcode Command Line Tools; Swift Package Manager is the default iOS dependency manager since Capacitor 8 (CocoaPods optional via --packagemanager CocoaPods); Android requires Android Studio 2025.2.1+, Android SDK API 24+, JDK installed automatically — https://capacitorjs.com/docs/getting-started/environment-setup
• Capacitor official documentation — "Camera Capacitor Plugin API" — npm install @capacitor/camera + npx cap sync; Camera.takePhoto({ quality: 90 }) as the new 8.1.0 API; getPhoto and pickImages deprecated; iOS Info.plist usage-description keys; Android photo-picker behavior — https://capacitorjs.com/docs/apis/camera
• Capawesome, "Capacitor Setup Guide for Any Web Framework" — install → init → add platforms → build → sync → open in Xcode/Android Studio loop; webDir mismatch as the top blank-screen cause; live reload npx cap run ios -l --external as dev-only; Live Updates cover web-layer changes only — https://capawesome.io/blog/build-mobile-apps-with-any-web-framework-and-capacitor/
• App369, "Titanium, PhoneGap and Xamarin Are Gone: Which Cross-Platform Framework in 2026?" (updated October 21, 2026) — Capacitor 8.5.3 (October 7, 2026); Apache Cordova still maintained but a maintenance choice, not a starting point; Ionic + Capacitor MIT licensed — https://app369.com/blog/titanium-phonegap-xamarin-cross-platform-frameworks-2026/
• Rankite, "Best Software to Develop Mobile Apps in 2026" — Capacitor vs React Native trade-offs; the WebView limitation for games and heavy animation; Ionic/Capacitor for web teams with no mobile specialists — https://rankite.com/blog/best-software-to-develop-mobile-apps
• MobiDev, "Best Apache Cordova Alternatives: CTO's Migration Guide 2026" — Capacitor as a top Cordova alternative; migration feasibility — https://mobidev.biz/blog/apache-cordova-alternatives-cross-platform-mobile-app-development
• CopyProgramming, "Migrating Ionic Apps from Cordova to Capacitor" — Capacitor 8 as the 2026 standard for new projects; Apple Developer $99/year and Google Play $25 one-time store costs; Cordova-to-Capacitor migration steps — https://copyprogramming.com/howto/ionic-app-from-cordova-to-capacitor-code-example