---
name: capacitor-hybrid-app
description: "Wrap a web app as native iOS + Android with Capacitor. Plugin access to native APIs without rewriting. Bootstraps Capacitor projects: native plugin integration (camera, push, filesystem), App Store / Play Store config, deep-link handlers."
license: MIT
---

# Capacitor Hybrid App Builder

Take an existing web app — React, Vue, Angular, Svelte, or plain HTML — and ship it to the App Store and Google Play without rewriting your UI in Swift or Kotlin. This skill scaffolds a Capacitor project around your build output, wires up the native plugins you actually need, and configures the platform-specific files that the stores require. It's aimed at frontend and Ionic developers who want native distribution and device APIs without maintaining two separate native codebases.

## When to use it

- You have a deployed web app and want it in the stores as a real installable binary, not just a PWA.
- You need device features your web code can't reach: camera, push notifications, filesystem, geolocation, haptics, secure storage.
- You're adding deep links (`myapp://` or Universal/App Links) and need the iOS and Android handlers set up correctly.
- You're migrating from Cordova and want the modern plugin model.

## How it works

The skill drives the Capacitor CLI and edits the native projects it generates. Core flow:

- `npm install @capacitor/core @capacitor/cli` and `npx cap init` to create `capacitor.config.ts`, where `webDir` points at your build output (e.g. `dist`, `build`, `www`).
- `npx cap add ios` and `npx cap add android` generate the native Xcode and Gradle projects.
- Plugins are installed as npm packages (`@capacitor/camera`, `@capacitor/push-notifications`, `@capacitor/filesystem`, `@capacitor/app`) and registered automatically; the skill adds the required `Info.plist` usage strings on iOS and permissions/`AndroidManifest.xml` entries on Android.
- Deep links: configures `CFBundleURLTypes` / Associated Domains on iOS and `intent-filter` blocks on Android, plus `App.addListener('appUrlOpen', ...)` handling.
- `npx cap sync` copies your web assets and updates native dependencies after every build.

## Usage example

```bash
curl -fsSL --create-dirs -o ~/.claude/skills/capacitor-hybrid-app/SKILL.md https://claudeskil.com/skills/capacitor-hybrid-app/SKILL.md

# from your web project root
npm run build
npx cap init "My App" com.example.myapp --web-dir=dist
npm i @capacitor/camera @capacitor/push-notifications
npx cap add ios && npx cap add android
npx cap sync
npx cap open ios   # launches Xcode to run/sign
```

```ts
import { Camera, CameraResultType } from '@capacitor/camera';
const photo = await Camera.getPhoto({ quality: 90, resultType: CameraResultType.Uri });
```

## Tips & gotchas

- Run `npx cap sync` after **every** web build and after adding any plugin — `cap copy` alone won't update native deps.
- `webDir` must match your bundler's output folder exactly, or you'll ship a blank white screen.
- On iOS, missing `Info.plist` usage description strings cause silent permission failures and App Store rejection.
- Live reload during dev: set `server.url` in `capacitor.config.ts` to your dev server, but remove it before release builds.

## FAQ

**Do I still need Xcode and Android Studio?** Yes — they're required for signing, running on devices, and submitting. Capacitor generates standard native projects you open in each IDE.

**Can I write custom native code?** Yes. You can author a Capacitor plugin in Swift/Kotlin or drop native code directly into the generated projects; the web layer calls it through a registered plugin bridge.

**Does it work with Ionic?** Fully — Capacitor is Ionic's official native runtime, but it works equally well with any web framework.