Antigravity × Capacitor Hybrid App Implementation Guide: An AI-Driven Workflow for Taking a Web App to iOS/Android Native

# Example setup commands Antigravity will auto-run
node -v  # Confirm v20 or higher
pod --version  # Confirm 1.15 or higher
xcodebuild -version  # Confirm Xcode 16 or higher
 
# If CocoaPods isn't installed
sudo gem install cocoapods

# Run from the project root
npm install @capacitor/core @capacitor/cli
npx cap init
 
# Inputs during initialization
# App Name: MyApp
# App ID: com.yourcompany.myapp (reverse domain format)
# Web Dir: out (Next.js static output directory)

// capacitor.config.ts
// Antigravity auto-adds WebViewSettings and other best-practice configs
import type { CapacitorConfig } from '@capacitor/cli';
 
const config: CapacitorConfig = {
  appId: 'com.yourcompany.myapp',
  appName: 'MyApp',
  webDir: 'out',
  server: {
    // Use local server during development (remove in production)
    // url: 'http://192.168.1.x:3000',
    // cleartext: true,
  },
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      backgroundColor: '#ffffff',
      androidSplashResourceName: 'splash',
      showSpinner: false,
    },
    PushNotifications: {
      presentationOptions: ['badge', 'sound', 'alert'],
    },
  },
};
 
export default config;

# Add iOS/Android platforms
npm install @capacitor/ios @capacitor/android
npx cap add ios
npx cap add android
 
# Build the project and sync to native
npm run build  # Next.js static export
npx cap sync   # Update native projects to latest state

npm install @capacitor/camera
npx cap sync

// src/hooks/useCamera.ts
// Antigravity generates a type-safe implementation including permission handling
import { Camera, CameraResultType, CameraSource, Photo } from '@capacitor/camera';
import { useState, useCallback } from 'react';
 
interface UseCameraReturn {
  photo: Photo | null;
  takePhoto: () => Promise<void>;
  pickFromGallery: () => Promise<void>;
  error: string | null;
  isLoading: boolean;
}
 
export const useCamera = (): UseCameraReturn => {
  const [photo, setPhoto] = useState<Photo | null>(null);
  const [error, setError] = useState<string | null>(null);
  const [isLoading, setIsLoading] = useState(false);
 
  const requestPermissions = async (): Promise<boolean> => {
    const permissions = await Camera.requestPermissions({
      permissions: ['camera', 'photos'],
    });
    return (
      permissions.camera === 'granted' &&
      permissions.photos === 'granted'
    );
  };
 
  const takePhoto = useCallback(async () => {
    setIsLoading(true);
    setError(null);
 
    try {
      const granted = await requestPermissions();
      if (!granted) {
        setError('Camera access is required. Please enable it in Settings.');
        return;
      }
 
      const result = await Camera.getPhoto({
        quality: 85,                          // Image quality (0-100)
        allowEditing: false,
        resultType: CameraResultType.DataUrl, // Get as base64 DataURL
        source: CameraSource.Camera,
        width: 1024,
        height: 1024,
        correctOrientation: true,             // Auto-rotate correction
      });
 
      setPhoto(result);
    } catch (err) {
      // Don't treat user cancellation as an error
      if (err instanceof Error && err.message.includes('cancelled')) {
        return;
      }
      setError('An error occurred while capturing the photo.');
      console.error('Camera error:', err);
    } finally {
      setIsLoading(false);
    }
  }, []);
 
  const pickFromGallery = useCallback(async () => {
    setIsLoading(true);
    setError(null);
 
    try {
      const result = await Camera.getPhoto({
        quality: 85,
        allowEditing: false,
        resultType: CameraResultType.DataUrl,
        source: CameraSource.Photos, // Select from gallery
        width: 1024,
        height: 1024,
      });
 
      setPhoto(result);
    } catch (err) {
      if (err instanceof Error && err.message.includes('cancelled')) {
        return;
      }
      setError('An error occurred while accessing the gallery.');
    } finally {
      setIsLoading(false);
    }
  }, []);
 
  return { photo, takePhoto, pickFromGallery, error, isLoading };
};

<!-- Add to ios/App/App/Info.plist -->
<!-- Antigravity can auto-detect this requirement and suggest adding it -->
<key>NSCameraUsageDescription</key>
<string>Used for taking profile photos and uploading product images</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Used for selecting images from your gallery</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Used for saving captured photos to your camera roll</string>

<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-feature android:name="android.hardware.camera" android:required="false" />

npm install @capacitor/push-notifications
npx cap sync

// src/services/pushNotifications.ts
import { PushNotifications, PushNotificationSchema, ActionPerformed } from '@capacitor/push-notifications';
import { Capacitor } from '@capacitor/core';
 
export class PushNotificationService {
  private static instance: PushNotificationService;
  private token: string | null = null;
 
  private constructor() {}
 
  static getInstance(): PushNotificationService {
    if (!PushNotificationService.instance) {
      PushNotificationService.instance = new PushNotificationService();
    }
    return PushNotificationService.instance;
  }
 
  async initialize(onTokenReceived: (token: string) => void): Promise<void> {
    // Only runs on native platforms (skip web environment)
    if (!Capacitor.isNativePlatform()) {
      console.log('Push notifications are only available on native platforms');
      return;
    }
 
    // Register listeners for notification events
    PushNotifications.addListener('registration', (token) => {
      this.token = token.value;
      console.log('Push registration token: ', token.value);
      onTokenReceived(token.value);
    });
 
    PushNotifications.addListener('registrationError', (error) => {
      console.error('Push registration error: ', error.error);
    });
 
    // Handle foreground notifications
    PushNotifications.addListener('pushNotificationReceived', (notification: PushNotificationSchema) => {
      console.log('Push notification received: ', notification);
      this.handleForegroundNotification(notification);
    });
 
    // Handle notification tap actions
    PushNotifications.addListener('pushNotificationActionPerformed', (action: ActionPerformed) => {
      console.log('Push action performed: ', action);
      this.handleNotificationAction(action);
    });
 
    // Request permissions and register
    await this.requestPermissionAndRegister();
  }
 
  private async requestPermissionAndRegister(): Promise<void> {
    let permStatus = await PushNotifications.checkPermissions();
 
    if (permStatus.receive === 'prompt') {
      permStatus = await PushNotifications.requestPermissions();
    }
 
    if (permStatus.receive !== 'granted') {
      console.warn('Notification permission denied');
      return;
    }
 
    await PushNotifications.register();
  }
 
  private handleForegroundNotification(notification: PushNotificationSchema): void {
    // Handle foreground notification (show custom UI, etc.)
    const event = new CustomEvent('push-notification-received', {
      detail: notification,
    });
    window.dispatchEvent(event);
  }
 
  private handleNotificationAction(action: ActionPerformed): void {
    // Deep link handling from notification
    const data = action.notification.data;
    if (data?.route) {
      window.location.href = data.route;
    }
  }
 
  getToken(): string | null {
    return this.token;
  }
 
  async removeAllListeners(): Promise<void> {
    await PushNotifications.removeAllListeners();
  }
}

npm install @aparajita/capacitor-biometric-auth
npx cap sync

// src/hooks/useBiometricAuth.ts
import { BiometricAuth, BiometryType } from '@aparajita/capacitor-biometric-auth';
import { useState, useEffect } from 'react';
 
interface BiometricAuthState {
  isAvailable: boolean;
  biometryType: string;
  authenticate: () => Promise<boolean>;
}
 
export const useBiometricAuth = (): BiometricAuthState => {
  const [isAvailable, setIsAvailable] = useState(false);
  const [biometryType, setBiometryType] = useState('');
 
  useEffect(() => {
    checkBiometryAvailability();
  }, []);
 
  const checkBiometryAvailability = async () => {
    try {
      const result = await BiometricAuth.checkBiometry();
      setIsAvailable(result.isAvailable);
 
      // Determine available biometry type
      if (result.biometryType === BiometryType.faceId) {
        setBiometryType('Face ID');
      } else if (result.biometryType === BiometryType.touchId) {
        setBiometryType('Touch ID');
      } else if (result.biometryType === BiometryType.fingerprint) {
        setBiometryType('Fingerprint');
      } else if (result.biometryType === BiometryType.faceAuthentication) {
        setBiometryType('Face Authentication');
      }
    } catch {
      setIsAvailable(false);
    }
  };
 
  const authenticate = async (): Promise<boolean> => {
    try {
      await BiometricAuth.authenticate({
        reason: 'Authentication is required to access your account',
        iosFallbackTitle: 'Use Passcode',
        androidTitle: 'Biometric Authentication',
        androidSubtitle: 'Confirm access to your account',
        androidConfirmationRequired: false,
      });
      return true;
    } catch (error) {
      console.error('Biometric authentication failed:', error);
      return false;
    }
  };
 
  return { isAvailable, biometryType, authenticate };
};

npm install @capacitor/preferences
npx cap sync

// src/lib/storage.ts
// Antigravity generates a type-safe implementation using TypeScript Generics
import { Preferences } from '@capacitor/preferences';
 
export class TypedStorage {
  static async set<T>(key: string, value: T): Promise<void> {
    await Preferences.set({
      key,
      value: JSON.stringify(value),
    });
  }
 
  static async get<T>(key: string): Promise<T | null> {
    const { value } = await Preferences.get({ key });
    if (value === null) return null;
 
    try {
      return JSON.parse(value) as T;
    } catch {
      return null;
    }
  }
 
  static async remove(key: string): Promise<void> {
    await Preferences.remove({ key });
  }
 
  static async clear(): Promise<void> {
    await Preferences.clear();
  }
 
  static async keys(): Promise<string[]> {
    const { keys } = await Preferences.keys();
    return keys;
  }
}
 
// Usage example
interface UserSettings {
  theme: 'light' | 'dark';
  language: 'ja' | 'en';
  notifications: boolean;
}
 
// Save
await TypedStorage.set<UserSettings>('userSettings', {
  theme: 'dark',
  language: 'en',
  notifications: true,
});
 
// Retrieve
const settings = await TypedStorage.get<UserSettings>('userSettings');
// settings?.theme === 'dark'

npm install @capacitor-community/sqlite
npx cap sync

// src/lib/database.ts
import { CapacitorSQLite, SQLiteConnection, SQLiteDBConnection } from '@capacitor-community/sqlite';
import { Capacitor } from '@capacitor/core';
 
class DatabaseService {
  private sqlite: SQLiteConnection;
  private db: SQLiteDBConnection | null = null;
 
  constructor() {
    this.sqlite = new SQLiteConnection(CapacitorSQLite);
  }
 
  async initialize(): Promise<void> {
    // Web environment requires a polyfill for IndexedDB
    if (Capacitor.getPlatform() === 'web') {
      // e.g. load and define jeep-sqlite (Web Component) per the plugin README
      await import('jeep-sqlite/loader').then((m) => m.defineCustomElements(window));
    }
 
    this.db = await this.sqlite.createConnection(
      'myapp.db',      // Database name
      false,           // No encryption
      'no-encryption', // Encryption mode
      1,               // Version
      false            // Not read-only
    );
 
    await this.db.open();
    await this.createTables();
  }
 
  private async createTables(): Promise<void> {
    if (!this.db) throw new Error('Database not initialized');
 
    const createUsersTable = `
      CREATE TABLE IF NOT EXISTS users (
        id TEXT PRIMARY KEY,
        name TEXT NOT NULL,
        email TEXT UNIQUE NOT NULL,
        created_at INTEGER NOT NULL,
        updated_at INTEGER NOT NULL
      );
    `;
 
    const createPostsTable = `
      CREATE TABLE IF NOT EXISTS posts (
        id TEXT PRIMARY KEY,
        user_id TEXT NOT NULL,
        title TEXT NOT NULL,
        content TEXT,
        created_at INTEGER NOT NULL,
        FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
      );
    `;
 
    await this.db.execute(createUsersTable);
    await this.db.execute(createPostsTable);
  }
 
  async insertUser(user: { id: string; name: string; email: string }): Promise<void> {
    if (!this.db) throw new Error('Database not initialized');
 
    const now = Date.now();
    const query = `
      INSERT OR REPLACE INTO users (id, name, email, created_at, updated_at)
      VALUES (?, ?, ?, ?, ?);
    `;
 
    await this.db.run(query, [user.id, user.name, user.email, now, now]);
  }
 
  async getUserById(id: string): Promise<{ id: string; name: string; email: string } | null> {
    if (!this.db) throw new Error('Database not initialized');
 
    const query = 'SELECT * FROM users WHERE id = ?;';
    const result = await this.db.query(query, [id]);
 
    if (result.values && result.values.length > 0) {
      return result.values[0] as { id: string; name: string; email: string };
    }
    return null;
  }
 
  async close(): Promise<void> {
    if (this.db) {
      await this.sqlite.closeConnection('myapp.db', false);
      this.db = null;
    }
  }
}
 
export const database = new DatabaseService();

// Additional optimization settings for capacitor.config.ts
// Antigravity recommends platform-specific optimal settings
const config: CapacitorConfig = {
  // ...base config...
  ios: {
    contentInset: 'automatic',
    scrollEnabled: true,
    backgroundColor: '#ffffff',
    preferredContentMode: 'mobile',
    limitsNavigationsToAppBoundDomains: true,
    webContentsDebuggingEnabled: false, // false in production
  },
  android: {
    backgroundColor: '#ffffff',
    useLegacyBridge: false,
    allowMixedContent: false,
    captureInput: true,
    webContentsDebuggingEnabled: false, // false in production
  },
};

# Create an archive in Xcode
cd ios/App
xcodebuild -workspace App.xcworkspace \
           -scheme App \
           -configuration Release \
           -archivePath App.xcarchive \
           archive
 
# Export IPA (for App Store Connect)
xcodebuild -exportArchive \
           -archivePath App.xcarchive \
           -exportOptionsPlist ExportOptions.plist \
           -exportPath ./output

<!-- ExportOptions.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>method</key>
  <string>app-store</string>
  <key>teamID</key>
  <string>YOUR_TEAM_ID</string>
  <key>uploadSymbols</key>
  <true/>
  <key>compileBitcode</key>
  <false/>
</dict>
</plist>

# Create a release build with Gradle
cd android
./gradlew bundleRelease  # AAB format (recommended)
# Or
./gradlew assembleRelease  # APK format

// Add to android/app/build.gradle
// Antigravity generates a config following security best practices
android {
    signingConfigs {
        release {
            // Do not include the keystore in version control
            // Read from environment variables or local.properties
            storeFile file(System.getenv('KEYSTORE_PATH') ?: '../keystore/release.keystore')
            storePassword System.getenv('KEYSTORE_PASSWORD') ?: ''
            keyAlias System.getenv('KEY_ALIAS') ?: 'release'
            keyPassword System.getenv('KEY_PASSWORD') ?: ''
        }
    }
 
    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled true      // Code obfuscation
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
            shrinkResources true    // Remove unused resources
        }
    }
}

# .github/workflows/mobile-release.yml
name: Mobile Release Pipeline
 
on:
  push:
    tags:
      - 'v*.*.*'
 
jobs:
  build-ios:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
 
      - name: Install dependencies
        run: npm ci
 
      - name: Build web app
        run: npm run build
 
      - name: Sync Capacitor
        run: npx cap sync ios
 
      - name: Setup Ruby & CocoaPods
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'
          bundler-cache: true
 
      - name: Install CocoaPods
        run: cd ios/App && pod install
 
      - name: Import Certificates
        env:
          P12_CERTIFICATE: ${{ secrets.P12_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
        run: |
          echo "$P12_CERTIFICATE" | base64 --decode > certificate.p12
          security create-keychain -p "" build.keychain
          security import certificate.p12 -k build.keychain -P "$P12_PASSWORD" -T /usr/bin/codesign
          security set-keychain-settings -t 3600 -u build.keychain
          security default-keychain -s build.keychain
          security unlock-keychain -p "" build.keychain
 
      - name: Build & Archive iOS
        run: |
          cd ios/App
          xcodebuild -workspace App.xcworkspace \
                     -scheme App \
                     -configuration Release \
                     -archivePath $GITHUB_WORKSPACE/App.xcarchive \
                     archive
 
      - name: Export IPA
        run: |
          xcodebuild -exportArchive \
                     -archivePath $GITHUB_WORKSPACE/App.xcarchive \
                     -exportOptionsPlist $GITHUB_WORKSPACE/ExportOptions.plist \
                     -exportPath $GITHUB_WORKSPACE/output
 
      - name: Upload to App Store Connect
        env:
          APPLE_ID: ${{ secrets.APPLE_ID }}
          APPLE_APP_PASSWORD: ${{ secrets.APPLE_APP_PASSWORD }}
        run: |
          xcrun altool --upload-app \
                       -f output/App.ipa \
                       -t ios \
                       -u "$APPLE_ID" \
                       -p "$APPLE_APP_PASSWORD"
 
  build-android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
 
      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'
 
      - name: Install dependencies
        run: npm ci
 
      - name: Build web app
        run: npm run build
 
      - name: Sync Capacitor
        run: npx cap sync android
 
      - name: Build Release AAB
        env:
          KEYSTORE_PATH: ${{ github.workspace }}/release.keystore
          KEYSTORE_PASSWORD: ${{ secrets.KEYSTORE_PASSWORD }}
          KEY_ALIAS: ${{ secrets.KEY_ALIAS }}
          KEY_PASSWORD: ${{ secrets.KEY_PASSWORD }}
        run: |
          echo "${{ secrets.KEYSTORE_BASE64 }}" | base64 --decode > release.keystore
          cd android
          ./gradlew bundleRelease
 
      - name: Upload to Google Play
        uses: r0adkll/upload-google-play@v1
        with:
          serviceAccountJsonPlainText: ${{ secrets.SERVICE_ACCOUNT_JSON }}
          packageName: com.yourcompany.myapp
          releaseFiles: android/app/build/outputs/bundle/release/*.aab
          track: internal  # internal → alpha → beta → production

// capacitor.config.ts
import { CapacitorConfig } from '@capacitor/cli';
 
const config: CapacitorConfig = {
  appId: 'com.yourcompany.myapp',
  appName: 'MyApp',
  webDir: 'out',
  plugins: {
    SplashScreen: {
      launchAutoHide: false,       // don't auto-hide
      backgroundColor: '#0b1020',  // match the web background exactly
      androidScaleType: 'CENTER_CROP',
    },
  },
};
export default config;

// src/app/layout.tsx or _app.tsx
import { Capacitor } from '@capacitor/core';
import { SplashScreen } from '@capacitor/splash-screen';
import { useEffect } from 'react';
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    if (!Capacitor.isNativePlatform()) return;
    // Call after fonts, images, and initial API requests are settled
    const t = setTimeout(() => { SplashScreen.hide({ fadeOutDuration: 200 }); }, 50);
    return () => clearTimeout(t);
  }, []);
  return <>{children}</>;
}

import { AdMob } from '@capacitor-community/admob';
import { AppTrackingTransparency } from 'capacitor-plugin-app-tracking-transparency';
 
export async function initAds() {
  // 1) Show ATT prompt first (only iOS 14.5+ shows the actual dialog)
  const att = await AppTrackingTransparency.requestPermission();
  // 2) Personalized ads only if authorized; otherwise non-personalized
  const npa = att.status !== 'authorized';  // true = non-personalized ads
  // 3) Initialize AdMob *after* the ATT result is known
  await AdMob.initialize({
    requestTrackingAuthorization: false,  // already handled above
    testingDevices: [],
    initializeForTesting: false,
  });
  // 4) Pass npa with each ad request
  await AdMob.bannerAd.show({
    adId: 'ca-app-pub-XXXXXXXXXXXXXXXX/YYYYYYYYYY',
    adSize: 'ADAPTIVE_BANNER',
    position: 'BOTTOM_CENTER',
    margin: 0,
    npa,
  } as any);
}

import { FirebaseCrashlytics } from '@capacitor-community/firebase-crashlytics';
import { Capacitor } from '@capacitor/core';
 
export function installWebErrorBridge() {
  if (!Capacitor.isNativePlatform()) return;
  const send = (message: string, stacktrace?: string) => {
    FirebaseCrashlytics.recordException({ message, stacktrace }).catch(() => {});
  };
  window.addEventListener('error', (e) => {
    send(`[JS Error] ${e.message}`, e.error?.stack);
  });
  window.addEventListener('unhandledrejection', (e) => {
    const r: any = e.reason;
    send(`[Unhandled Promise] ${r?.message ?? String(r)}`, r?.stack);
  });
}

import { Preferences } from '@capacitor/preferences';
 
const KEY = 'auth.idToken';
 
export async function persistToken(token: string) {
  await Preferences.set({ key: KEY, value: token });
  localStorage.setItem(KEY, token);  // keep parity within the same session
}
 
export async function restoreTokenOnBoot() {
  const { value } = await Preferences.get({ key: KEY });
  if (value && !localStorage.getItem(KEY)) localStorage.setItem(KEY, value);
}