webapp-to-capacitor

What this skill does

# Web App to Capacitor Migration

Migrate a production web app into a native-feeling Capacitor app that can pass app store review.

## When to Use This Skill

- User asks how to turn a web app, PWA, or site into an iOS or Android app
- User wants to add Capacitor to an existing React, Vue, Angular, Svelte, Next.js, Nuxt, Vite, or vanilla web app
- User is worried the app will be rejected as a thin WebView wrapper
- User needs a migration plan from web-only to app-store-ready mobile
- User asks about native permissions, safe areas, offline support, account deletion, mobile billing, or store testing for a converted web app

## Community Lessons

Use the Reddit discussion as the framing: the basic Capacitor wrapper is usually the easy part; store approval and mobile polish are the hard parts.

Prioritize these risks before celebrating a successful native build:

- The app must behave like a mobile app, not a website in a shell.
- Safe areas, keyboard behavior, modals, gestures, loading states, and offline/error states need mobile treatment.
- Native features such as camera, location, files, notifications, and GPS are manageable, but require platform permissions and real-device testing.
- App Store and Play Store approval are separate projects: metadata, privacy, billing, demo accounts, review notes, and testing tracks matter.
- Use official docs and current store policies over old videos.
- Android Studio, Xcode, Java, signing, and certificates can take longer than the first Capacitor integration.

## Live Project Snapshot

Detected web framework, build scripts, and Capacitor packages:
!`node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const names=['@capacitor/core','@capacitor/cli','@capacitor/ios','@capacitor/android','@capgo/capacitor-updater','next','react','vue','@angular/core','@sveltejs/kit','nuxt','vite','@ionic/react','@ionic/vue','@ionic/angular'];const out=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(names.includes(name))out.push(section+'.'+name+'='+version)}}for(const [name,cmd] of Object.entries(pkg.scripts||{})){if(/build|dev|preview|start|export|sync|cap|ios|android/i.test(name))out.push('scripts.'+name+'='+cmd)}console.log(out.sort().join('\n'))"`

Relevant config and native project paths:
!`find . -maxdepth 4 \( -name 'capacitor.config.*' -o -name 'vite.config.*' -o -name 'next.config.*' -o -name 'nuxt.config.*' -o -name 'angular.json' -o -name 'svelte.config.*' -o -name 'package.json' -o -path './ios' -o -path './android' -o -name 'Info.plist' -o -name 'AndroidManifest.xml' \)`

## Command Policy

- Use the target repo's package manager for installs and package scripts.
- For Capacitor and Capgo CLI commands in this skill, use `npx` so the intended CLI version is used. Do not rewrite those examples to `bunx`.
- In Capgo repos, keep development commands on Bun when local instructions require it.

## Migration Procedure

### Step 1: Audit the Web App

Before adding Capacitor, identify:

- Framework and build output directory (`dist`, `build`, `out`, or custom)
- SSR, API routes, middleware, server actions, image optimization, or filesystem assumptions that will not run inside a native WebView
- Auth providers, social login, account deletion, subscription or payment flows
- Required native capabilities: camera, photos, files, push, location, haptics, biometrics, contacts, calendar, background tasks
- Offline expectations and what data must be cached locally
- Routes that need deep links, universal links, or custom URL schemes

If the app uses Next.js, Nuxt, SvelteKit, or another framework with SSR/static-export choices, combine this skill with `framework-to-capacitor`.

### Step 2: Make a Static Mobile Build

Capacitor ships web assets inside the native app. Make the web app produce static HTML/CSS/JS that works without a Node server.

- Replace server-only routes with external API calls or client-side flows.
- Disable framework features that require a live server in the native bundle.
- Set the correct `webDir` in `capacitor.config.*`.
- Build locally, then open the build output with a static preview server before adding native complexity.

Use this config shape as the target:

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

const config: CapacitorConfig = {
  appId: 'com.company.app',
  appName: 'App Name',
  webDir: 'dist',
  server: {
    androidScheme: 'https',
  },
};

export default config;
```

### Step 3: Add Capacitor

Install Capacitor with the app's package manager, then run the Capacitor CLI:

```bash
npx cap init
npx cap add ios
npx cap add android
npx cap sync
```

After each web build:

```bash
npx cap sync
```

Open native projects only after the web build and sync are clean:

```bash
npx cap open ios
npx cap open android
```

### Step 4: Make It Native-Feeling

Treat "works in a WebView" as the first checkpoint, not the finish line.

Required mobile polish:

- Safe-area handling for notch, Dynamic Island, home indicator, and Android edge-to-edge layouts
- Native-size tap targets, scroll momentum, pull-to-refresh only when appropriate, and no desktop hover-only controls
- Mobile navigation patterns: tabs, stacks, sheets, back-button behavior, and gestures that match platform expectations
- Keyboard-safe forms with visible focused fields and no trapped submit buttons
- Splash screen, app icon, launch/loading states, empty states, and offline states
- App-like modal dismissal and state restoration after background/resume
- No obvious browser chrome assumptions: download links, hover menus, wide tables, tiny controls, or desktop-only layouts

Use `safe-area-handling`, `capacitor-keyboard`, `capacitor-splash-screen`, `ionic-design`, `konsta-ui`, or `tailwind-capacitor` when those details are in scope.

### Step 5: Map Web Features to Native Capabilities

Prefer official Capacitor plugins first, then Capgo plugins when official coverage is missing or a Capgo plugin is a better fit.

For each native capability:

- Install the plugin
- Add iOS usage strings in `Info.plist`
- Add Android permissions only when needed
- Handle denied, limited, unavailable, and simulator-only states
- Test on real iOS and Android devices when the feature touches camera, files, push, location, biometrics, or background behavior

Do not request permissions on first launch unless the app needs them immediately. Ask in context after explaining the value in the UI.

### Step 6: Run Store Readiness Before Submission

Call out thin-wrapper risk directly. A converted app is more likely to pass review when it has clear app value, mobile-native interaction, and reviewer-friendly metadata.

Apple checks:

- If users can log in, provide demo credentials or an approved demo mode.
- If third-party/social login is used, check Sign in with Apple requirements.
- If users create accounts, provide account deletion.
- If the app sells digital goods or subscriptions, verify whether Apple In-App Purchase or an allowed external-link entitlement is required.
- Remove placeholder content, test pages, broken links, and web-only billing pages from the iOS build when they violate review rules.
- Add reviewer notes for non-obvious native functionality, live updates, demo data, and hardware-dependent flows.

Google Play checks:

- Complete Data safety, content rating, target SDK, signing, and release track setup.
- For personal developer accounts created after November 13, 2023, plan for the current closed-testing requirement before production access.
- Build a tester plan early; do not leave Play testing logistics until launch week.

Use `capacitor-apple-review-preflight` for Apple-specific risk and `capacitor-app-store` for final submission work.

### Step 7: Verify on Devices

Minimum verification:

- Web build and static preview pass
- `npx cap sync` succeeds
- iOS simulator launch succ