Capacitor: Cross-Platform Native Runtime

Capacitor is a cross-platform native runtime for building Web Native apps that run on iOS, Android, and the web from a single modern web codebase. It provides a consistent, web-focused API layer that bridges JavaScript to native device features via a plugin system.

Core Workflow

The canonical development loop is:

Build web assets:
```
npm run build
```
(or
```
ng build
```
,
```
vite build
```
, etc.)
Sync to native projects:
```
npx cap sync
```
- Copies the web bundle into iOS and Android native projects
- Installs/updates native plugin dependencies
- Run this after every web build or plugin change
Test on device:
bash
```
npx cap run ios
npx cap run android
```

Open native IDE when native changes are needed:

bash

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

Build a release binary:

bash

npx cap build android  # outputs signed AAB/APK
npx cap build ios      # outputs IPA

Keep

@capacitor/core

@capacitor/ios

, and

@capacitor/android

on identical versions at all times. Update all together:

bash

npm i @capacitor/core @capacitor/ios @capacitor/android
npm i -D @capacitor/cli

Configuration

Capacitor-level settings live in

capacitor.config.ts

(or

.json

). This file controls tooling only — not native runtime behavior. Key fields:

Field	Purpose
`appId`	Bundle identifier (e.g. `com.example.app` )
`appName`	Display name
`webDir`	Output directory of the web build (e.g. `dist` , `build` , `www` )
`server.url`	Override for live reload (remove before committing)

Platform-specific runtime configuration is done in native IDEs:

ios/App/App/Info.plist

and

AndroidManifest.xml

for Android. Do not attempt to manage those via the Capacitor config file.

Plugins

Capacitor plugins expose native APIs to JavaScript. Three sources exist:

Official plugins (
```
@capacitor/*
```
) — maintained by the Capacitor team, covering Camera, Filesystem, Geolocation, Push Notifications, Preferences, etc.
Community plugins (
```
@capacitor-community/*
```
) — curated third-party ecosystem
Cordova plugins — compatibility layer; prefer Capacitor-native equivalents

Install a plugin, then sync:

bash

npm install @capacitor/camera
npx cap sync

Always check whether a plugin requires additional native configuration (entitlements on iOS, permissions in

AndroidManifest.xml

). The plugin's README will specify.

Mocking Plugins in Tests

Capacitor plugins are JavaScript proxies; wrapping a proxy in another proxy fails. Use manual mocks instead.

Jest — place stubs under

__mocks__/@capacitor/

// __mocks__/@capacitor/preferences.ts
export const Preferences = {
  async get(data: { key: string }) { return { value: undefined }; },
  async set(_data: { key: string; value: string }) {},
  async remove(_data: { key: string }) {},
  async clear() {},
};

Jest auto-discovers files from

__mocks__/

before

node_modules

Jasmine/Angular — add a

paths

mapping in

tsconfig.spec.json

json

"paths": {
  "@capacitor/*": ["__mocks__/@capacitor/*"]
}

Note:

paths

tsconfig.spec.json

replaces (does not merge with) the base

tsconfig.json

paths — include all existing entries.

Storage

Do not rely on

localStorage

IndexedDB

as primary storage on mobile. The OS reclaims both when storage is low. IndexedDB on iOS is not persisted by default.

Use case	Recommended solution
Small key/value data (settings, tokens)	`@capacitor/preferences`
Large datasets / SQL queries	SQLite plugin ( `capacitor-sqlite` )
Sensitive values (encryption keys, auth tokens)	iOS Keychain / Android Keystore via a plugin

import { Preferences } from '@capacitor/preferences';

// Write
await Preferences.set({ key: 'theme', value: 'dark' });

// Read
const { value } = await Preferences.get({ key: 'theme' });

// Remove
await Preferences.remove({ key: 'theme' });

Preferences

values are stored natively and survive app updates and low-storage eviction.

Security

Secrets and API Keys

Never embed secrets in web app code. The JavaScript bundle ships inside the app binary and is trivially extractable. Move secret-dependent logic server-side (serverless function or backend API). If a token must exist on device (e.g. auth token), store it only in memory or in the native Keychain/Keystore — never in

localStorage

Preferences

unencrypted.

Network

Only make requests to

https://

endpoints. Never use

http://

in production builds.

Content Security Policy

Add a CSP

<meta>

tag in

index.html

to restrict resource loading:

html

<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self'; connect-src 'self' https://api.example.com"
/>

oAuth2 / Deep Link Authentication

Custom URL schemes (e.g.

myapp://

) are not domain-controlled and can be intercepted by a malicious app. Never pass sensitive tokens through a custom scheme. Use Universal Links (iOS) or App Links (Android) for auth callbacks, and always enable PKCE in oAuth2 flows.

Deep Links (Universal Links / App Links)

Deep links allow HTTPS URLs to open specific screens inside the native app. Prefer Universal/App Links over custom URL schemes — they require verified web domain ownership.

Listen for Incoming Links

import { App } from '@capacitor/app';

App.addListener('appUrlOpen', (event) => {
  const path = new URL(event.url).pathname;
  // hand off to your router
  router.navigate(path);
});

Required Setup (both platforms)

Host a site association file at

https://yourdomain.com/.well-known/

iOS:
```
apple-app-site-association
```
(no extension, JSON)
Android:
```
assetlinks.json
```

Configure the native app:
- iOS: enable Associated Domains in Xcode (
```
applinks:yourdomain.com
```
  )
- Android: add
```
intent-filter
```
  with
```
android:autoVerify="true"
```
  in
```
AndroidManifest.xml
```

See

references/security-and-deeplinks.md

for complete file formats and intent filter XML.

Live Reload (Development Only)

Live reload reloads the WebView when web source files change — no native rebuild required.

With Ionic CLI (recommended):

bash

npm install -g @ionic/cli native-run
ionic cap run ios -l --external
ionic cap run android -l --external

Without Ionic CLI — add a

server

entry to

capacitor.config.json

json

"server": {
  "url": "http://192.168.1.68:8100",
  "cleartext": true
}

Run

npx cap copy

to push the config update, then launch from the native IDE.

Never commit the
server
config to source control. Remove it before building for release.

Quick Reference

Task	Command
Sync web build to native	`npx cap sync`
Copy web assets only	`npx cap copy`
Open iOS project	`npx cap open ios`
Open Android project	`npx cap open android`
Run on device	`npx cap run ios` / `npx cap run android`
Build release binary	`npx cap build ios` / `npx cap build android`
Update Capacitor	`npm i @capacitor/core @capacitor/ios @capacitor/android`

Additional Resources

references/plugins-and-storage.md
— Plugin installation patterns, Preferences API reference, SQLite options, and testing stubs in detail
references/security-and-deeplinks.md
— CSP patterns, Keychain/Keystore guidance, full Universal Links / App Links file formats, PKCE requirements

capacitor

NPX Install

Tags

SKILL.md Content

Capacitor: Cross-Platform Native Runtime

Core Workflow

Configuration

Plugins

Mocking Plugins in Tests

Storage

Security

Secrets and API Keys

Network

Content Security Policy

oAuth2 / Deep Link Authentication

Deep Links (Universal Links / App Links)

Listen for Incoming Links

Required Setup (both platforms)

Live Reload (Development Only)

Quick Reference

Additional Resources