docs: add Capacitor 9 app upgrade guide - #589
Conversation
Covers app-level changes only (Cordova-optional, CLI, Android/iOS breaking changes, upgrade steps, plugin summary). Deprecated-API removal tables and the plugin-author guide are tracked separately (RMET-4728, RMET-5321). RMET-5320
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
OS-pedrogustavobilro
left a comment
OS-pedrogustavobilro
left a comment
There was a problem hiding this comment.
Left a few comments. If some of them are better to address offline, let me know!
| - On Android, the generated `settings.gradle` and app `build.gradle` no longer include the `capacitor-cordova-android` / `capacitor-cordova-android-plugins` modules. | ||
| - On iOS, `CapacitorCordova` is no longer added to your `Podfile` or `Package.swift`. | ||
|
|
||
| There is currently no configuration option to force-include the Cordova runtime when no Cordova plugin is present. If your app's native code (or a plugin you maintain) directly references symbols from Capacitor's Cordova compatibility layer — for example `com.getcapacitor.cordova.CordovaPlugin` on Android, or anything from the `CapacitorCordova` pod/product on iOS — without having an actual Cordova plugin installed, those references will fail to resolve after upgrading. Add a Cordova plugin dependency (even a trivial one) if you need the layer present, or remove the direct reference. |
There was a problem hiding this comment.
This paragraph may change soon with this task but I suppose for now it's true. Just something to keep in mind, we may want to revise this doc in the near future after this PR is merged.
| AGP 9 no longer ships `proguard-android.txt` — any `build.gradle` that still references it fails at Gradle configuration time, even with `minifyEnabled false`: | ||
|
|
||
| ```groovy | ||
| // Before — hard build error on AGP 9 | ||
| proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro' | ||
| // After | ||
| proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro' | ||
| ``` | ||
|
|
||
| `androidx.core:core` 1.19.0 merges every extension function previously shipped in `core-ktx` into `core` itself, turning `core-ktx` into an empty compatibility artifact. If your app (or an old/community plugin it depends on) still explicitly pins `core-ktx` to a version older than `1.19.0`, you may hit a duplicate class error at build time; remove the explicit `core-ktx` version override. | ||
|
|
||
| AGP 9 also bundles the Kotlin Gradle Plugin natively and removes the `jcenter()` repository helper entirely. These are unlikely to affect your app directly, but can break the build if you (or a legacy/community plugin) still apply Kotlin standalone or reference `jcenter()` — see [Update Kotlin and remove jcenter()](#update-kotlin-and-remove-jcenter) below. |
There was a problem hiding this comment.
Trying to think if these changes would go on @capacitor/android or in separate sections. You mention the proguard and Kotlin / jcenter in their own sections, so this feels like duplicated information here.
The core isn't mentioned below I guess, but could be moved below to its own subsection perhaps?
And here at most we would like to those sections?
Let me know if that makes sense.
There was a problem hiding this comment.
@andredestro I'm unsure if the update structure from your latest commit is still "the best it can be". When I look at https://capacitorjs.com/docs/updating/8-0 that structure makes more sense to me where it lists:
- "Breaking changes in @capacitor/android" - which are changes in the platform that are not covered by CLI migration; so in this case things like minSdk and proguard would not be in that category, and they are not breaking changes introduced by capacitor android
- "Breaking changes in @capacitor/ios" - similarily to Android, things like deployment target and
@mainreplacing@UIApplicationMainare covered by cap migrate, and they are not breaking changes introduced by capacitor ios.
If you disagree or think the current structure is better, do let me know!
There was a problem hiding this comment.
Agreed, that structure makes more sense. Pushed a commit that trims "Breaking changes in @capacitor/android" and "@capacitor/ios" down to what cap migrate doesn't already fix (minSdk/compileSdk, the proguard rename, deployment target, and @main all moved out, they're fully covered by the manual steps below). Kept core-ktx and the standalone Kotlin/jcenter mentions there since those aren't automated.
- Move "Using the CLI to Migrate" above the breaking-changes sections that cap migrate automates (Android/iOS), so readers try it first - Trim duplicated proguard/kotlin/jcenter details from the @capacitor/android summary, add a dedicated core-ktx-to-core section - Note npm 11 ships with Node 24 (vs npm 10 with Node 22) - Use the exact CocoaPods Trunk read-only date and link to the SPM guide - Document removing targetSdkVersion from the app's build.gradle - Fix the Kotlin removal example to start from 2.2.20, not 1.9.10 - Fill in and alphabetize per-plugin variable bumps (Barcode Scanner, Camera, Geolocation, InAppBrowser) instead of vague placeholders Addresses review comments from @OS-pedrogustavobilro on PR #589.
Per PR feedback: "Breaking changes in @capacitor/X" should only list what cap migrate doesn't already fix. Removes minSdk/compileSdk and the proguard rename from the Android section (fully covered by "Update Android Project Variables" / "Rename the default ProGuard file" below), and removes the deployment target / @main mentions from the iOS section (covered by "Raise iOS Deployment Target" and the new "Replace @UIApplicationMain with @main" step). Also trims the targetSdkVersion removal note down to a single sentence.
2 participants
Description
Adds
docs/main/updating/9-0.md, the "Updating to 9.0" app upgrade guide, and registers it in the Upgrade Guides sidebar (sidebars.js).Covers app-level changes only:
@capacitor/cli(--urlreplacing the separate live-reload flags)@capacitor/android(minSdk 26, compileSdk/targetSdk 37, AGP 9.2.1 / Gradle 9.5.1, theproguard-android.txtrename,androidx.core1.19 /core-ktx, removing standalone Kotlin plugin references,jcenter()removal)@capacitor/ios(deployment target 16.0,@mainreplacing@UIApplicationMain, a pointer to the 8.5 guide for UIScene if updating from 8.4 or earlier)Using the CLI to Migrate, and the manual iOS/Android upgrade steps (Xcode, Android Studio,variables.gradle, Gradle wrapper, google-services)Change Type
Rationale / Problems Fixed
Capacitor 9 needs an "Updating to 9.0" guide before GA so app developers upgrading from 8.x have a single place documenting breaking changes and migration steps, and so Capacitor CLI and other components can link to it.
Internal Jira reference: https://outsystemsrd.atlassian.net/browse/RMET-5320
Tests or Reproductions
Content was cross-checked against the actual merged PRs in
ionic-team/capacitorandionic-team/capacitor-plugins(and sibling plugin repos) that introduce each breaking change, plus the currentnextbranch state of the Android/iOS templates (variables.gradle,app/build.gradle,Podfile, etc.) to confirm the exact version numbers. Verifiednpm run build(Docusaurus) succeeds and the new page renders at/next/updating/9-0/with no broken links.Note: Capacitor 9 hasn't reached GA yet, so the guide's install instructions point at the
nextdist-tag (@capacitor/cli@next) rather than@latest.Screenshots / Media
N/A
Platforms Affected