From capacitor-core
Guides Capacitor app development with best practices on project structure, plugin installation and usage, performance optimization, security, and deployment. Use for code reviews, new projects, or app optimization.
npx claudepluginhub cap-go/capgo-skills --plugin capacitor-coreThis skill uses the workspace's default tool permissions.
Comprehensive guidelines for building production-ready Capacitor applications.
Scans Capacitor and Ionic apps for 63+ security vulnerabilities using Capsec tool across secrets, storage, network, authentication, cryptography, and platform issues. Use for audits, CI/CD integration, and OWASP mobile checks.
Recommends official Capacitor plugins first, with Capgo and community alternatives for native iOS/Android features like camera, biometrics, geolocation, and payments. Use for plugin selection and comparisons.
Migrates web apps, PWAs, SPAs to store-ready Capacitor iOS/Android apps. Addresses thin WebView rejections, native UX, permissions, offline support, billing, testing, Capgo updates.
Share bugs, ideas, or general feedback.
Comprehensive guidelines for building production-ready Capacitor applications.
my-app/
├── src/ # Web app source
├── android/ # Android native project
├── ios/ # iOS native project
├── capacitor.config.ts # Capacitor configuration
├── package.json
└── tsconfig.json
capacitor.config.ts (CORRECT):
import type { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.company.app',
appName: 'My App',
webDir: 'dist',
server: {
// Only enable for development
...(process.env.NODE_ENV === 'development' && {
url: 'http://localhost:5173',
cleartext: true,
}),
},
plugins: {
SplashScreen: {
launchAutoHide: false,
},
},
};
export default config;
capacitor.config.json (AVOID):
{
"server": {
"url": "http://localhost:5173",
"cleartext": true
}
}
Never commit development server URLs to production
Keep Capacitor core packages in sync:
npm install @capacitor/core@latest @capacitor/cli@latest
npm install @capacitor/ios@latest @capacitor/android@latest
npx cap sync
CORRECT:
# 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 ../..
INCORRECT:
# Missing sync step
npm install @capgo/capacitor-native-biometric
# App crashes because native code not linked
CORRECT - Check availability before use:
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;
}
}
INCORRECT - No availability check:
// Will crash if biometrics not available
await NativeBiometric.verifyIdentity({ reason: 'Login' });
CORRECT - Dynamic imports:
// Only load when needed
async function scanDocument() {
const { DocumentScanner } = await import('@capgo/capacitor-document-scanner');
return DocumentScanner.scanDocument();
}
INCORRECT - Import everything at startup:
// 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
CORRECT - Use hardware acceleration:
<!-- android/app/src/main/AndroidManifest.xml -->
<application
android:hardwareAccelerated="true"
android:largeHeap="true">
<!-- ios/App/App/Info.plist -->
<key>UIViewGroupOpacity</key>
<false/>
CORRECT - Batch operations:
// Single call with batch data
await Storage.set({
key: 'userData',
value: JSON.stringify({ name, email, preferences }),
});
INCORRECT - Multiple bridge calls:
// 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) });
CORRECT:
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,
});
INCORRECT:
const photo = await Camera.getPhoto({
quality: 100,
resultType: CameraResultType.Base64, // Memory intensive
// No size limits
});
CORRECT - Use secure storage for sensitive data:
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',
});
INCORRECT - Plain storage:
import { Preferences } from '@capacitor/preferences';
// NEVER store sensitive data in plain preferences
await Preferences.set({
key: 'password',
value: 'secret', // Stored in plain text!
});
For production apps handling sensitive data:
// 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
}
}
CORRECT:
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;
}
}
INCORRECT:
// 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);
});
CORRECT - Background download, apply on restart:
// Download silently
const bundle = await CapacitorUpdater.download({ url, version });
// User continues using app...
// Apply when they close/reopen
await CapacitorUpdater.set(bundle);
INCORRECT - Interrupt user:
// Don't force reload while user is active
const bundle = await CapacitorUpdater.download({ url, version });
await CapacitorUpdater.reload(); // Disrupts user
Modern approach - prefer SPM over CocoaPods:
# 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
}