capacitor-best-practices

{
  "server": {
    "url": "http://localhost:5173",
    "cleartext": true
  }
}

npm install @capacitor/core@latest @capacitor/cli@latest
npm install @capacitor/ios@latest @capacitor/android@latest
npx cap sync

# 1. Install the package
npm install @capgo/capacitor-native-biometric
 
# 2. Sync native projects
npx cap sync
 
# 3. For iOS: Install pods (or use SPM)
cd ios/App && pod install && cd ../..

# Missing sync step
npm install @capgo/capacitor-native-biometric
# App crashes because native code not linked

import { NativeBiometric, BiometryType } from '@capgo/capacitor-native-biometric';
 
async function authenticate() {
  const { isAvailable, biometryType } = await NativeBiometric.isAvailable();
 
  if (!isAvailable) {
    // Fallback to password
    return authenticateWithPassword();
  }
 
  try {
    await NativeBiometric.verifyIdentity({
      reason: 'Authenticate to access your account',
      title: 'Biometric Login',
    });
    return true;
  } catch (error) {
    // User cancelled or biometric failed
    return false;
  }
}

// Will crash if biometrics not available
await NativeBiometric.verifyIdentity({ reason: 'Login' });

// Only load when needed
async function scanDocument() {
  const { DocumentScanner } = await import('@capgo/capacitor-document-scanner');
  return DocumentScanner.scanDocument();
}

// Increases initial bundle size
import { DocumentScanner } from '@capgo/capacitor-document-scanner';
import { NativeBiometric } from '@capgo/capacitor-native-biometric';
import { Camera } from '@capacitor/camera';
// ... 20 more plugins

<!-- android/app/src/main/AndroidManifest.xml -->
<application
    android:hardwareAccelerated="true"
    android:largeHeap="true">

<!-- ios/App/App/Info.plist -->
<key>UIViewGroupOpacity</key>
<false/>

// Single call with batch data
await Storage.set({
  key: 'userData',
  value: JSON.stringify({ name, email, preferences }),
});

// Each call crosses the JS-native bridge
await Storage.set({ key: 'name', value: name });
await Storage.set({ key: 'email', value: email });
await Storage.set({ key: 'preferences', value: JSON.stringify(preferences) });

import { Camera, CameraResultType } from '@capacitor/camera';
 
const photo = await Camera.getPhoto({
  quality: 80,           // Not 100
  width: 1024,           // Reasonable max
  resultType: CameraResultType.Uri,  // Not Base64 for large images
  correctOrientation: true,
});

const photo = await Camera.getPhoto({
  quality: 100,
  resultType: CameraResultType.Base64,  // Memory intensive
  // No size limits
});

import { NativeBiometric } from '@capgo/capacitor-native-biometric';
 
// Store credentials securely
await NativeBiometric.setCredentials({
  username: 'user@example.com',
  password: 'secret',
  server: 'api.myapp.com',
});
 
// Retrieve with biometric verification
const credentials = await NativeBiometric.getCredentials({
  server: 'api.myapp.com',
});

import { Preferences } from '@capacitor/preferences';
 
// NEVER store sensitive data in plain preferences
await Preferences.set({
  key: 'password',
  value: 'secret',  // Stored in plain text!
});

// capacitor.config.ts
const config: CapacitorConfig = {
  plugins: {
    CapacitorHttp: {
      enabled: true,
    },
  },
  server: {
    // Disable cleartext in production
    cleartext: false,
  },
};

import { IsRoot } from '@capgo/capacitor-is-root';
 
async function checkDeviceSecurity() {
  const { isRooted } = await IsRoot.isRooted();
 
  if (isRooted) {
    // Show warning or restrict functionality
    showSecurityWarning('Device appears to be rooted/jailbroken');
  }
}

import { AppTrackingTransparency } from '@capgo/capacitor-app-tracking-transparency';
 
async function requestTracking() {
  const { status } = await AppTrackingTransparency.requestPermission();
 
  if (status === 'authorized') {
    // Enable analytics
  }
}

import { Camera, CameraResultType } from '@capacitor/camera';
 
async function takePhoto() {
  try {
    const image = await Camera.getPhoto({
      quality: 90,
      resultType: CameraResultType.Uri,
    });
    return image;
  } catch (error) {
    if (error.message === 'User cancelled photos app') {
      // User cancelled, not an error
      return null;
    }
    if (error.message.includes('permission')) {
      // Permission denied
      showPermissionDialog();
      return null;
    }
    // Unexpected error
    console.error('Camera error:', error);
    throw error;
  }
}

// No error handling
const image = await Camera.getPhoto({ quality: 90 });

import { CapacitorUpdater } from '@capgo/capacitor-updater';
 
// Notify when app is ready
CapacitorUpdater.notifyAppReady();
 
// Listen for updates
CapacitorUpdater.addListener('updateAvailable', async (update) => {
  // Download in background
  const bundle = await CapacitorUpdater.download({
    url: update.url,
    version: update.version,
  });
 
  // Apply on next app start
  await CapacitorUpdater.set(bundle);
});

// Download silently
const bundle = await CapacitorUpdater.download({ url, version });
 
// User continues using app...
 
// Apply when they close/reopen
await CapacitorUpdater.set(bundle);

// Don't force reload while user is active
const bundle = await CapacitorUpdater.download({ url, version });
await CapacitorUpdater.reload();  // Disrupts user

# Podfile - Remove plugin pods, use SPM instead
target 'App' do
  capacitor_pods
  # Plugin dependencies via SPM in Xcode
end

// android/app/build.gradle
android {
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 34
    }
 
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

// Mock for web testing
jest.mock('@capgo/capacitor-native-biometric', () => ({
  NativeBiometric: {
    isAvailable: jest.fn().mockResolvedValue({
      isAvailable: true,
      biometryType: 'touchId',
    }),
    verifyIdentity: jest.fn().mockResolvedValue({}),
  },
}));

import { Capacitor } from '@capacitor/core';
 
if (Capacitor.isNativePlatform()) {
  // Native-specific code
} else {
  // Web fallback
}
 
// Or check specific platform
if (Capacitor.getPlatform() === 'ios') {
  // iOS-specific code
}