Capacitor Best Practices

{
  "version": "1.0.0",
  "organization": "Capgo",
  "date": "January 2026",
  "abstract": "Comprehensive best practices guide for Capacitor app development. Covers project structure, plugin usage patterns, performance optimization, security hardening, error handling, live updates, and deployment preparation.",
  "triggers": [
    "capacitor best practice",
    "optimize capacitor",
    "capacitor security",
    "capacitor performance",
    "capacitor project structure",
    "review capacitor code"
  ],
  "references": [
    "https://capacitorjs.com/docs",
    "https://capgo.app/docs",
    "https://ionicframework.com/docs"
  ]
}


---
name: capacitor-best-practices
description: Best practices for Capacitor app development including project structure, plugin usage, performance optimization, security, and deployment. Use this skill when reviewing Capacitor code, setting up new projects, or optimizing existing apps.
---

# Capacitor Best Practices

Comprehensive guidelines for building production-ready Capacitor applications.

## When to Use This Skill

- Setting up a new Capacitor project
- Reviewing Capacitor app architecture
- Optimizing app performance
- Implementing security measures
- Preparing for app store submission

## Project Structure

### Recommended Directory Layout

```text
my-app/
├── src/                      # Web app source
├── android/                  # Android native project
├── ios/                      # iOS native project
├── capacitor.config.ts       # Capacitor configuration
├── package.json
└── tsconfig.json
```

### Configuration Best Practices

**capacitor.config.ts** (CORRECT):
```typescript
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):
```json
{
  "server": {
    "url": "http://localhost:5173",
    "cleartext": true
  }
}
```
*Never commit development server URLs to production*

## Plugin Usage

### CRITICAL: Always Use Latest Capacitor

Keep Capacitor core packages in sync:

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

### Plugin Installation Pattern

**CORRECT**:
```bash
# 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**:
```bash
# Missing sync step
npm install @capgo/capacitor-native-biometric
# App crashes because native code not linked
```

### Plugin Initialization

**CORRECT** - Check availability before use:
```typescript
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:
```typescript
// Will crash if biometrics not available
await NativeBiometric.verifyIdentity({ reason: 'Login' });
```

## Performance Optimization

### CRITICAL: Lazy Load Plugins

**CORRECT** - Dynamic imports:
```typescript
// Only load when needed
async function scanDocument() {
  const { DocumentScanner } = await import('@capgo/capacitor-document-scanner');
  return DocumentScanner.scanDocument();
}
```

**INCORRECT** - Import everyth