native-update/docs/guides/migration-from-codepush.md

Foundation package for building a comprehensive update system for Capacitor apps. Provides architecture and interfaces but requires backend implementation.

# Migration Guide: From CodePush to Capacitor Native Update

This guide helps you migrate from Microsoft CodePush to Capacitor Native Update.

## Key Differences

### Architecture
- **CodePush**: Centralized Microsoft-hosted service
- **Capacitor Native Update**: Self-hosted solution (you control the infrastructure)

### Features
- **CodePush**: OTA updates only
- **Capacitor Native Update**: OTA + native app updates + app reviews

### Security
- **CodePush**: Microsoft-managed security
- **Capacitor Native Update**: Your own security implementation

## Migration Steps

### 1. Backend Setup

First, you need to set up your own update server:

```bash
# Create a backend using our templates
npx native-update backend create express --with-admin
# or for Firebase
npx native-update backend create firebase --with-monitoring

cd native-update-backend
npm install
npm run dev
```

### 2. Update Your App Code

Replace CodePush imports:

```typescript
// Old (CodePush)
import codePush from 'react-native-code-push';

// New (Capacitor Native Update)
import { NativeUpdate } from 'native-update';
```

### 3. Configure Plugin

Replace CodePush configuration:

```typescript
// Old (CodePush)
const codePushOptions = {
  checkFrequency: codePush.CheckFrequency.ON_APP_START,
  deploymentKey: 'YOUR_DEPLOYMENT_KEY',
};

// New (Capacitor Native Update)
await NativeUpdate.configure({
  serverUrl: 'https://your-update-server.com',
  channel: 'production',
  autoCheck: true,
  publicKey: 'YOUR_PUBLIC_KEY',
});
```

### 4. Update Check Logic

Replace update checking:

```typescript
// Old (CodePush)
codePush.sync({
  updateDialog: true,
  installMode: codePush.InstallMode.IMMEDIATE,
});

// New (Capacitor Native Update)
const result = await NativeUpdate.sync({
  installMode: 'IMMEDIATE'
});
// Sync handles check, download, and apply automatically
```

### 5. Bundle Creation

Replace release process:

```bash
# Old (CodePush)
code-push release-react MyApp ios -d Production

# New (Capacitor Native Update)
npx native-update bundle create ./www
npx native-update bundle sign bundle.zip --key private-key.pem
# Upload to your server
```

## Feature Mapping

| CodePush Feature | Capacitor Native Update |
|-----------------|------------------------|
| sync() | sync() |
| getUpdateMetadata() | current() |
| notifyAppReady() | notifyAppReady() |
| restartApp() | reload() |
| clearUpdates() | reset() |

## Migration Checklist

- [ ] Set up update server infrastructure
- [ ] Generate RSA key pair for signing
- [ ] Update app dependencies
- [ ] Replace CodePush API calls
- [ ] Update CI/CD pipeline
- [ ] Test update flow
- [ ] Implement rollback strategy
- [ ] Add monitoring

## Benefits After Migration

1. **Full Control**: Own your update infrastructure
2. **No Vendor Lock-in**: Not dependent on Microsoft
3. **Additional Features**: Native updates and app reviews
4. **Custom Analytics**: Implement your own tracking
5. **Flexible Deployment**: Use any CDN or server

## Common Issues

### Issue: Updates Not Downloading
- Check server URL is HTTPS
- Verify CORS configuration
- Ensure bundle is signed correctly

### Issue: Signature Verification Failed
- Verify public key matches private key
- Check bundle hasn't been modified
- Ensure base64 encoding is correct

## Need Help?

- See [Testing Guide](../guides/testing-guide.md)
- Check [Server Requirements](../server-requirements.md)
- Review [Security Best Practices](./security-best-practices.md)