Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 37 ยท Capacitor and Native APIs

Capacitor Overview and Project Setup

Understand how Capacitor wraps your Ionic web app in a native shell, add Android and iOS platforms, configure capacitor.config.ts and sync web code to native projects.

An Ionic app is a web app: HTML, CSS and JavaScript. A browser tab can show it, but a phone user expects an icon on the home screen, a camera, files, notifications and a place in the app store. Capacitor is the layer that makes this possible. It puts your built web app inside a native Android or iOS project, shows it in the system web view, and gives your JavaScript a bridge to native features.

This lesson explains how that bridge works, how to add platforms to an Ionic project, what the capacitor.config.ts file controls and what sync really does. The next lessons use plugins such as the camera and filesystem, so this is the foundation. It assumes you have a working Ionic project from the earlier chapters.

The big picture

Capacitor has three parts:

  • Core: a small JavaScript runtime (@capacitor/core) and a native runtime for each platform. It routes calls from JavaScript to native code and back.
  • Plugins: pairs of JavaScript API and native implementation, such as Camera, Filesystem, Geolocation or Haptics.
  • Native projects: real Android Studio and Xcode projects in android/ and ios/ folders that you own and can edit.
flowchart LR
  A["Your Ionic app<br/>(TypeScript, HTML, CSS)"] -->|"npm run build"| B["www / dist folder"]
  B -->|"npx cap sync"| C["android/ project"]
  B -->|"npx cap sync"| D["ios/ project"]
  C --> E["Web view + native plugins"]
  D --> E

Capacitor copies your build output into each native project; the web view loads it from the app bundle, not from the internet.

Unlike older tools, Capacitor treats the native folders as source code. You commit them, open them in Android Studio or Xcode and change them when you need to. There is no hidden build step that regenerates them.

Adding Capacitor to a project

New Ionic projects created with the CLI already include Capacitor. For an existing web project the steps are the same. Real commands, read-only:

Terminal
# Install the core runtime and the command line tool
npm install @capacitor/core
npm install -D @capacitor/cli

# Create capacitor.config.ts (asks for app name and id)
npx cap init "Trail Notes" com.example.trailnotes --web-dir=www

# Add the platforms you want to ship
npm install @capacitor/android @capacitor/ios
npx cap add android
npx cap add ios

# Build the web app, then copy it into the native projects
npm run build
npx cap sync

The app id (com.example.trailnotes) is a reverse-domain name. It becomes the Android applicationId and the iOS bundle identifier. Both stores use it as the permanent identity of your app, so choose it once and do not change it after publishing.

capacitor.config.ts

This file sits at the project root. It is read by the CLI at sync time and by the native runtime at launch.

TypeScript
import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.trailnotes',
  appName: 'Trail Notes',
  webDir: 'www',               // folder produced by your build
  server: {
    androidScheme: 'https',    // the web view origin is https://localhost
  },
  plugins: {
    SplashScreen: { launchShowDuration: 0 },
  },
};

export default config;

webDir must match the real output folder of your framework build (www for Ionic Angular, dist for Vite based React and Vue projects). Plugin options live under plugins, keyed by plugin name.

During development you can point the app at your dev server with server.url (for example http://192.168.1.20:5173) and enable live reload with npx cap run android -l --external. Remove server.url before building for release, or the store build will try to load your laptop.

What sync, copy and update do

Command What it does
npx cap copy Copies webDir and capacitor.config.ts into the native projects
npx cap update Updates native plugin dependencies from package.json
npx cap sync Runs copy and update together
npx cap open android Opens the project in Android Studio
npx cap run ios Builds and runs on a device or simulator

Run sync after every web build, and after installing or removing a plugin. Forgetting it is the most common reason "my change is not on the phone".

Calling a plugin

Every plugin call is asynchronous and returns a promise, because it crosses from the web view to native code. In your TypeScript you import the plugin and call it like any other module.

TypeScript
import { Capacitor } from '@capacitor/core';
import { Device } from '@capacitor/device';

if (Capacitor.isNativePlatform()) {
  const info = await Device.getInfo();
  console.log(info.platform, info.model);   // "android", "Pixel 8"
}
console.log(Capacitor.getPlatform());       // 'web' | 'android' | 'ios'

Capacitor.getPlatform() and isNativePlatform() let one code base behave differently in a browser and on a device. Many plugins also have a web implementation, so you can test them in the browser during development.

A runnable stand-in: the bridge

The real bridge is native code, so the live examples use a small JavaScript model of it. Each plugin is registered by name, calls are asynchronous and unknown plugins fail the way a missing native implementation would.

JS A tiny plugin bridge

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Reading the config at run time

Plugins read the plugins section of the config. A realistic stand-in merges defaults with your options, which is how most native plugins behave.

JS Merging plugin config with defaults

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does Capacitor load your Ionic app from on a phone?

    Sync copies the web build into android/ and ios/, and the web view loads it from the app bundle.
  2. 2. You installed a new plugin. Which command makes the native project aware of it?

    cap sync copies the web assets and updates native dependencies, including new plugins.
  3. 3. What does webDir in capacitor.config.ts point to?

    webDir must match the framework build output, for example www or dist.
  4. 4. Which call tells you whether the code runs in a browser or on a device?

    getPlatform() returns web, android or ios, and isNativePlatform() returns a boolean.

Summary

  • Capacitor hosts your built web app in a native web view and bridges JavaScript to native plugins.
  • android/ and ios/ are real projects that you commit and may edit.
  • capacitor.config.ts holds the app id, name, webDir and plugin options.
  • Run npx cap sync after each build and after plugin changes.
  • Use Capacitor.getPlatform() to branch between web and native behavior.

Next: Camera and Filesystem