From 2658a384966c370c3581e11446c6d3cdfb2e49e0 Mon Sep 17 00:00:00 2001 From: Nathan Walker Date: Mon, 20 Jan 2025 20:01:13 -0800 Subject: [PATCH 1/3] feat: platform version handling --- content/guide/platform-version-handling.md | 168 +++++++++++++++++++++ content/sidebar.ts | 22 +-- 2 files changed, 181 insertions(+), 9 deletions(-) create mode 100644 content/guide/platform-version-handling.md diff --git a/content/guide/platform-version-handling.md b/content/guide/platform-version-handling.md new file mode 100644 index 00000000..54ae5e5b --- /dev/null +++ b/content/guide/platform-version-handling.md @@ -0,0 +1,168 @@ +--- +title: Platform Version Handling +--- + +There are several key things to understand about platform version handling within the scope of your NativeScript project. Platform versioning pertains to specific SDKs shipped with Android, iOS, visionOS, macOS, Meta Quest, etc. + +In general, maintaining `package.json` dependency versions is often a familiar topic with JavaScript developers. We recommend [this article](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Client-side_tools/Package_management) as well as [our overview here](https://docs.nativescript.org/guide/development-workflow/using-packages#package-managers) if not familiar with JavaScript package managers. + +This document however focuses on a topic beyond the JavaScript ecosystem. + +# How to manage platform versions + +## Android + +There are 2 key Android files in your project to keep an eye on with platform versioning over time: + +1. `app.gradle`: [Gradle](https://gradle.org/) build configuration for Android which contains minimum, maximum and build-tools SDK targets. + +We can specify target SDKs as follows: + +```groovy +android { + compileSdkVersion 34 + buildToolsVersion "34" + defaultConfig { + minSdkVersion 24 + targetSdkVersion 34 + versionName = "1.0.0" + versionCode = 1 + } +} +``` + +Every year, platforms often bump minimum requirements for public store deployments to be accepted which can often be seen [here for Google](https://developer.android.com/google/play/requirements/target-sdk). For example, it may be stated like this: + +> New apps and app updates must target Android 14 (API level 34) or higher to be submitted to Google Play; except for Wear OS and Android TV apps, which must target Android 13 (API level 33) or higher. +Existing apps must target Android 13 (API level 33) or higher to remain available to new users on devices running Android OS higher than your app's target API level. + +It's good to refer to these platform docs from time to time (*email notifications are also often sent to Play Store accounts on these evolving requirements*) to ensure your app's targets keep up with store requirements. + +2. `before-plugins.gradle`: (*optional*) Some plugins may fallback to gradle configured versions which you can define here to also help align with app build configuration targets. + +We can specify additional gradle versions as follows: + +```groovy +ext { + compileSdkVersion = 34 + buildToolsVersion = "34" + minSdkVersion = 24 + targetSdkVersion = 34 +} +``` + +### Android Version Errors with Solutions + +#### Error Sample A + +```bash +1. Dependency 'androidx.appcompat:appcompat-resources:1.6.1' requires libraries and applications that + depend on it to compile against version 33 or later of the + Android APIs. + + :app is currently compiled against android-31. + + Recommended action: Update this project to use a newer compileSdk + of at least 33, for example 34. +``` + +#### Error Solution A + +This one is a bit more self explanatory since the error includes a recommended action. Just targeting higher sdk version would resolve this one. + +#### Error Sample B + +```bash +platforms/android/app/build.gradle' line: 574 +A problem occurred configuring project ':app'. +Could not find androidx.dynamicanimation:dynamicanimation:1.1.2 +``` + +#### Error Solution B + +This is often a misspelled plugin name or invalid version. In this particular error, it's that 1.1.2 of that library does not exist; it's actually `1.1.0-alpha03` for example. + +## iOS + +There are 2 key iOS files in your project to keep an eye on with platform versioning over time: + +- `App_Resources/iOS/build.xcconfig`: Sets minimum iOS deployment version + +We can specify the minimum target as follows: + +```bash +IPHONEOS_DEPLOYMENT_TARGET = 17.0; +``` + +Every year, platforms often bump minimum requirements for public store deployments to be accepted which can often be seen [here for Apple](https://developer.apple.com/ios/submit/). For example, the `Build with Xcode` section may often state something like this: + +> All iOS and iPadOS apps uploaded to App Store Connect must be built with a minimum of Xcode 15 and the iOS 17 SDK. Starting April 2025, all iOS and iPadOS apps uploaded to App Store Connect must be built with the iOS 18 SDK. + +It's good to refer to these platform docs from time to time (*email notifications are also often sent to App Store accounts on these evolving requirements*) to ensure your app's targets keep up with store requirements. + +- `App_Resources/iOS/Podfile`: (*optional*) If your project brings in plugins that involve [Cocoapods](https://cocoapods.org/) it's a good idea to have one of these. It can help align platform version minimums to match your build.xcconfig. + +We can make our `Podfile` match our build.xcconfig target versions as follows: + +```ruby +platform :ios, '17.0' + +post_install do |installer| + installer.pods_project.targets.each do |target| + target.build_configurations.each do |config| + config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '17.0' + end + end +end +``` + +It's generally a good practice to have these match. + +### iOS Version Errors with Solutions + +#### iOS Version Error Sample A + +``` +node_modules/@nativescript/swift-ui/platforms/ios/src/Common/View+Modifiers.swift:874:49: error: 'accessibilitySortPriority' is only available in iOS 14.0 or newer + view = AnyView(view.accessibilitySortPriority(priority)) + +RichTextKit/Sources/RichTextKit/Format/RichTextFormatToolbarBase.swift:148:31: error: 'bordered' is only available in iOS 15.0 or newer + .buttonStyle(.bordered) + +RichTextKit/Sources/RichTextKit/Colors/RichTextColor+Picker.swift:175:22: error: 'foregroundStyle' is only available in iOS 17.0 or newer + .foregroundStyle(foregroundColor) +``` + +### iOS Version Error Solution A + +This is related to 2 causes: + +- A plugin in use, @nativescript/swift-ui, uses a modifier that is only available on iOS 14.0 or newer. +- Another plugin or internal implementation in the project use uses Swift APIs that are only available in 15 and 17 or newer. + +So what to do in a case like this? You have several options. + +A. Set an `IPHONEOS_DEPLOYMENT_TARGET` in your `App_Resource/iOS/build.xcconfig` to the highest minimum version stated. In this case, it would be 17.0. + +``` +IPHONEOS_DEPLOYMENT_TARGET = 17.0; +``` + +B. Make a change to source code to properly wrap the implementations with [availability](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/statements/#Availability-Condition) decorators to ensure that platform version specific code does not cause an issue if your app is run on an older devicie. You can use [patch-package](https://www.npmjs.com/package/patch-package) to create the diff to manage custom source code changes made to plugins. + +``` +var body: some View { + if #available(iOS 17.0, *) { + ZStack { + // ... something only available on iOS 17 or newer + } + } else { + // fallback + EmptyView() + } +} +``` + +## Other Considerations + +It's common for NativeScript plugins to include a `platforms/{ios|android}` folder which merge various platform dependencies in with your project. These will often include Cocoapods, gradle plugins, or just platform specific code. It's possible these plugins may specify SDK's which need an update from time to time to match the store requirements mentioned above. You can contact plugin authors or become involved in open source yourself by helping keep your plugins up to date. diff --git a/content/sidebar.ts b/content/sidebar.ts index f9e0ea58..1e1b62db 100644 --- a/content/sidebar.ts +++ b/content/sidebar.ts @@ -161,10 +161,18 @@ export default [ { text: 'Fundamental Concepts', items: [ + { + text: 'Accessibility', + link: '/guide/accessibility', + }, { text: 'Animations', link: '/guide/animations', }, + { + text: 'Best Practices', + link: '/best-practices/', + }, ...coreSidebarItems, { text: 'Data Binding', @@ -199,7 +207,7 @@ export default [ { text: 'Styling', link: '/guide/styling', - }, + } ], }, { @@ -254,14 +262,6 @@ export default [ text: 'Shared Element Transitions', link: '/guide/shared-element-transitions', }, - { - text: 'Accessibility', - link: '/guide/accessibility', - }, - { - text: 'Best Practices', - link: '/best-practices/', - }, { text: 'Multithreading', link: '/guide/multithreading', @@ -296,6 +296,10 @@ export default [ }, ], }, + { + text: 'Platform Version Handling', + link: '/guide/platform-version-handling', + } ], }, ] as NSSidebarGroup[] From 115f17be0e61d5761b84713d28b41e7edffb3194 Mon Sep 17 00:00:00 2001 From: Nathan Walker Date: Mon, 20 Jan 2025 20:05:43 -0800 Subject: [PATCH 2/3] chore: cleanup --- content/guide/platform-version-handling.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/content/guide/platform-version-handling.md b/content/guide/platform-version-handling.md index 54ae5e5b..1256b1e2 100644 --- a/content/guide/platform-version-handling.md +++ b/content/guide/platform-version-handling.md @@ -12,7 +12,9 @@ This document however focuses on a topic beyond the JavaScript ecosystem. ## Android -There are 2 key Android files in your project to keep an eye on with platform versioning over time: +The [@nativescript/android](https://github.com/NativeScript/android) dependency is good to keep your project up to date with as it often contains system level updates and requirements. + +Beyond that, there are 2 key Android files in your project to keep an eye on with platform versioning over time: 1. `app.gradle`: [Gradle](https://gradle.org/) build configuration for Android which contains minimum, maximum and build-tools SDK targets. @@ -84,7 +86,9 @@ This is often a misspelled plugin name or invalid version. In this particular er ## iOS -There are 2 key iOS files in your project to keep an eye on with platform versioning over time: +The [@nativescript/ios](https://github.com/NativeScript/ios) dependency is good to keep your project up to date with as it often contains system level updates and requirements. + +Beyond that, there are 2 key iOS files in your project to keep an eye on with platform versioning over time: - `App_Resources/iOS/build.xcconfig`: Sets minimum iOS deployment version @@ -120,7 +124,7 @@ It's generally a good practice to have these match. ### iOS Version Errors with Solutions -#### iOS Version Error Sample A +#### Error Sample A ``` node_modules/@nativescript/swift-ui/platforms/ios/src/Common/View+Modifiers.swift:874:49: error: 'accessibilitySortPriority' is only available in iOS 14.0 or newer @@ -133,7 +137,7 @@ RichTextKit/Sources/RichTextKit/Colors/RichTextColor+Picker.swift:175:22: error: .foregroundStyle(foregroundColor) ``` -### iOS Version Error Solution A +### Error Solution A This is related to 2 causes: @@ -165,4 +169,4 @@ var body: some View { ## Other Considerations -It's common for NativeScript plugins to include a `platforms/{ios|android}` folder which merge various platform dependencies in with your project. These will often include Cocoapods, gradle plugins, or just platform specific code. It's possible these plugins may specify SDK's which need an update from time to time to match the store requirements mentioned above. You can contact plugin authors or become involved in open source yourself by helping keep your plugins up to date. +It's common for [NativeScript plugins](https://docs.nativescript.org/plugins/) that your project may depend on to include a `platforms/{ios|android}` folder which merge various platform dependencies in with your project. These will often include Cocoapods, gradle plugins, or just platform specific code. It's possible these plugins may specify SDK's which need an update from time to time to match the store requirements mentioned above. You can contact plugin authors or become involved in open source yourself by helping keep your plugins up to date. From 2d4c1b1edf7e7c2ec4914575496a8fa5c95cc7ba Mon Sep 17 00:00:00 2001 From: Nathan Walker Date: Mon, 20 Jan 2025 20:07:17 -0800 Subject: [PATCH 3/3] chore: cleanup --- content/guide/platform-version-handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guide/platform-version-handling.md b/content/guide/platform-version-handling.md index 1256b1e2..8f26f8fb 100644 --- a/content/guide/platform-version-handling.md +++ b/content/guide/platform-version-handling.md @@ -2,7 +2,7 @@ title: Platform Version Handling --- -There are several key things to understand about platform version handling within the scope of your NativeScript project. Platform versioning pertains to specific SDKs shipped with Android, iOS, visionOS, macOS, Meta Quest, etc. +There are several key things to understand about platform version handling within the scope of your NativeScript project. When talking about platform versions, we are referring to specific platform level SDKs shipped with Android, iOS, visionOS, macOS, Meta Quest, etc. In general, maintaining `package.json` dependency versions is often a familiar topic with JavaScript developers. We recommend [this article](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Client-side_tools/Package_management) as well as [our overview here](https://docs.nativescript.org/guide/development-workflow/using-packages#package-managers) if not familiar with JavaScript package managers.