From c6850e80bebb837ad88dfb68d3a97c611ceca254 Mon Sep 17 00:00:00 2001 From: jesswrd Date: Mon, 6 Apr 2026 14:25:41 -0700 Subject: [PATCH 01/26] looks good --- .../breaking-changes/migrate-to-agp-9.md | 133 +++++++++++++----- 1 file changed, 98 insertions(+), 35 deletions(-) diff --git a/src/content/release/breaking-changes/migrate-to-agp-9.md b/src/content/release/breaking-changes/migrate-to-agp-9.md index 6fefa6b816..1e8b804df0 100644 --- a/src/content/release/breaking-changes/migrate-to-agp-9.md +++ b/src/content/release/breaking-changes/migrate-to-agp-9.md @@ -5,16 +5,6 @@ description: >- to build apps with Android Gradle Plugin 9.0.0+. --- -:::warning -**Current status:** Please **do not** update your -Flutter app for Android to AGP 9. Flutter apps using plugins -are currently incompatible with AGP 9: [Issue #181383][]. -This support is paused while the Flutter team audits -the migration for backwards compatibility with older versions of AGP. - -If you would still like to migrate to AGP 9, follow the migration guide below. -::: - ## Summary To build a Flutter app for Android, the Android Gradle Plugin (AGP) @@ -28,11 +18,11 @@ You must migrate from `kotlin-android` to built-in Kotlin. Second, AGP 9+ will only use the new AGP DSL interfaces. This means any old DSL types will not be properly read. The Flutter team is working on migrating old DSL types -to use the new DSL: [Issue #180137][]. In the meantime, -you can set a Gradle property flag to use the old DSL. +to use the new DSL: [Issue #180137][]. -In a future Flutter release, support will be added for applying AGP 9+. -For now, all projects must be migrated manually. +Support has been added to upgrade to AGP 9+. All projects, +including apps and plugins must manually migrate to built-in Kotlin. +In a future flutter version, support for applying KGP will be removed. To learn more about Android Gradle Plugin, see the [Android Gradle Plugin docs][AGP block]. @@ -44,6 +34,9 @@ an AGP version created before 9.0.0 to an AGP version 9.0.0+. You should also use the minimum compatible dependency versions listed in the [Android Gradle Plugin docs][AGP block]. +This guide provides migration steps for Flutter Android apps, +Flutter plugins, and add-to-app android host apps. + ### Update the Gradle file If your app doesn't apply @@ -51,19 +44,22 @@ the `kotlin-android` plugin (also called Kotlin Gradle Plugin), then skip to the next step. First, find the `kotlin-android` plugin, likely located -in the `plugins` block of the `/android/build.gradle` +in the `plugins` block or the legacy `apply()` method +of the `/android/build.gradle` or `/android/build.gradle.kts` file. As an example, consider the `build.gradle.kts` file from a Flutter app created before this change: **Before**: + + + ```kotlin plugins { id("com.android.application") id("kotlin-android") - // The Flutter Gradle Plugin must be applied after the Android and Kotlin Gradle plugins. - id("dev.flutter.flutter-gradle-plugin") + // ... } android { @@ -83,8 +79,22 @@ Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: plugins { id("com.android.application") - id("kotlin-android") - // The Flutter Gradle Plugin must be applied after the Android and Kotlin Gradle plugins. - id("dev.flutter.flutter-gradle-plugin") + // ... + } + + android { + // ... +- kotlinOptions { +- jvmTarget = JavaVersion.VERSION_17.toString() +- } + // ... + } +``` +```groovy diff + plugins { + apply plugin:'com.android.application' +- apply plugin: 'kotlin-android' + // ... } android { @@ -113,16 +123,33 @@ Here is how the file will likely end up: ```kotlin plugins { id("com.android.application") - // The Flutter Gradle Plugin must be applied after the Android and Kotlin Gradle plugins. - id("dev.flutter.flutter-gradle-plugin") + // ... } android { // ... - kotlin { - compilerOptions { - jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 - } +} + +kotlin { + compilerOptions { + jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 + } +} + +// ... +``` + + + + +```groovy +apply plugin:'com.android.application' +apply plugin: 'kotlin-android' + +android { + // ... + kotlinOptions { + jvmTarget = JavaVersion.VERSION_17.toString() } // ... } @@ -130,22 +157,58 @@ android { // ... ``` -### Set the Gradle property flag +Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: -Next, to use the old AGP DSL, set the Gradle property flag -`android.newDsl` to `false` in -your app's `/android/gradle.properties` file. +```groovy diff + apply plugin:'com.android.application' +- apply plugin: 'kotlin-android' -```properties diff - org.gradle.jvmargs=-Xmx8G -XX:MaxMetaspaceSize=4G -XX:ReservedCodeCacheSize=512m -XX:+HeapDumpOnOutOfMemoryError - android.useAndroidX=true -+ android.newDsl=false + android { + // ... +- kotlinOptions { +- jvmTarget = JavaVersion.VERSION_17.toString() +- } + // ... + } +``` + +Replace the `kotlinOptions` block with the following: + +```kotlin diff ++ kotlin { ++ compilerOptions { ++ jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 ++ } ++ } ``` +Here is how the file will likely end up: + +**After**: + +```groovy +apply plugin:'com.android.application' + +android { + // ... +} + +kotlin { + compilerOptions { + jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 + } +} + +// ... +``` + + + + ### Validate -Execute `flutter run` to confirm that your app builds and -launches on a connected Android device or emulator. +Execute `flutter run` or `flutter build apk` to confirm that +your app builds and launches on a connected Android device or emulator. ## Next steps From 7fc1f2f86de393af373126a95726bac726f47e5f Mon Sep 17 00:00:00 2001 From: jesswrd Date: Mon, 6 Apr 2026 14:53:43 -0700 Subject: [PATCH 02/26] fixed the tabs content for migrate app --- .../breaking-changes/migrate-to-agp-9.md | 40 ++++++++----------- 1 file changed, 16 insertions(+), 24 deletions(-) diff --git a/src/content/release/breaking-changes/migrate-to-agp-9.md b/src/content/release/breaking-changes/migrate-to-agp-9.md index 1e8b804df0..550cad7bbf 100644 --- a/src/content/release/breaking-changes/migrate-to-agp-9.md +++ b/src/content/release/breaking-changes/migrate-to-agp-9.md @@ -44,17 +44,20 @@ the `kotlin-android` plugin (also called Kotlin Gradle Plugin), then skip to the next step. First, find the `kotlin-android` plugin, likely located -in the `plugins` block or the legacy `apply()` method -of the `/android/build.gradle` +in the `plugins` block of the `/android/build.gradle` or `/android/build.gradle.kts` file. +If you use the legacy apply() method, it will be located in +the Groovy-based `/android/build.gradle` file, as this syntax is +not supported in Kotlin DSL. + As an example, consider the `build.gradle.kts` file from a Flutter app created before this change: -**Before**: - +**Before**: + ```kotlin plugins { id("com.android.application") @@ -90,21 +93,6 @@ Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: // ... } ``` -```groovy diff - plugins { - apply plugin:'com.android.application' -- apply plugin: 'kotlin-android' - // ... - } - - android { - // ... -- kotlinOptions { -- jvmTarget = JavaVersion.VERSION_17.toString() -- } - // ... - } -``` Replace the `kotlinOptions` block with the following: @@ -142,9 +130,12 @@ kotlin { +**Before**: + ```groovy -apply plugin:'com.android.application' +apply plugin: 'com.android.application' apply plugin: 'kotlin-android' +// ... android { // ... @@ -160,8 +151,9 @@ android { Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: ```groovy diff - apply plugin:'com.android.application' + apply plugin: 'com.android.application' - apply plugin: 'kotlin-android' +// ... android { // ... @@ -171,10 +163,9 @@ Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: // ... } ``` - Replace the `kotlinOptions` block with the following: -```kotlin diff +```groovy diff + kotlin { + compilerOptions { + jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 @@ -187,7 +178,8 @@ Here is how the file will likely end up: **After**: ```groovy -apply plugin:'com.android.application' +apply plugin: 'com.android.application' +// ... android { // ... From d15067a928e69ef916d1930b5b966c63f5cf169d Mon Sep 17 00:00:00 2001 From: jesswrd Date: Mon, 6 Apr 2026 15:01:01 -0700 Subject: [PATCH 03/26] added titles to each change --- .../breaking-changes/migrate-to-agp-9.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/content/release/breaking-changes/migrate-to-agp-9.md b/src/content/release/breaking-changes/migrate-to-agp-9.md index 550cad7bbf..ef4ff5a39c 100644 --- a/src/content/release/breaking-changes/migrate-to-agp-9.md +++ b/src/content/release/breaking-changes/migrate-to-agp-9.md @@ -50,15 +50,15 @@ If you use the legacy apply() method, it will be located in the Groovy-based `/android/build.gradle` file, as this syntax is not supported in Kotlin DSL. -As an example, consider the `build.gradle.kts` file from -a Flutter app created before this change: +The following are migration examples for migrating a Flutter Android app, +a Flutter plugins, and an add-to-app android host apps: **Before**: -```kotlin +```kotlin title="/android/build.gradle.kts" plugins { id("com.android.application") id("kotlin-android") @@ -78,7 +78,7 @@ android { Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: -```kotlin diff +```kotlin diff title="/android/build.gradle.kts" plugins { id("com.android.application") - id("kotlin-android") @@ -96,7 +96,7 @@ Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: Replace the `kotlinOptions` block with the following: -```kotlin diff +```kotlin diff title="/android/build.gradle.kts" + kotlin { + compilerOptions { + jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 @@ -108,7 +108,7 @@ Here is how the file will likely end up: **After**: -```kotlin +```kotlin title="/android/build.gradle.kts" plugins { id("com.android.application") // ... @@ -132,7 +132,7 @@ kotlin { **Before**: -```groovy +```groovy title="/android/build.gradle" apply plugin: 'com.android.application' apply plugin: 'kotlin-android' // ... @@ -150,7 +150,7 @@ android { Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: -```groovy diff +```groovy diff title="/android/build.gradle" apply plugin: 'com.android.application' - apply plugin: 'kotlin-android' // ... @@ -165,7 +165,7 @@ Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: ``` Replace the `kotlinOptions` block with the following: -```groovy diff +```groovy diff title="/android/build.gradle" + kotlin { + compilerOptions { + jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 @@ -177,7 +177,7 @@ Here is how the file will likely end up: **After**: -```groovy +```groovy title="/android/build.gradle" apply plugin: 'com.android.application' // ... From 14390eb29ff2ef883dfd98243b2310070ba4aad3 Mon Sep 17 00:00:00 2001 From: jesswrd Date: Mon, 6 Apr 2026 15:03:54 -0700 Subject: [PATCH 04/26] added library migration docs --- .../breaking-changes/migrate-to-agp-9.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) diff --git a/src/content/release/breaking-changes/migrate-to-agp-9.md b/src/content/release/breaking-changes/migrate-to-agp-9.md index ef4ff5a39c..8484235cab 100644 --- a/src/content/release/breaking-changes/migrate-to-agp-9.md +++ b/src/content/release/breaking-changes/migrate-to-agp-9.md @@ -53,6 +53,9 @@ not supported in Kotlin DSL. The following are migration examples for migrating a Flutter Android app, a Flutter plugins, and an add-to-app android host apps: + + + @@ -195,6 +198,154 @@ kotlin { ``` + + + + + +**Before**: + +```kotlin title="/android/build.gradle.kts" +plugins { + id("com.android.library") + id("kotlin-android") + // ... +} + +android { + // ... + kotlinOptions { + jvmTarget = JavaVersion.VERSION_17.toString() + } + // ... +} + +// ... +``` + +Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: + +```kotlin diff title="/android/build.gradle.kts" + plugins { + id("com.android.library") +- id("kotlin-android") + // ... + } + + android { + // ... +- kotlinOptions { +- jvmTarget = JavaVersion.VERSION_17.toString() +- } + // ... + } +``` + +Replace the `kotlinOptions` block with the following: + +```kotlin diff title="/android/build.gradle.kts" ++ kotlin { ++ compilerOptions { ++ jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 ++ } ++ } +``` + +Here is how the file will likely end up: + +**After**: + +```kotlin title="/android/build.gradle.kts" +plugins { + id("com.android.library") + // ... +} + +android { + // ... +} + +kotlin { + compilerOptions { + jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 + } +} + +// ... +``` + + + + +**Before**: + +```groovy title="/android/build.gradle" +apply plugin: 'com.android.library' +apply plugin: 'kotlin-android' +// ... + +android { + // ... + kotlinOptions { + jvmTarget = JavaVersion.VERSION_17.toString() + } + // ... +} + +// ... +``` + +Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: + +```groovy diff title="/android/build.gradle" + apply plugin: 'com.android.library' +- apply plugin: 'kotlin-android' +// ... + + android { + // ... +- kotlinOptions { +- jvmTarget = JavaVersion.VERSION_17.toString() +- } + // ... + } +``` +Replace the `kotlinOptions` block with the following: + +```groovy diff title="/android/build.gradle" ++ kotlin { ++ compilerOptions { ++ jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 ++ } ++ } +``` + +Here is how the file will likely end up: + +**After**: + +```groovy title="/android/build.gradle" +apply plugin: 'com.android.library' +// ... + +android { + // ... +} + +kotlin { + compilerOptions { + jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 + } +} + +// ... +``` + + + + + + ### Validate From bdea58c60bcabcc44a59a6424c53eeb16039b7fd Mon Sep 17 00:00:00 2001 From: jesswrd Date: Mon, 6 Apr 2026 15:27:24 -0700 Subject: [PATCH 05/26] add-to-app migration --- .../breaking-changes/migrate-to-agp-9.md | 78 ++++++++++++++++++- 1 file changed, 77 insertions(+), 1 deletion(-) diff --git a/src/content/release/breaking-changes/migrate-to-agp-9.md b/src/content/release/breaking-changes/migrate-to-agp-9.md index 8484235cab..aeb11d3524 100644 --- a/src/content/release/breaking-changes/migrate-to-agp-9.md +++ b/src/content/release/breaking-changes/migrate-to-agp-9.md @@ -203,6 +203,9 @@ kotlin { + + + **Before**: ```kotlin title="/android/build.gradle.kts" @@ -342,10 +345,83 @@ kotlin { ``` + - + + +**Before**: + +```kotlin title="/android/build.gradle.kts" +plugins { + alias(libs.plugins.android.application) + alias(libs.plugins.kotlin.android) + // ... +} + +android { + // ... + kotlinOptions { + jvmTarget = JavaVersion.VERSION_17.toString() + } + // ... +} + +// ... +``` + +Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: + +```kotlin diff title="/android/build.gradle.kts" + plugins { + alias(libs.plugins.android.application) +- alias(libs.plugins.kotlin.android) + // ... + } + + android { + // ... +- kotlinOptions { +- jvmTarget = JavaVersion.VERSION_17.toString() +- } + // ... + } +``` +Replace the `kotlinOptions` block with the following: + +```kotlin diff title="/android/build.gradle.kts" ++ kotlin { ++ compilerOptions { ++ jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 ++ } ++ } +``` + +Here is how the file will likely end up: + +**After**: + +```kotlin title="/android/build.gradle.kts" +plugins { + alias(libs.plugins.android.application) + // ... +} + +android { + // ... +} + +kotlin { + compilerOptions { + jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 + } +} + +// ... +``` + + ### Validate From 32fd3c2e77dbe4f9ac4063bbffa992742530dcfc Mon Sep 17 00:00:00 2001 From: jesswrd Date: Mon, 6 Apr 2026 16:12:17 -0700 Subject: [PATCH 06/26] update the title and description --- .../breaking-changes/migrate-to-agp-9.md | 49 +++++++++++++------ 1 file changed, 34 insertions(+), 15 deletions(-) diff --git a/src/content/release/breaking-changes/migrate-to-agp-9.md b/src/content/release/breaking-changes/migrate-to-agp-9.md index aeb11d3524..8fe9a85d9b 100644 --- a/src/content/release/breaking-changes/migrate-to-agp-9.md +++ b/src/content/release/breaking-changes/migrate-to-agp-9.md @@ -1,8 +1,8 @@ --- -title: Migrating Flutter Android app to Android Gradle Plugin 9.0.0 +title: Migrating Flutter Android projects to Built-in Kotlin description: >- - How to migrate your Flutter app's Android Gradle files - to build apps with Android Gradle Plugin 9.0.0+. + Update your Flutter Android Gradle files to use built-in Kotlin support. + Essential for migrating projects to Android Gradle Plugin 9.0.0+. --- ## Summary @@ -43,9 +43,9 @@ If your app doesn't apply the `kotlin-android` plugin (also called Kotlin Gradle Plugin), then skip to the next step. -First, find the `kotlin-android` plugin, likely located -in the `plugins` block of the `/android/build.gradle` -or `/android/build.gradle.kts` file. +First, find the `kotlin-android` plugin (or the `org.jetbrains.kotlin.android`), +likely located in the `plugins` block of the `/android/build.gradle` +or the `/android/build.gradle.kts` file. If you use the legacy apply() method, it will be located in the Groovy-based `/android/build.gradle` file, as this syntax is not supported in Kotlin DSL. @@ -61,7 +61,7 @@ a Flutter plugins, and an add-to-app android host apps: **Before**: -```kotlin title="/android/build.gradle.kts" +```kotlin title="/android/build.gradle(.kts)" plugins { id("com.android.application") id("kotlin-android") @@ -111,7 +111,7 @@ Here is how the file will likely end up: **After**: -```kotlin title="/android/build.gradle.kts" +```kotlin title="/android/build.gradle(.kts)" plugins { id("com.android.application") // ... @@ -208,7 +208,7 @@ kotlin { **Before**: -```kotlin title="/android/build.gradle.kts" +```kotlin title="/android/build.gradle(.kts)" plugins { id("com.android.library") id("kotlin-android") @@ -258,7 +258,7 @@ Here is how the file will likely end up: **After**: -```kotlin title="/android/build.gradle.kts" +```kotlin title="/android/build.gradle(.kts)" plugins { id("com.android.library") // ... @@ -353,7 +353,7 @@ kotlin { **Before**: -```kotlin title="/android/build.gradle.kts" +```kotlin title="/android/build.gradle(.kts)" plugins { alias(libs.plugins.android.application) alias(libs.plugins.kotlin.android) @@ -402,7 +402,7 @@ Here is how the file will likely end up: **After**: -```kotlin title="/android/build.gradle.kts" +```kotlin title="/android/build.gradle(.kts)" plugins { alias(libs.plugins.android.application) // ... @@ -424,6 +424,22 @@ kotlin { +:::note This is a no-op. No further migration is required. + +To ensure compatibility between the legacy Kotlin Gradle Plugin (KGP) +and the built-in Kotlin support during this migration, +we now automatically add `android.builtInKotlin=false` +and `android.newDsl=false` to your `gradle.properties` file. + +If these flags are missing from your gradle.properties file, +they will be automatically generated when you next build or run your app +using flutter run or flutter build apk. Alternatively, performing a build +through Android Studio tooling will also populate these entries. +Once the process completes, verify that the flags have been added. + +For more details, see [Issue #183910]. +::: + ### Validate Execute `flutter run` or `flutter build apk` to confirm that @@ -431,9 +447,10 @@ your app builds and launches on a connected Android device or emulator. ## Next steps -- **Full Support for Plugins:** Full support for plugins on AGP 9 - will be enabled once the team confirms the migration is backwards compatible with - older versions of AGP. +- **Remove Support for KGP:** In a future version of Flutter, + support for applying KGP will be removed. Developers must + migrate their projects (apps, plugins, host app projects) or else + they will be unable to build. - **Remove DSL Gradle Property:** Once the Flutter team completes the migration to the new AGP DSL, remove `android.newDsl=false` from your @@ -447,6 +464,7 @@ Relevant issues: - [Issue #175688][]: Audit flutter for compatibility with the AGP 9.0.0 - [Issue #180137][]: Migrate from old to new AGP DSL - [Issue #181383][]: Flutter plugins should support AGP 9.0.0 +- [Issue #183910][]: Add Disable Built-in Kotlin and new DSL Migrators The Gradle build files in your app vary based on the Flutter version used when your app was created. @@ -459,3 +477,4 @@ in your app's directory. [Issue #175688]: {{site.github}}/flutter/flutter/issues/175688 [Issue #180137]: {{site.github}}/flutter/flutter/issues/180137 [Issue #181383]: {{site.github}}/flutter/flutter/issues/181383 +[Issue #183910]: {{site.github}}/flutter/flutter/issues/183910 From d1f47c165b9855a2e1bce0925a025606886eb1c0 Mon Sep 17 00:00:00 2001 From: jesswrd Date: Mon, 6 Apr 2026 16:24:11 -0700 Subject: [PATCH 07/26] updated file name made this doc clearer. --- src/content/release/breaking-changes/index.md | 10 ++++------ ...grate-to-agp-9.md => migrate-to-built-in-kotlin.md} | 7 ++++--- 2 files changed, 8 insertions(+), 9 deletions(-) rename src/content/release/breaking-changes/{migrate-to-agp-9.md => migrate-to-built-in-kotlin.md} (97%) diff --git a/src/content/release/breaking-changes/index.md b/src/content/release/breaking-changes/index.md index e137d6087a..87eb074e36 100644 --- a/src/content/release/breaking-changes/index.md +++ b/src/content/release/breaking-changes/index.md @@ -40,18 +40,16 @@ They're sorted by release and listed in alphabetical order: * [Deprecate `onReorder` callback][] * [Deprecated `cacheExtent` and `cacheExtentStyle`][] * [Deprecate `TextInputConnection.setStyle`][] -* [`IconData` class marked as `final`][] -* [ListTile reports error in debug when wrapped in a colored widget][] -* [Migrating Flutter Android app to Android Gradle Plugin 9.0.0][] +* [ListTile throws exception when wrapped in a colored widget][] +* [Migrating Flutter Android Projects to Built-in Kotlin][] * [Page transition builders reorganization][] [Changing RawMenuAnchor close order]: /release/breaking-changes/raw-menu-anchor-close-order [Deprecate `onReorder` callback]: /release/breaking-changes/deprecate-onreorder-callback [Deprecated `cacheExtent` and `cacheExtentStyle`]: /release/breaking-changes/scroll-cache-extent [Deprecate `TextInputConnection.setStyle`]: /release/breaking-changes/deprecate-text-input-connection-set-style -[`IconData` class marked as `final`]: /release/breaking-changes/icondata-class-marked-final -[ListTile reports error in debug when wrapped in a colored widget]: /release/breaking-changes/list-tile-color-warning -[Migrating Flutter Android app to Android Gradle Plugin 9.0.0]: /release/breaking-changes/migrate-to-agp-9 +[ListTile throws exception when wrapped in a colored widget]: /release/breaking-changes/list-tile-color-warning +[Migrating Flutter Android Projects to Built-in Kotlin]: /release/breaking-changes/migrate-to-built-in-kotlin [Page transition builders reorganization]: /release/breaking-changes/decouple-page-transition-builders diff --git a/src/content/release/breaking-changes/migrate-to-agp-9.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin.md similarity index 97% rename from src/content/release/breaking-changes/migrate-to-agp-9.md rename to src/content/release/breaking-changes/migrate-to-built-in-kotlin.md index 8fe9a85d9b..04b6ffe331 100644 --- a/src/content/release/breaking-changes/migrate-to-agp-9.md +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin.md @@ -1,5 +1,5 @@ --- -title: Migrating Flutter Android projects to Built-in Kotlin +title: Migrating Flutter Android Projects to Built-in Kotlin description: >- Update your Flutter Android Gradle files to use built-in Kotlin support. Essential for migrating projects to Android Gradle Plugin 9.0.0+. @@ -20,8 +20,9 @@ This means any old DSL types will not be properly read. The Flutter team is working on migrating old DSL types to use the new DSL: [Issue #180137][]. -Support has been added to upgrade to AGP 9+. All projects, -including apps and plugins must manually migrate to built-in Kotlin. +Flutter now supports built-in Kotlin, enabling a safe upgrade to AGP 9.0+. +To ensure compatibility, all apps and plugins must be manually migrated +from the legacy Kotlin Gradle Plugin (KGP) to built-in Kotlin. In a future flutter version, support for applying KGP will be removed. To learn more about Android Gradle Plugin, From 3684e48fbb2167b380235cc3002609390bf2821a Mon Sep 17 00:00:00 2001 From: jesswrd Date: Mon, 6 Apr 2026 16:54:57 -0700 Subject: [PATCH 08/26] moved properties file instructions up --- .../migrate-to-built-in-kotlin.md | 40 +++++++++++-------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin.md index 04b6ffe331..8619354d5f 100644 --- a/src/content/release/breaking-changes/migrate-to-built-in-kotlin.md +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin.md @@ -38,6 +38,30 @@ listed in the [Android Gradle Plugin docs][AGP block]. This guide provides migration steps for Flutter Android apps, Flutter plugins, and add-to-app android host apps. +### Verify flags in properties file + +To ensure compatibility between the legacy Kotlin Gradle Plugin (KGP) +and the built-in Kotlin support during this migration, +we now automatically add `android.builtInKotlin=false` +and `android.newDsl=false` to your `gradle.properties` file. + +If these flags are missing from your gradle.properties file, +they will be automatically added when you next build or run your app +using `flutter run` or `flutter build apk`. Alternatively, performing a build +through Android Studio tooling will also populate these entries. +Once the process completes, verify that the flags have been added. +For more details, see [Issue #183910]. + +:::note All add-to-app projects must manually add `android.builtInKotlin=false` +and `android.newDsl=false` to the android host app's `gradle.properties` file. + +```properties diff title="/gradle.properties" +# ... ++ android.newDsl=false ++ android.builtInKotlin=false +``` +::: + ### Update the Gradle file If your app doesn't apply @@ -425,22 +449,6 @@ kotlin { -:::note This is a no-op. No further migration is required. - -To ensure compatibility between the legacy Kotlin Gradle Plugin (KGP) -and the built-in Kotlin support during this migration, -we now automatically add `android.builtInKotlin=false` -and `android.newDsl=false` to your `gradle.properties` file. - -If these flags are missing from your gradle.properties file, -they will be automatically generated when you next build or run your app -using flutter run or flutter build apk. Alternatively, performing a build -through Android Studio tooling will also populate these entries. -Once the process completes, verify that the flags have been added. - -For more details, see [Issue #183910]. -::: - ### Validate Execute `flutter run` or `flutter build apk` to confirm that From 1ebb6136049059a50b02c144d8e4423ce79fcf5a Mon Sep 17 00:00:00 2001 From: jesswrd Date: Mon, 6 Apr 2026 17:13:44 -0700 Subject: [PATCH 09/26] added to sidenav --- src/data/sidenav.yml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/data/sidenav.yml b/src/data/sidenav.yml index dc6616b0f6..14a6c15d53 100644 --- a/src/data/sidenav.yml +++ b/src/data/sidenav.yml @@ -447,6 +447,13 @@ permalink: /platform-integration/android/chromeos - title: Protect your app's sensitive content permalink: /platform-integration/android/sensitive-content + - title: Built-in Kotlin + permalink: /platform-integration/android/built-in-kotlin + children: + - title: Migrate to Built-in Kotlin + permalink: /release/breaking-changes/migrate-to-built-in-kotlin + - title: Report an issue to plugins + permalink: /release/breaking-changes/migrate-to-built-in-kotlin - title: iOS permalink: /platform-integration/ios children: @@ -532,6 +539,11 @@ permalink: /packages-and-plugins/swift-package-manager/for-app-developers - title: For plugin authors permalink: /packages-and-plugins/swift-package-manager/for-plugin-authors + - title: Built-in Kotlin + permalink: /packages-and-plugins/built-in-kotlin + children: + - title: Migrate to Built-in Kotlin + permalink: /release/breaking-changes/migrate-to-built-in-kotlin - divider - title: Flutter Favorites permalink: /packages-and-plugins/favorites From bc65f884a27c13255def271f1ae3ae7a5b61b47a Mon Sep 17 00:00:00 2001 From: jesswrd Date: Thu, 9 Apr 2026 12:45:58 -0700 Subject: [PATCH 10/26] refactored file. added directions --- .../migrate-to-built-in-kotlin.md | 489 ------------------ .../for-app-developers.md | 351 +++++++++++++ .../for-plugin-authors.md | 216 ++++++++ .../migrate-to-built-in-kotlin/index.md | 76 +++ 4 files changed, 643 insertions(+), 489 deletions(-) delete mode 100644 src/content/release/breaking-changes/migrate-to-built-in-kotlin.md create mode 100644 src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers.md create mode 100644 src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md create mode 100644 src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin.md deleted file mode 100644 index 8619354d5f..0000000000 --- a/src/content/release/breaking-changes/migrate-to-built-in-kotlin.md +++ /dev/null @@ -1,489 +0,0 @@ ---- -title: Migrating Flutter Android Projects to Built-in Kotlin -description: >- - Update your Flutter Android Gradle files to use built-in Kotlin support. - Essential for migrating projects to Android Gradle Plugin 9.0.0+. ---- - -## Summary - -To build a Flutter app for Android, the Android Gradle Plugin (AGP) -must be applied. As of AGP 9.0.0, -the following migrations are required to successfully apply AGP 9+. - -First, built-in Kotlin is the new default, meaning any apps -using the `kotlin-android` plugin will not build successfully. -You must migrate from `kotlin-android` to built-in Kotlin. - -Second, AGP 9+ will only use the new AGP DSL interfaces. -This means any old DSL types will not be properly read. -The Flutter team is working on migrating old DSL types -to use the new DSL: [Issue #180137][]. - -Flutter now supports built-in Kotlin, enabling a safe upgrade to AGP 9.0+. -To ensure compatibility, all apps and plugins must be manually migrated -from the legacy Kotlin Gradle Plugin (KGP) to built-in Kotlin. -In a future flutter version, support for applying KGP will be removed. - -To learn more about Android Gradle Plugin, -see the [Android Gradle Plugin docs][AGP block]. - -## Migrate - -These instructions assume you are updating from -an AGP version created before 9.0.0 to an AGP version 9.0.0+. -You should also use the minimum compatible dependency versions -listed in the [Android Gradle Plugin docs][AGP block]. - -This guide provides migration steps for Flutter Android apps, -Flutter plugins, and add-to-app android host apps. - -### Verify flags in properties file - -To ensure compatibility between the legacy Kotlin Gradle Plugin (KGP) -and the built-in Kotlin support during this migration, -we now automatically add `android.builtInKotlin=false` -and `android.newDsl=false` to your `gradle.properties` file. - -If these flags are missing from your gradle.properties file, -they will be automatically added when you next build or run your app -using `flutter run` or `flutter build apk`. Alternatively, performing a build -through Android Studio tooling will also populate these entries. -Once the process completes, verify that the flags have been added. -For more details, see [Issue #183910]. - -:::note All add-to-app projects must manually add `android.builtInKotlin=false` -and `android.newDsl=false` to the android host app's `gradle.properties` file. - -```properties diff title="/gradle.properties" -# ... -+ android.newDsl=false -+ android.builtInKotlin=false -``` -::: - -### Update the Gradle file - -If your app doesn't apply -the `kotlin-android` plugin (also called Kotlin Gradle Plugin), -then skip to the next step. - -First, find the `kotlin-android` plugin (or the `org.jetbrains.kotlin.android`), -likely located in the `plugins` block of the `/android/build.gradle` -or the `/android/build.gradle.kts` file. -If you use the legacy apply() method, it will be located in -the Groovy-based `/android/build.gradle` file, as this syntax is -not supported in Kotlin DSL. - -The following are migration examples for migrating a Flutter Android app, -a Flutter plugins, and an add-to-app android host apps: - - - - - - - -**Before**: - -```kotlin title="/android/build.gradle(.kts)" -plugins { - id("com.android.application") - id("kotlin-android") - // ... -} - -android { - // ... - kotlinOptions { - jvmTarget = JavaVersion.VERSION_17.toString() - } - // ... -} - -// ... -``` - -Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: - -```kotlin diff title="/android/build.gradle.kts" - plugins { - id("com.android.application") -- id("kotlin-android") - // ... - } - - android { - // ... -- kotlinOptions { -- jvmTarget = JavaVersion.VERSION_17.toString() -- } - // ... - } -``` - -Replace the `kotlinOptions` block with the following: - -```kotlin diff title="/android/build.gradle.kts" -+ kotlin { -+ compilerOptions { -+ jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 -+ } -+ } -``` - -Here is how the file will likely end up: - -**After**: - -```kotlin title="/android/build.gradle(.kts)" -plugins { - id("com.android.application") - // ... -} - -android { - // ... -} - -kotlin { - compilerOptions { - jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 - } -} - -// ... -``` - - - - -**Before**: - -```groovy title="/android/build.gradle" -apply plugin: 'com.android.application' -apply plugin: 'kotlin-android' -// ... - -android { - // ... - kotlinOptions { - jvmTarget = JavaVersion.VERSION_17.toString() - } - // ... -} - -// ... -``` - -Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: - -```groovy diff title="/android/build.gradle" - apply plugin: 'com.android.application' -- apply plugin: 'kotlin-android' -// ... - - android { - // ... -- kotlinOptions { -- jvmTarget = JavaVersion.VERSION_17.toString() -- } - // ... - } -``` -Replace the `kotlinOptions` block with the following: - -```groovy diff title="/android/build.gradle" -+ kotlin { -+ compilerOptions { -+ jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 -+ } -+ } -``` - -Here is how the file will likely end up: - -**After**: - -```groovy title="/android/build.gradle" -apply plugin: 'com.android.application' -// ... - -android { - // ... -} - -kotlin { - compilerOptions { - jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 - } -} - -// ... -``` - - - - - - - - - - -**Before**: - -```kotlin title="/android/build.gradle(.kts)" -plugins { - id("com.android.library") - id("kotlin-android") - // ... -} - -android { - // ... - kotlinOptions { - jvmTarget = JavaVersion.VERSION_17.toString() - } - // ... -} - -// ... -``` - -Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: - -```kotlin diff title="/android/build.gradle.kts" - plugins { - id("com.android.library") -- id("kotlin-android") - // ... - } - - android { - // ... -- kotlinOptions { -- jvmTarget = JavaVersion.VERSION_17.toString() -- } - // ... - } -``` - -Replace the `kotlinOptions` block with the following: - -```kotlin diff title="/android/build.gradle.kts" -+ kotlin { -+ compilerOptions { -+ jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 -+ } -+ } -``` - -Here is how the file will likely end up: - -**After**: - -```kotlin title="/android/build.gradle(.kts)" -plugins { - id("com.android.library") - // ... -} - -android { - // ... -} - -kotlin { - compilerOptions { - jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 - } -} - -// ... -``` - - - - -**Before**: - -```groovy title="/android/build.gradle" -apply plugin: 'com.android.library' -apply plugin: 'kotlin-android' -// ... - -android { - // ... - kotlinOptions { - jvmTarget = JavaVersion.VERSION_17.toString() - } - // ... -} - -// ... -``` - -Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: - -```groovy diff title="/android/build.gradle" - apply plugin: 'com.android.library' -- apply plugin: 'kotlin-android' -// ... - - android { - // ... -- kotlinOptions { -- jvmTarget = JavaVersion.VERSION_17.toString() -- } - // ... - } -``` -Replace the `kotlinOptions` block with the following: - -```groovy diff title="/android/build.gradle" -+ kotlin { -+ compilerOptions { -+ jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 -+ } -+ } -``` - -Here is how the file will likely end up: - -**After**: - -```groovy title="/android/build.gradle" -apply plugin: 'com.android.library' -// ... - -android { - // ... -} - -kotlin { - compilerOptions { - jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 - } -} - -// ... -``` - - - - - - - - -**Before**: - -```kotlin title="/android/build.gradle(.kts)" -plugins { - alias(libs.plugins.android.application) - alias(libs.plugins.kotlin.android) - // ... -} - -android { - // ... - kotlinOptions { - jvmTarget = JavaVersion.VERSION_17.toString() - } - // ... -} - -// ... -``` - -Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: - -```kotlin diff title="/android/build.gradle.kts" - plugins { - alias(libs.plugins.android.application) -- alias(libs.plugins.kotlin.android) - // ... - } - - android { - // ... -- kotlinOptions { -- jvmTarget = JavaVersion.VERSION_17.toString() -- } - // ... - } -``` -Replace the `kotlinOptions` block with the following: - -```kotlin diff title="/android/build.gradle.kts" -+ kotlin { -+ compilerOptions { -+ jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 -+ } -+ } -``` - -Here is how the file will likely end up: - -**After**: - -```kotlin title="/android/build.gradle(.kts)" -plugins { - alias(libs.plugins.android.application) - // ... -} - -android { - // ... -} - -kotlin { - compilerOptions { - jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 - } -} - -// ... -``` - - - - -### Validate - -Execute `flutter run` or `flutter build apk` to confirm that -your app builds and launches on a connected Android device or emulator. - -## Next steps - -- **Remove Support for KGP:** In a future version of Flutter, - support for applying KGP will be removed. Developers must - migrate their projects (apps, plugins, host app projects) or else - they will be unable to build. - -- **Remove DSL Gradle Property:** Once the Flutter team completes the migration - to the new AGP DSL, remove `android.newDsl=false` from your - `gradle.properties` file. This document will be updated - to reflect that change. - -## References - -Relevant issues: - -- [Issue #175688][]: Audit flutter for compatibility with the AGP 9.0.0 -- [Issue #180137][]: Migrate from old to new AGP DSL -- [Issue #181383][]: Flutter plugins should support AGP 9.0.0 -- [Issue #183910][]: Add Disable Built-in Kotlin and new DSL Migrators - -The Gradle build files in your app vary based on the Flutter version -used when your app was created. -Consider staying up to date with the latest version -of the build files by periodically running `flutter upgrade` -in your app's directory. - -[AGP block]: {{site.android-dev}}/build/releases/gradle-plugin - -[Issue #175688]: {{site.github}}/flutter/flutter/issues/175688 -[Issue #180137]: {{site.github}}/flutter/flutter/issues/180137 -[Issue #181383]: {{site.github}}/flutter/flutter/issues/181383 -[Issue #183910]: {{site.github}}/flutter/flutter/issues/183910 diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers.md new file mode 100644 index 0000000000..f70237629e --- /dev/null +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers.md @@ -0,0 +1,351 @@ +## Migrate + +This guide outlines the migration steps specifically for app developers. + +These instructions assume you are updating from +an AGP version created before 9.0.0 to an AGP version 9.0.0+. +You should also use the minimum compatible dependency versions +listed in the [Android Gradle Plugin docs][AGP block]. + +### Verify flags in properties file + +Flutter sets the default behavior to use the legacy Kotlin Gradle Plugin (KGP) +and the old AGP DSL types to support projects that have not yet migrated. +The Flutter migrator tool automatically adds `android.builtInKotlin=false` +and `android.newDsl=false` to your `gradle.properties` file. + +If these flags are missing from your `gradle.properties` file, +the Flutter tool automatically adds them when you next build or run your app +using `flutter run` or `flutter build apk`. + +Alternatively, building the project using Android Studio tooling also adds +these flags automatically. +Once the process completes, verify that the flags have been added. +For more details, see [Issue #183910]. + +All add-to-app projects must manually add `android.builtInKotlin=false` +and `android.newDsl=false` to the Android host app's `gradle.properties` file. +The Flutter migrator tool cannot run during add-to-app Android host app builds +because the host app is a pure native Android project. + +```properties diff title="/gradle.properties" +# ... ++ android.newDsl=false ++ android.builtInKotlin=false +``` + +:::note +If your app doesn't apply +the `kotlin-android` plugin (also called Kotlin Gradle Plugin), +then you only need to add `android.newDsl=false` and do not need +further migration. +::: + +### Update the Gradle file + +First, find the `kotlin-android` plugin (or the `org.jetbrains.kotlin.android` +plugin). +It is likely located in the `plugins` block of the +`/android/build.gradle` or the +`/android/build.gradle.kts` file. +If you use the legacy `apply` syntax, it will be located in +the Groovy-based `/android/build.gradle` file, as this syntax is +not supported in Kotlin DSL. + +The following examples demonstrate how to migrate a Flutter Android app +and an add-to-app Android host app: + +#### Migrate your Flutter Android app + + + + +**Before**: + +```kotlin title="/android/build.gradle(.kts)" +plugins { + id("com.android.application") + id("kotlin-android") + // ... +} + +android { + // ... + kotlinOptions { + jvmTarget = JavaVersion.VERSION_17.toString() + } + // ... +} + +// ... +``` + +Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: + +```kotlin diff title="/android/build.gradle.kts" + plugins { + id("com.android.application") +- id("kotlin-android") + // ... + } + + android { + // ... +- kotlinOptions { +- jvmTarget = JavaVersion.VERSION_17.toString() +- } + // ... + } +``` + +Add the `kotlin.compilerOptions{}` DSL block with the following: + +```kotlin diff title="/android/build.gradle.kts" ++ kotlin { ++ compilerOptions { ++ jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 ++ } ++ } +``` + +Here is how the file will likely end up: + +**After**: + +```kotlin title="/android/build.gradle(.kts)" +plugins { + id("com.android.application") + // ... +} + +android { + // ... +} + +kotlin { + compilerOptions { + jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 + } +} + +// ... +``` + + + + +**Before**: + +```groovy title="/android/build.gradle" +apply plugin: 'com.android.application' +apply plugin: 'kotlin-android' +// ... + +android { + // ... + kotlinOptions { + jvmTarget = JavaVersion.VERSION_17.toString() + } + // ... +} + +// ... +``` + +Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: + +```groovy diff title="/android/build.gradle" + apply plugin: 'com.android.application' +- apply plugin: 'kotlin-android' +// ... + + android { + // ... +- kotlinOptions { +- jvmTarget = JavaVersion.VERSION_17.toString() +- } + // ... + } +``` +Add the `kotlin.compilerOptions{}` DSL block with the following: + +```groovy diff title="/android/build.gradle" ++ kotlin { ++ compilerOptions { ++ jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 ++ } ++ } +``` + +Here is how the file will likely end up: + +**After**: + +```groovy title="/android/build.gradle" +apply plugin: 'com.android.application' +// ... + +android { + // ... +} + +kotlin { + compilerOptions { + jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 + } +} + +// ... +``` + + + + +#### Migrate your add-to-app Android host app + +Android native apps use the `alias` keyword to apply plugins, +which is incompatible with the legacy `apply()` syntax. +Therefore, only the `plugins {}` block instructions are included. + +**Before**: + +```kotlin title="/android/build.gradle(.kts)" +plugins { + alias(libs.plugins.android.application) + alias(libs.plugins.kotlin.android) + // ... +} + +android { + // ... + kotlinOptions { + jvmTarget = JavaVersion.VERSION_17.toString() + } + // ... +} + +// ... +``` + +Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: + +```kotlin diff title="/android/build.gradle.kts" + plugins { + alias(libs.plugins.android.application) +- alias(libs.plugins.kotlin.android) + // ... + } + + android { + // ... +- kotlinOptions { +- jvmTarget = JavaVersion.VERSION_17.toString() +- } + // ... + } +``` +Add the `kotlin.compilerOptions{}` DSL block with the following: + +```kotlin diff title="/android/build.gradle.kts" ++ kotlin { ++ compilerOptions { ++ jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 ++ } ++ } +``` + +Here is how the file will likely end up: + +**After**: + +```kotlin title="/android/build.gradle(.kts)" +plugins { + alias(libs.plugins.android.application) + // ... +} + +android { + // ... +} + +kotlin { + compilerOptions { + jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 + } +} + +// ... +``` + +### Validate + +Execute `flutter run` or `flutter build apk` to confirm that +your app builds and launches on a connected Android device or emulator. + +If your app fails to build because you are using an unmigrated Flutter plugin, +follow the instructions below: + +### Report incompatible Kotlin Gradle Plugin usage to plugin authors + +Follow these instructions only if your app uses a Flutter plugin +that has not yet migrated to built-in Kotlin. + +1. Find the repository of the unmigrated Flutter plugin by searching for the + plugin name on [pub.dev](https://pub.dev) or online. +2. Refer to the plugin CHANGELOG to confirm that no existing version + has migrated to built-in Kotlin. +3. Report an issue to the plugin authors, informing them that the Kotlin + Gradle Plugin is incompatible and won't be supported in a future version + of Flutter. + +You can use the following template for the issue: + +**Issue Title:** Migrate Plugin to Built-in Kotlin + +**Issue Body:** +I am using `` in my Flutter app. + +Starting with Android Gradle Plugin (AGP) 9.0, +support for applying the Kotlin Gradle Plugin (KGP) has been removed. +Because this plugin applies KGP, it causes a compilation error +that prevents my app from building. +Here is an example of the error [Issue #181383][]. + +Flutter has temporarily added support to allow KGP +while apps and plugins migrate to AGP 9.0+, +but this support will be removed in a future version of Flutter. + +Please migrate this plugin to use built-in Kotlin to ensure your plugin +users can successfully build their apps in future versions of Flutter. + +Here is the Flutter [migration guide for plugin authors][plugin-migration-guide]. + +Please be respectful and mindful of the plugin repository's rules and code +of conduct when reporting issues and interacting with plugin authors. + +For reference, see the [Flutter Code of Conduct][Code of Conduct]. + +## Next steps + +See the [migration overview](./) for next steps. + +## References + +Relevant issues: + +- [Issue #183910][]: Add Disable Built-in Kotlin and new DSL Migrators +- [Issue #181383][]: Flutter plugins should support AGP 9.0.0 + +The Gradle build files in your app vary based on the Flutter version +used when your app was created. +Consider staying up to date with the latest version +of the build files by periodically running `flutter upgrade` +in your app's directory. + +[AGP block]: {{site.android-dev}}/build/releases/gradle-plugin + +[Issue #183910]: {{site.github}}/flutter/flutter/issues/183910 +[Issue #181383]: {{site.github}}/flutter/flutter/issues/181383 + +[plugin-migration-guide]: {{site.flutter-docs}}/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors +[Code of Conduct]: https://github.com/flutter/flutter/blob/master/CODE_OF_CONDUCT.md diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md new file mode 100644 index 0000000000..b2c924590f --- /dev/null +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md @@ -0,0 +1,216 @@ +## Migrate Your Flutter Plugin + +This guide outlines the migration steps specifically for plugin authors. + +### Update the Gradle file + +First, find the `kotlin-android` plugin (or the `org.jetbrains.kotlin.android` +plugin). +It is likely located in the `plugins` block of the +`/build.gradle` or the `/build.gradle.kts` file. +If you use the legacy `apply` syntax, it will be located in +the Groovy-based `/build.gradle` file, as this syntax is +not supported in Kotlin DSL. + +The following examples demonstrate how to migrate a Flutter plugin: + + + + +**Before**: + +```kotlin title="/android/build.gradle(.kts)" +plugins { + id("com.android.library") + id("kotlin-android") + // ... +} + +android { + // ... + kotlinOptions { + jvmTarget = JavaVersion.VERSION_17.toString() + } + // ... +} + +// ... +``` + +Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: + +```kotlin diff title="/android/build.gradle.kts" + plugins { + id("com.android.library") +- id("kotlin-android") + // ... + } + + android { + // ... +- kotlinOptions { +- jvmTarget = JavaVersion.VERSION_17.toString() +- } + // ... + } +``` + +Add the `kotlin.compilerOptions{}` DSL block with the following: + +```kotlin diff title="/android/build.gradle.kts" ++ kotlin { ++ compilerOptions { ++ jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 ++ } ++ } +``` + +Here is how the file will likely end up: + +**After**: + +```kotlin title="/android/build.gradle(.kts)" +plugins { + id("com.android.library") + // ... +} + +android { + // ... +} + +kotlin { + compilerOptions { + jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 + } +} + +// ... +``` + + + + +**Before**: + +```groovy title="/android/build.gradle" +apply plugin: 'com.android.library' +apply plugin: 'kotlin-android' +// ... + +android { + // ... + kotlinOptions { + jvmTarget = JavaVersion.VERSION_17.toString() + } + // ... +} + +// ... +``` + +Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: + +```groovy diff title="/android/build.gradle" + apply plugin: 'com.android.library' +- apply plugin: 'kotlin-android' +// ... + + android { + // ... +- kotlinOptions { +- jvmTarget = JavaVersion.VERSION_17.toString() +- } + // ... + } +``` +Add the `kotlin.compilerOptions{}` DSL block with the following: + +```groovy diff title="/android/build.gradle" ++ kotlin { ++ compilerOptions { ++ jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 ++ } ++ } +``` + +Here is how the file will likely end up: + +**After**: + +```groovy title="/android/build.gradle" +apply plugin: 'com.android.library' +// ... + +android { + // ... +} + +kotlin { + compilerOptions { + jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 + } +} + +// ... +``` + +### Update the Plugin `pubspec.yaml` + +Using the `kotlin.compilerOptions {}` DSL block requires a minimum Kotlin Gradle Plugin (KGP) version of 2.0.0. +Beginning with Flutter 3.44, the minimum required KGP version is 2.0.0. +To ensure that apps using your plugin can safely migrate to built-in Kotlin, +you should require a minimum Flutter version of 3.44 for this plugin version. + +Since you are updating the minimum Flutter version, you must also update the minimum associated Dart version. + +Update the minimum Flutter version and the minimum Dart version: + +```yaml diff title="/pubspec.yaml" +# ... + +environment: +- sdk: ^ ++ sdk: ^3.12.0 +- flutter: ">=" ++ flutter: ">=3.44.0" + +# ... +``` + +Here is how the file will likely end up: + +```yaml title="/pubspec.yaml" +# ... + +environment: + sdk: ^3.12.0 + flutter: ">=3.44.0" + +# ... +``` + +### Update the Plugin `CHANGELOG.md` + +Include your changes in the CHANGELOG of the newly released plugin version: + +```markdown diff title="/CHANGELOG.md" ++ ## + ++ - Updates minimum supported SDK version to Flutter 3.44/Dart 3.12. ++ - Migrates to built-in Kotlin + +// ... +``` + +### Validate + +Execute `flutter run` or `flutter build apk` to confirm that +your plugin example app builds and launches +on a connected Android device or emulator. + +If your plugin example app also applies KGP, +then you will also have to migrate the example app. +Follow the [migration guide for app developers][app-migration-guide] to migrate your example app. + +[app-migration-guide]: https://docs.flutter.dev/release/breaking-changes/migrate-to-built-in-kotlin diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md new file mode 100644 index 0000000000..f708c6aab1 --- /dev/null +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md @@ -0,0 +1,76 @@ +--- +title: Migrating Flutter Android Projects to Built-in Kotlin +description: >- + Update your Flutter Android Gradle files to use built-in Kotlin support. + Essential for migrating projects to Android Gradle Plugin 9.0.0+. +--- + +## Summary + +To build a Flutter app for Android, the Android Gradle Plugin (AGP) +must be applied. As of AGP 9.0.0, +the following migrations are required to successfully use AGP 9.0.0+. + +First, built-in Kotlin is the new default on AGP 9+, meaning any apps +using the `kotlin-android` plugin (also known as the Kotlin Gradle Plugin +or KGP) will not build successfully [Issue #181383][]. +However, the Flutter team has added temporary support for the legacy +Kotlin Gradle Plugin (KGP) in AGP 9.0.0+ [Issue #183909][]. +This allows app and plugin developers to safely build their projects +regardless of their migration state. + +Second, AGP 9.0.0+ will only use the new AGP DSL interfaces. +This means any old DSL types will not be recognized. +The Flutter team is working on migrating old DSL types +to use the new DSL: [Issue #180137][]. +In the meantime, the Flutter team has configured the AGP DSL to be compatible +with the legacy old AGP DSL types [Issue #184838][]. +This ensures app and plugin developers can safely upgrade to AGP 9+. + +To ensure compatibility, all apps and plugins must be manually migrated +from the legacy Kotlin Gradle Plugin (KGP) to built-in Kotlin. +In a future Flutter version, support for applying KGP will be removed +[Issue #184837][]. + +To learn more about Android Gradle Plugin, +see the [Android Gradle Plugin docs][AGP block]. + +## Migrate + +**For app developers:** See the [app developer migration guide](./for-app-developers). + +**For plugin authors:** See the [plugin author migration guide](./for-plugin-authors). + +## Next steps + +- **Remove Support for KGP:** In a future version of Flutter, + support for applying KGP will be removed [Issue #184837][]. Developers must + migrate their projects (apps, plugins, host app projects) or they will be + unable to build. + +- **Remove DSL Gradle Property:** Once the Flutter team + completes the migration to the new AGP DSL, + the Flutter team will remove support for the old DSL [Issue #184839][]. + +Relevant issues: + +- [Issue #180137][]: Migrate from old to new AGP DSL +- [Issue #181383][]: Flutter plugins should support AGP 9.0.0 +- [Issue #183909][]: Add support for KGP in AGP+ +- [Issue #184837][]: Remove support for KGP +- [Issue #184838][]: Disable new AGP DSL flag by default +- [Issue #184839][]: Remove support for old AGP DSL types + +The Gradle build files in your app vary based on the Flutter version +used when your app was created. +Consider staying up to date with the latest version +of the build files by periodically running `flutter upgrade` +in your app's directory. + +[AGP block]: {{site.android-dev}}/build/releases/gradle-plugin + +[Issue #180137]: {{site.github}}/flutter/flutter/issues/180137 +[Issue #181383]: {{site.github}}/flutter/flutter/issues/181383 +[Issue #183909]: {{site.github}}/flutter/flutter/issues/183909 +[Issue #184837]: {{site.github}}/flutter/flutter/issues/184837 +[Issue #184838]: {{site.github}}/flutter/flutter/issues/184838 From c261e4020c5694cb7a0b99be098c83f26d4fcac1 Mon Sep 17 00:00:00 2001 From: jesswrd Date: Thu, 9 Apr 2026 12:53:06 -0700 Subject: [PATCH 11/26] add title --- .../migrate-to-built-in-kotlin/for-app-developers.md | 6 ++++++ .../migrate-to-built-in-kotlin/for-plugin-authors.md | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers.md index f70237629e..55132e8cd6 100644 --- a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers.md +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers.md @@ -1,3 +1,9 @@ +--- +title: Built-in Kotlin migration for app developers +description: >- + Migrate Flutter apps to use built-in Kotlin. +--- + ## Migrate This guide outlines the migration steps specifically for app developers. diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md index b2c924590f..b316a32b06 100644 --- a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md @@ -1,3 +1,9 @@ +--- +title: Built-in Kotlin migration for plugin authors +description: >- + Migrate Flutter plugins to use built-in Kotlin. +--- + ## Migrate Your Flutter Plugin This guide outlines the migration steps specifically for plugin authors. From ae2016a2bd55ff5181f8b1058b9a5b547c087831 Mon Sep 17 00:00:00 2001 From: jesswrd Date: Thu, 9 Apr 2026 13:52:31 -0700 Subject: [PATCH 12/26] removed from packages and plugins --- src/data/sidenav.yml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/src/data/sidenav.yml b/src/data/sidenav.yml index c2c15ac60f..dbb0916f72 100644 --- a/src/data/sidenav.yml +++ b/src/data/sidenav.yml @@ -539,11 +539,6 @@ permalink: /packages-and-plugins/swift-package-manager/for-app-developers - title: For plugin authors permalink: /packages-and-plugins/swift-package-manager/for-plugin-authors - - title: Built-in Kotlin - permalink: /packages-and-plugins/built-in-kotlin - children: - - title: Migrate to Built-in Kotlin - permalink: /release/breaking-changes/migrate-to-built-in-kotlin - divider - title: Flutter Favorites permalink: /packages-and-plugins/favorites From 2b087e8d1114a909faa91dc1423bb2688cb0487c Mon Sep 17 00:00:00 2001 From: jesswrd Date: Thu, 9 Apr 2026 14:04:11 -0700 Subject: [PATCH 13/26] match main now --- src/data/sidenav.yml | 7 ------- 1 file changed, 7 deletions(-) diff --git a/src/data/sidenav.yml b/src/data/sidenav.yml index dbb0916f72..449eeae9ba 100644 --- a/src/data/sidenav.yml +++ b/src/data/sidenav.yml @@ -447,13 +447,6 @@ permalink: /platform-integration/android/chromeos - title: Protect your app's sensitive content permalink: /platform-integration/android/sensitive-content - - title: Built-in Kotlin - permalink: /platform-integration/android/built-in-kotlin - children: - - title: Migrate to Built-in Kotlin - permalink: /release/breaking-changes/migrate-to-built-in-kotlin - - title: Report an issue to plugins - permalink: /release/breaking-changes/migrate-to-built-in-kotlin - title: iOS permalink: /platform-integration/ios children: From 1e5451795efcc18dcfa32d2350005e3d5e0dd2b5 Mon Sep 17 00:00:00 2001 From: jesswrd Date: Thu, 9 Apr 2026 14:10:41 -0700 Subject: [PATCH 14/26] update the link --- src/content/release/breaking-changes/index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/content/release/breaking-changes/index.md b/src/content/release/breaking-changes/index.md index 87eb074e36..c387f14dd9 100644 --- a/src/content/release/breaking-changes/index.md +++ b/src/content/release/breaking-changes/index.md @@ -40,7 +40,8 @@ They're sorted by release and listed in alphabetical order: * [Deprecate `onReorder` callback][] * [Deprecated `cacheExtent` and `cacheExtentStyle`][] * [Deprecate `TextInputConnection.setStyle`][] -* [ListTile throws exception when wrapped in a colored widget][] +* [`IconData` class marked as `final`][] +* [ListTile reports error in debug when wrapped in a colored widget][] * [Migrating Flutter Android Projects to Built-in Kotlin][] * [Page transition builders reorganization][] @@ -48,7 +49,8 @@ They're sorted by release and listed in alphabetical order: [Deprecate `onReorder` callback]: /release/breaking-changes/deprecate-onreorder-callback [Deprecated `cacheExtent` and `cacheExtentStyle`]: /release/breaking-changes/scroll-cache-extent [Deprecate `TextInputConnection.setStyle`]: /release/breaking-changes/deprecate-text-input-connection-set-style -[ListTile throws exception when wrapped in a colored widget]: /release/breaking-changes/list-tile-color-warning +[`IconData` class marked as `final`]: /release/breaking-changes/icondata-class-marked-final +[ListTile reports error in debug when wrapped in a colored widget]: /release/breaking-changes/list-tile-color-warning [Migrating Flutter Android Projects to Built-in Kotlin]: /release/breaking-changes/migrate-to-built-in-kotlin [Page transition builders reorganization]: /release/breaking-changes/decouple-page-transition-builders From ebaa5ceda539f31f940db32660e37c92ac7e34fc Mon Sep 17 00:00:00 2001 From: jesswrd Date: Thu, 9 Apr 2026 14:18:48 -0700 Subject: [PATCH 15/26] one more --- .../release/breaking-changes/migrate-to-built-in-kotlin/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md index f708c6aab1..6b99e02868 100644 --- a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md @@ -74,3 +74,4 @@ in your app's directory. [Issue #183909]: {{site.github}}/flutter/flutter/issues/183909 [Issue #184837]: {{site.github}}/flutter/flutter/issues/184837 [Issue #184838]: {{site.github}}/flutter/flutter/issues/184838 +[Issue #184839]: {{site.github}}/flutter/flutter/issues/184839 From d4fc1c8285d306d9c265ec026ca198b5c3b38556 Mon Sep 17 00:00:00 2001 From: jesswrd Date: Thu, 9 Apr 2026 14:30:09 -0700 Subject: [PATCH 16/26] links should be fixed --- .../migrate-to-built-in-kotlin/for-plugin-authors.md | 2 +- .../breaking-changes/migrate-to-built-in-kotlin/index.md | 7 +++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md index b316a32b06..5f17676ebd 100644 --- a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md @@ -219,4 +219,4 @@ If your plugin example app also applies KGP, then you will also have to migrate the example app. Follow the [migration guide for app developers][app-migration-guide] to migrate your example app. -[app-migration-guide]: https://docs.flutter.dev/release/breaking-changes/migrate-to-built-in-kotlin +[app-migration-guide]: {{site.flutter-docs}}/release/breaking-changes/migrate-to-built-in-kotlin diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md index 6b99e02868..23c0be1581 100644 --- a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md @@ -37,9 +37,9 @@ see the [Android Gradle Plugin docs][AGP block]. ## Migrate -**For app developers:** See the [app developer migration guide](./for-app-developers). +**For app developers:** See the [app developer migration guide][app-migration-guide]. -**For plugin authors:** See the [plugin author migration guide](./for-plugin-authors). +**For plugin authors:** See the [plugin author migration guide][plugin-migration-guide]. ## Next steps @@ -75,3 +75,6 @@ in your app's directory. [Issue #184837]: {{site.github}}/flutter/flutter/issues/184837 [Issue #184838]: {{site.github}}/flutter/flutter/issues/184838 [Issue #184839]: {{site.github}}/flutter/flutter/issues/184839 + +[app-migration-guide]: {{site.flutter-docs}}/release/breaking-changes/migrate-to-built-in-kotlin +[plugin-migration-guide]: {{site.flutter-docs}}/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors From e7df60c08d8b5e49b0a5ee4eca9a84d9bef40843 Mon Sep 17 00:00:00 2001 From: jesswrd Date: Thu, 9 Apr 2026 14:44:55 -0700 Subject: [PATCH 17/26] one more time --- .../migrate-to-built-in-kotlin/for-plugin-authors.md | 2 +- .../breaking-changes/migrate-to-built-in-kotlin/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md index 5f17676ebd..aca9a8c266 100644 --- a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md @@ -219,4 +219,4 @@ If your plugin example app also applies KGP, then you will also have to migrate the example app. Follow the [migration guide for app developers][app-migration-guide] to migrate your example app. -[app-migration-guide]: {{site.flutter-docs}}/release/breaking-changes/migrate-to-built-in-kotlin +[app-migration-guide]: {{site.flutter-docs}}/release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md index 23c0be1581..952f07df6d 100644 --- a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md @@ -76,5 +76,5 @@ in your app's directory. [Issue #184838]: {{site.github}}/flutter/flutter/issues/184838 [Issue #184839]: {{site.github}}/flutter/flutter/issues/184839 -[app-migration-guide]: {{site.flutter-docs}}/release/breaking-changes/migrate-to-built-in-kotlin +[app-migration-guide]: {{site.flutter-docs}}/release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers [plugin-migration-guide]: {{site.flutter-docs}}/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors From 030db6b305cd62d30f7210a86352309740f6ff8f Mon Sep 17 00:00:00 2001 From: Shams Zakhour <44418985+sfshaza2@users.noreply.github.com> Date: Thu, 9 Apr 2026 14:45:38 -0700 Subject: [PATCH 18/26] Update src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md --- .../migrate-to-built-in-kotlin/for-plugin-authors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md index aca9a8c266..2e2b8006b5 100644 --- a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md @@ -4,7 +4,7 @@ description: >- Migrate Flutter plugins to use built-in Kotlin. --- -## Migrate Your Flutter Plugin +## Migrate your Flutter plugin This guide outlines the migration steps specifically for plugin authors. From 94396a28e303944c1b6d88502a8fdc5b6e02ca1b Mon Sep 17 00:00:00 2001 From: Shams Zakhour <44418985+sfshaza2@users.noreply.github.com> Date: Thu, 9 Apr 2026 14:45:49 -0700 Subject: [PATCH 19/26] Update src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md --- .../migrate-to-built-in-kotlin/for-plugin-authors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md index 2e2b8006b5..81ba9b98fb 100644 --- a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md @@ -161,7 +161,7 @@ kotlin { // ... ``` -### Update the Plugin `pubspec.yaml` +### Update the plugin's `pubspec.yaml` Using the `kotlin.compilerOptions {}` DSL block requires a minimum Kotlin Gradle Plugin (KGP) version of 2.0.0. Beginning with Flutter 3.44, the minimum required KGP version is 2.0.0. From 1a6a07c60c9eb4be327e4207dca46bc9a18105a9 Mon Sep 17 00:00:00 2001 From: Shams Zakhour <44418985+sfshaza2@users.noreply.github.com> Date: Thu, 9 Apr 2026 14:46:04 -0700 Subject: [PATCH 20/26] Update src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md --- .../migrate-to-built-in-kotlin/for-plugin-authors.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md index 81ba9b98fb..8401585cbd 100644 --- a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md @@ -163,7 +163,8 @@ kotlin { ### Update the plugin's `pubspec.yaml` -Using the `kotlin.compilerOptions {}` DSL block requires a minimum Kotlin Gradle Plugin (KGP) version of 2.0.0. +Using the `kotlin.compilerOptions {}` DSL block requires +a minimum Kotlin Gradle Plugin (KGP) version of 2.0.0. Beginning with Flutter 3.44, the minimum required KGP version is 2.0.0. To ensure that apps using your plugin can safely migrate to built-in Kotlin, you should require a minimum Flutter version of 3.44 for this plugin version. From ac6e3a1204ff2be09eb780e87c4f83267bf5a8b9 Mon Sep 17 00:00:00 2001 From: Shams Zakhour <44418985+sfshaza2@users.noreply.github.com> Date: Thu, 9 Apr 2026 14:46:15 -0700 Subject: [PATCH 21/26] Update src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md --- .../migrate-to-built-in-kotlin/for-plugin-authors.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md index 8401585cbd..15c336a157 100644 --- a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md @@ -169,7 +169,8 @@ Beginning with Flutter 3.44, the minimum required KGP version is 2.0.0. To ensure that apps using your plugin can safely migrate to built-in Kotlin, you should require a minimum Flutter version of 3.44 for this plugin version. -Since you are updating the minimum Flutter version, you must also update the minimum associated Dart version. +Since you are updating the minimum Flutter version, +you must also update the minimum associated Dart version. Update the minimum Flutter version and the minimum Dart version: From 4e4b3b924a4d857bceb14ec99707ae581daaceb2 Mon Sep 17 00:00:00 2001 From: Shams Zakhour <44418985+sfshaza2@users.noreply.github.com> Date: Thu, 9 Apr 2026 14:46:25 -0700 Subject: [PATCH 22/26] Update src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md --- .../migrate-to-built-in-kotlin/for-plugin-authors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md index 15c336a157..230bf1ab51 100644 --- a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md @@ -198,7 +198,7 @@ environment: # ... ``` -### Update the Plugin `CHANGELOG.md` +### Update the plugin's `CHANGELOG.md` Include your changes in the CHANGELOG of the newly released plugin version: From 4d9d67e4df8e1a52bc365d8b9d8aedd23f4d015c Mon Sep 17 00:00:00 2001 From: Shams Zakhour <44418985+sfshaza2@users.noreply.github.com> Date: Thu, 9 Apr 2026 14:46:34 -0700 Subject: [PATCH 23/26] Update src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md --- .../breaking-changes/migrate-to-built-in-kotlin/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md index 952f07df6d..3a4c165861 100644 --- a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md @@ -1,5 +1,5 @@ --- -title: Migrating Flutter Android Projects to Built-in Kotlin +title: Migrating Flutter Android projects to built-in Kotlin description: >- Update your Flutter Android Gradle files to use built-in Kotlin support. Essential for migrating projects to Android Gradle Plugin 9.0.0+. From 96e9824c116506cc2be4b7785e9468a7511bac07 Mon Sep 17 00:00:00 2001 From: Shams Zakhour <44418985+sfshaza2@users.noreply.github.com> Date: Thu, 9 Apr 2026 14:46:45 -0700 Subject: [PATCH 24/26] Update src/content/release/breaking-changes/index.md --- src/content/release/breaking-changes/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/release/breaking-changes/index.md b/src/content/release/breaking-changes/index.md index c387f14dd9..78b2a2ee58 100644 --- a/src/content/release/breaking-changes/index.md +++ b/src/content/release/breaking-changes/index.md @@ -42,7 +42,7 @@ They're sorted by release and listed in alphabetical order: * [Deprecate `TextInputConnection.setStyle`][] * [`IconData` class marked as `final`][] * [ListTile reports error in debug when wrapped in a colored widget][] -* [Migrating Flutter Android Projects to Built-in Kotlin][] +* [Migrating Flutter Android projects to built-in Kotlin][] * [Page transition builders reorganization][] [Changing RawMenuAnchor close order]: /release/breaking-changes/raw-menu-anchor-close-order From d05b1815e073e794d587dc9c0aa9bbb18004de70 Mon Sep 17 00:00:00 2001 From: Shams Zakhour <44418985+sfshaza2@users.noreply.github.com> Date: Thu, 9 Apr 2026 14:46:56 -0700 Subject: [PATCH 25/26] Update src/content/release/breaking-changes/index.md --- src/content/release/breaking-changes/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/release/breaking-changes/index.md b/src/content/release/breaking-changes/index.md index 78b2a2ee58..b1106c7a26 100644 --- a/src/content/release/breaking-changes/index.md +++ b/src/content/release/breaking-changes/index.md @@ -51,7 +51,7 @@ They're sorted by release and listed in alphabetical order: [Deprecate `TextInputConnection.setStyle`]: /release/breaking-changes/deprecate-text-input-connection-set-style [`IconData` class marked as `final`]: /release/breaking-changes/icondata-class-marked-final [ListTile reports error in debug when wrapped in a colored widget]: /release/breaking-changes/list-tile-color-warning -[Migrating Flutter Android Projects to Built-in Kotlin]: /release/breaking-changes/migrate-to-built-in-kotlin +[Migrating Flutter Android projects to built-in Kotlin]: /release/breaking-changes/migrate-to-built-in-kotlin [Page transition builders reorganization]: /release/breaking-changes/decouple-page-transition-builders From 26694bd2520a09bd4e8e1ff37c88a5c54edb16fb Mon Sep 17 00:00:00 2001 From: jesswrd Date: Thu, 9 Apr 2026 14:58:05 -0700 Subject: [PATCH 26/26] addressed all suggested changes --- src/content/release/breaking-changes/index.md | 4 ++-- .../migrate-to-built-in-kotlin/for-plugin-authors.md | 12 +++++++----- .../migrate-to-built-in-kotlin/index.md | 2 +- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/src/content/release/breaking-changes/index.md b/src/content/release/breaking-changes/index.md index c387f14dd9..b1106c7a26 100644 --- a/src/content/release/breaking-changes/index.md +++ b/src/content/release/breaking-changes/index.md @@ -42,7 +42,7 @@ They're sorted by release and listed in alphabetical order: * [Deprecate `TextInputConnection.setStyle`][] * [`IconData` class marked as `final`][] * [ListTile reports error in debug when wrapped in a colored widget][] -* [Migrating Flutter Android Projects to Built-in Kotlin][] +* [Migrating Flutter Android projects to built-in Kotlin][] * [Page transition builders reorganization][] [Changing RawMenuAnchor close order]: /release/breaking-changes/raw-menu-anchor-close-order @@ -51,7 +51,7 @@ They're sorted by release and listed in alphabetical order: [Deprecate `TextInputConnection.setStyle`]: /release/breaking-changes/deprecate-text-input-connection-set-style [`IconData` class marked as `final`]: /release/breaking-changes/icondata-class-marked-final [ListTile reports error in debug when wrapped in a colored widget]: /release/breaking-changes/list-tile-color-warning -[Migrating Flutter Android Projects to Built-in Kotlin]: /release/breaking-changes/migrate-to-built-in-kotlin +[Migrating Flutter Android projects to built-in Kotlin]: /release/breaking-changes/migrate-to-built-in-kotlin [Page transition builders reorganization]: /release/breaking-changes/decouple-page-transition-builders diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md index aca9a8c266..230bf1ab51 100644 --- a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md @@ -4,7 +4,7 @@ description: >- Migrate Flutter plugins to use built-in Kotlin. --- -## Migrate Your Flutter Plugin +## Migrate your Flutter plugin This guide outlines the migration steps specifically for plugin authors. @@ -161,14 +161,16 @@ kotlin { // ... ``` -### Update the Plugin `pubspec.yaml` +### Update the plugin's `pubspec.yaml` -Using the `kotlin.compilerOptions {}` DSL block requires a minimum Kotlin Gradle Plugin (KGP) version of 2.0.0. +Using the `kotlin.compilerOptions {}` DSL block requires +a minimum Kotlin Gradle Plugin (KGP) version of 2.0.0. Beginning with Flutter 3.44, the minimum required KGP version is 2.0.0. To ensure that apps using your plugin can safely migrate to built-in Kotlin, you should require a minimum Flutter version of 3.44 for this plugin version. -Since you are updating the minimum Flutter version, you must also update the minimum associated Dart version. +Since you are updating the minimum Flutter version, +you must also update the minimum associated Dart version. Update the minimum Flutter version and the minimum Dart version: @@ -196,7 +198,7 @@ environment: # ... ``` -### Update the Plugin `CHANGELOG.md` +### Update the plugin's `CHANGELOG.md` Include your changes in the CHANGELOG of the newly released plugin version: diff --git a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md index 952f07df6d..3a4c165861 100644 --- a/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md +++ b/src/content/release/breaking-changes/migrate-to-built-in-kotlin/index.md @@ -1,5 +1,5 @@ --- -title: Migrating Flutter Android Projects to Built-in Kotlin +title: Migrating Flutter Android projects to built-in Kotlin description: >- Update your Flutter Android Gradle files to use built-in Kotlin support. Essential for migrating projects to Android Gradle Plugin 9.0.0+.