capawesome-cloud

What this skill does

# Capawesome Cloud

Set up and manage native builds, live updates, and app store publishing for Capacitor and Cordova apps using Capawesome Cloud.

## Prerequisites

1. A [Capawesome Cloud](https://console.cloud.capawesome.io) account and organization.
2. A **Capacitor 6/7/8** or **Cordova** app. Notes:
   - **Live Updates**: supported on both Capacitor and Cordova.
   - **Native Builds**: supported on Capacitor, Cordova, and native iOS/Android projects.
   - **App Store Publishing**: framework-agnostic — works with any native build produced by Native Builds.
3. Node.js and npm installed.
4. For **Native Builds**: The app must be in a Git repository (GitHub, GitLab, Bitbucket, or Azure DevOps).
5. For **Apple App Store Publishing**: An active [Apple Developer Program](https://developer.apple.com/programs/) membership and an app created in [App Store Connect](https://appstoreconnect.apple.com).
6. For **Google Play Store Publishing**: A [Google Play Developer](https://play.google.com/console) account and an app created in Google Play Console with at least one version uploaded manually.

## General Rules

Before running any `@capawesome/cli` command for the first time, run it with the `--help` flag to review all available options.

## Procedures

### Step 1: Authenticate with Capawesome Cloud

```bash
npx @capawesome/cli login
```

For CI/CD, use token-based auth:

```bash
npx @capawesome/cli login --token <token>
```

### Step 2: Create an App in Capawesome Cloud

Skip if the user already has an app ID.

```bash
npx @capawesome/cli apps:create
```

The CLI prompts for organization and app name, then outputs the **app ID** (UUID). Save for subsequent steps.

The app type defaults to `capacitor`. For a Cordova app, pass `--type cordova` (allowed values: `android`, `capacitor`, `cordova`, `ios`):

```bash
npx @capawesome/cli apps:create --type cordova
```

### Step 3: Identify Required Feature(s)

Ask the user which Capawesome Cloud feature(s) to set up:

1. **Native Builds** — Build iOS and Android apps in the cloud.
2. **Live Updates** — Push OTA web updates to deployed apps.
3. **App Store Publishing** — Automate submissions to Apple App Store or Google Play Store.

The user may select one or more features. Proceed to the corresponding sections below.

### Native Builds

Read `references/native-builds.md` for the full native builds setup and usage procedure. This covers:

- Connecting a Git repository
- Uploading signing certificates (Android keystores, iOS .p12 + provisioning profiles)
- Configuring environments and secrets
- Configuring build settings (monorepos, custom build commands)
- Triggering builds
- Monitoring and downloading build artifacts
- Configuring native configuration overwriting with Trapeze
- Setting up CI/CD pipelines

### Live Updates

Read `references/live-updates.md` first — it detects the framework (Capacitor or Cordova) and routes to the matching procedure (`live-updates-capacitor.md` or `live-updates-cordova.md`). Both procedures cover:

- Installing the Live Update plugin (`@capawesome/capacitor-live-update` for Capacitor, `@capawesome/cordova-live-update` for Cordova)
- Configuring the plugin (Capacitor config or Cordova `config.xml` preferences)
- Adding rollback protection
- Adding update logic (Always Latest, Manual Sync, Force Update)
- Configuring iOS Privacy Manifest
- Configuring version handling (versioned channels, versioned bundles)
- Testing the setup

### App Store Publishing

Read `references/app-store-publishing.md` for the full app store publishing setup and usage procedure. This covers:

- Creating Apple App Store destinations (API Key or Apple ID auth)
- Creating Google Play Store destinations
- Deploying builds to destinations
- Building and deploying in one step

## Error Handling

### Native Builds

- `invalid source release: 21` → Set `JAVA_VERSION` env var to `17` or `21`. Read `references/build-troubleshooting.md`.
- `JavaScript heap out of memory` → Set `NODE_OPTIONS` env var to `--max-old-space-size=4096`. Read `references/build-troubleshooting.md`.
- Authentication errors → Re-run `npx @capawesome/cli login`. For CI/CD, verify the token.
- Missing signing certificate → Upload via `apps:certificates:create`. Read `references/certificates-android.md` or `references/certificates-ios.md`.
- Expired provisioning profile → Regenerate in Apple Developer Portal and re-upload. Read `references/certificates-ios.md`.
- Web build step fails → Ensure `package.json` has `capawesome:build` or `build` script. Read `references/build-configuration.md`.

### Live Updates

- `npx cap sync` fails (Capacitor) → Verify plugin version matches Capacitor version in `package.json`.
- Bundles not applied → Ensure `ready()` is called before `readyTimeout`/`READY_TIMEOUT` expires.
- App reverts to default bundle after restart → `ready()` likely not called. Add it early in app init (in Cordova, inside the `deviceready` listener).
- Upload auth errors → Re-run `npx @capawesome/cli login`.
- Updates not detected with `autoUpdateStrategy: "background"` / `AUTO_UPDATE_STRATEGY=background` → Updates only checked if last check was >15 min ago. Force-close and restart.
- **Cordova:** preference changes have no effect → Cordova reads preferences only on platform add. Run `cordova platform rm <platform>` then `cordova platform add <platform>`.
- **Cordova:** updates never apply / WebView errors → The plugin requires the default custom WebView scheme. Ensure `config.xml` does not set `Scheme=file` or `AndroidInsecureFileModeEnabled=true`.
- Read `references/live-update-plugin-api.md` for the full SDK API reference.
- Read `references/live-update-faq.md` for compliance, billing, and limitations.

### App Store Publishing

- Authentication errors → Re-run `npx @capawesome/cli login`.
- Destination creation fails → Verify credentials. Read `references/apple-app-store-credentials.md` or `references/google-play-store-credentials.md`.
- iOS build not appearing in TestFlight → Build processing may take time. Common causes: build number not incremented, missing Privacy Descriptions in `Info.plist`, insufficient permissions.
- Google Play deployment fails → Ensure first version was uploaded manually. Verify service account has Release permissions.
- Deployment timeout → Use `--detached` flag and check logs with `apps:deployments:logs`.
- `apps:deployments:create` fails with "build not found" → Ensure the build completed successfully.
- Cancel a stuck deployment → `npx @capawesome/cli apps:deployments:cancel --app-id <APP_ID> --deployment-id <DEPLOYMENT_ID>`.

## Related Skills

- **`capacitor-app-development`** — For general Capacitor development topics, CI/CD patterns, and troubleshooting.
- **`capawesome-cli`** — For the full Capawesome CLI command reference, project configuration, and CI/CD integration details.
- **`capacitor-plugins`** — For installing and configuring Capacitor plugins, including the `@capawesome/capacitor-live-update` plugin.
- **`ionic-appflow-migration`** — For migrating existing Ionic Appflow projects to Capawesome Cloud.
- **`capacitor-in-app-purchases`** — For setting up in-app purchases and subscriptions before publishing to app stores.