capacitor-app-spm-migration

What this skill does

# Capacitor App: CocoaPods → SPM Migration

Migrate an existing Capacitor app project's iOS dependency management from CocoaPods to Swift Package Manager (SPM). The migration is destructive — the existing `ios/` folder is deleted and re-scaffolded, then user-authored files are restored from a temporary backup.

## Prerequisites

| Requirement | Version |
| ----------- | ------- |
| Capacitor   | 6+      |
| Node.js     | 18+     |
| Xcode       | 15+     |
| CocoaPods   | installed (only used for verification before deletion) |

The project must be a Capacitor **app** (not a plugin) and must currently use CocoaPods (`ios/App/Podfile` exists).

## Procedures

### Step 1: Verify Project State

1. Verify the project is a Capacitor **app**, not a plugin. Confirm `package.json` lists `@capacitor/ios` in `dependencies` and the project root contains a `capacitor.config.*` file.
2. Verify the project currently uses CocoaPods. The file `ios/App/Podfile` must exist. If it does not exist and `ios/App/CapApp-SPM/Package.swift` exists, the project is already on SPM — abort and inform the user.
3. Read `@capacitor/core` version from `package.json` (`dependencies` or `devDependencies`). Confirm the major version is **6 or higher**. If lower, abort and direct the user to the `capacitor-app-upgrades` skill first.
4. Verify the working tree is clean. Run `git status --porcelain` — if the output is non-empty, instruct the user to commit or stash changes before proceeding. The migration is destructive and must be reversible via `git checkout`.

### Step 2: Inventory Installed Capacitor Plugins

Read `package.json` and record every installed Capacitor plugin under `dependencies`. Match these prefixes:

- `@capacitor/*` (official plugins)
- `@capawesome/*` and `@capawesome-team/*`
- `@capacitor-community/*`
- `@capacitor-firebase/*`
- `@capacitor-mlkit/*`
- `@revenuecat/*`
- Any other package with `"capacitor"` in its `package.json` `keywords` array

Record each plugin's package name and installed version. This list is used in Step 8 to verify all plugins resolve under SPM after re-sync.

### Step 3: Identify Files to Preserve

Build a checklist of files in `ios/` that contain user-authored content and must survive the re-scaffold. For each path below, check whether the file exists. Record only the paths that exist.

| Path (relative to project root) | Purpose |
| ------------------------------- | ------- |
| `ios/App/App/Info.plist` | App permissions, URL schemes, bundle config, custom keys |
| `ios/App/App/AppDelegate.swift` | Custom app lifecycle code |
| `ios/App/App/SceneDelegate.swift` | Custom scene lifecycle code (if present) |
| `ios/App/App/Assets.xcassets/` | App icon, splash assets, color sets |
| `ios/App/App/Base.lproj/` | LaunchScreen and Main storyboards |
| `ios/App/App/App.entitlements` | Push, App Groups, Associated Domains, Keychain Sharing |
| `ios/App/App/GoogleService-Info.plist` | Firebase configuration (if Firebase plugins are installed) |
| `ios/App/App/*.xcconfig` | Build configuration overrides |
| `ios/App/App.xcodeproj/project.pbxproj` | Source for extracting signing values in Step 5 |

Additionally, scan `ios/App/App/` for **any other `.swift` files** beyond `AppDelegate.swift` and `SceneDelegate.swift`. These are user-authored Swift sources (e.g., custom Notification Service Extensions, custom view controllers) and must also be preserved.

If the project contains a Notification Service Extension or other Xcode targets under `ios/App/` (e.g., `ios/App/NotificationService/`), record those directories as well.

### Step 4: Back Up Preserved Files

1. Create the backup directory:

   ```bash
   mkdir -p .spm-migration-backup
   ```

2. Add `.spm-migration-backup/` to `.gitignore` to prevent accidental commits:

   ```diff
    # iOS files
   +.spm-migration-backup/
   ```

3. Copy each file recorded in Step 3 into `.spm-migration-backup/`, preserving the relative path. For example:

   ```bash
   mkdir -p .spm-migration-backup/ios/App/App
   cp ios/App/App/Info.plist .spm-migration-backup/ios/App/App/Info.plist
   cp ios/App/App/AppDelegate.swift .spm-migration-backup/ios/App/App/AppDelegate.swift
   cp -R ios/App/App/Assets.xcassets .spm-migration-backup/ios/App/App/Assets.xcassets
   cp -R ios/App/App/Base.lproj .spm-migration-backup/ios/App/App/Base.lproj
   ```

   Repeat for every file/directory identified in Step 3. Use `cp -R` for directories.

4. Always copy the full `ios/App/App.xcodeproj/project.pbxproj` to `.spm-migration-backup/ios/App/App.xcodeproj/project.pbxproj`, even though the file itself will not be restored. Step 5 reads it to extract signing values, and Step 11 may reference it for capability reconfiguration.

### Step 5: Extract Signing & Bundle Configuration

Read `.spm-migration-backup/ios/App/App.xcodeproj/project.pbxproj` and extract the values of the following build settings from the `App` target's `XCBuildConfiguration` blocks (both `Debug` and `Release`). Search for each key and record the assigned value:

- `PRODUCT_BUNDLE_IDENTIFIER`
- `DEVELOPMENT_TEAM`
- `CODE_SIGN_STYLE` (e.g., `Automatic` or `Manual`)
- `PROVISIONING_PROFILE_SPECIFIER` (only if `CODE_SIGN_STYLE = Manual`)
- `CODE_SIGN_IDENTITY` (only if `CODE_SIGN_STYLE = Manual`)
- `MARKETING_VERSION`
- `CURRENT_PROJECT_VERSION`
- `IPHONEOS_DEPLOYMENT_TARGET`
- `SWIFT_VERSION`

Also record the list of capabilities by reading `.spm-migration-backup/ios/App/App/App.entitlements` (if present). Note all top-level keys (e.g., `aps-environment`, `com.apple.security.application-groups`, `com.apple.developer.associated-domains`).

Save the extracted values in memory for use in Step 9.

### Step 6: Delete the `ios/` Folder

Confirm with the user that the working tree is committed (re-run `git status --porcelain` if necessary) and that `.spm-migration-backup/` contains every file from Step 3. Then run:

```bash
rm -rf ios
```

### Step 7: Re-scaffold iOS with SPM

Run:

```bash
npx cap add ios --packagemanager SPM
```

This creates a new `ios/` directory with the SPM-based scaffold. The new structure includes `ios/App/CapApp-SPM/Package.swift` instead of `ios/App/Podfile`.

### Step 8: Restore Preserved Files

Copy each backed-up file from `.spm-migration-backup/` back to its original path under `ios/`, **overwriting** the scaffolded defaults. For example:

```bash
cp .spm-migration-backup/ios/App/App/Info.plist ios/App/App/Info.plist
cp .spm-migration-backup/ios/App/App/AppDelegate.swift ios/App/App/AppDelegate.swift
cp -R .spm-migration-backup/ios/App/App/Assets.xcassets ios/App/App/Assets.xcassets
cp -R .spm-migration-backup/ios/App/App/Base.lproj ios/App/App/Base.lproj
```

Repeat for every file/directory backed up in Step 4, **except** `ios/App/App.xcodeproj/project.pbxproj` — that file is **not** restored. The new `project.pbxproj` is required for SPM integration; signing values from the old one are reapplied via Step 9.

If any preserved file did not exist in the new scaffold (e.g., `App.entitlements`, `GoogleService-Info.plist`, custom Swift files), the file must additionally be added to the Xcode project membership in Step 10.

### Step 9: Reapply Signing & Bundle Configuration

Edit the new `ios/App/App.xcodeproj/project.pbxproj` and reapply the values extracted in Step 5. For each setting, find every occurrence in the `App` target's `XCBuildConfiguration` blocks and replace the scaffolded value with the recorded value.

Apply this diff pattern for each setting (example for `PRODUCT_BUNDLE_IDENTIFIER`):

```diff
-				PRODUCT_BUNDLE_IDENTIFIER = com.example.app;
+				PRODUCT_BUNDLE_IDENTIFIER = <RECORDED_BUNDLE_ID>;
```

Settings to reapply (use `replace_all` semantics — update **all** occurrences across `Debug` and `Release` configurations):

- `PRODUCT_BUNDLE_IDENTIFIER`
- `DEVELOPMENT_TEAM`
- `CODE_SIGN_STYLE`
- `PROVISIONING_PROFILE_SPECIFIER` (only if manual signing)
- `CODE_SIGN_IDENTITY` (only if manual signing)
- `MARKETING_VERSION`
- `CURRENT_PROJEC