This is an automated email from the ASF dual-hosted git repository. manuelbeck pushed a commit to branch pr-cordova-ios-8-migration-guide in repository https://gitbox.apache.org/repos/asf/cordova-docs.git
commit 9f577f4fab6a2e1bcaa748d80238fe3bc5e4677b Author: Manuel Beck <[email protected]> AuthorDate: Sat Mar 7 21:42:19 2026 +0100 doc(ios): add migration guide for upgrading to Cordova iOS 8.x - Based on blog article https://cordova.apache.org/announcements/2025/11/23/cordova-ios-8.0.0.html, cordova-ios release notes https://github.com/apache/cordova-ios/blob/rel/8.0.0/RELEASENOTES.md and cordova-ios PR #1465 https://github.com/apache/cordova-ios/pull/1465 for app icon changes - Generated-By: GPT-5.3-Codex --- .../en/latest/guide/platforms/ios/upgrade-to-8.md | 225 +++++++++++++++++++++ www/docs/en/latest/guide/platforms/ios/upgrade.md | 8 + .../platforms/ios/ios-icon-variants-result.svg | 42 ++++ .../ios/ios-icon-variants-source-assets.svg | 54 +++++ 4 files changed, 329 insertions(+) diff --git a/www/docs/en/latest/guide/platforms/ios/upgrade-to-8.md b/www/docs/en/latest/guide/platforms/ios/upgrade-to-8.md new file mode 100644 index 0000000000..2587f46592 --- /dev/null +++ b/www/docs/en/latest/guide/platforms/ios/upgrade-to-8.md @@ -0,0 +1,225 @@ +--- +license: > + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +title: Upgrading to Cordova iOS 8.x +--- + +# Upgrading to Cordova iOS 8.x + +This guide covers upgrading app projects to Cordova iOS 8.x. + +If you are maintaining plugins, see the plugin migration guide: +[Upgrading Plugins to Cordova iOS 8.x](https://apache.github.io/cordova-ios/documentation/cordova/upgrading-8?language=objc). + +## Quick upgrade + +From your Cordova app root: + +```bash +cordova platform remove ios +cordova platform add [email protected] +``` + +Using remove/add is recommended for major upgrades so the generated iOS project files are refreshed. + +## Upgrading from 8.0.0 to 8.0.1 + +`8.0.1` is currently the recommended installation target for Cordova iOS 8.x. + +If you are on `8.0.0`, upgrade to `8.0.1`. + +Upgrade as usual: + +```bash +cordova platform remove ios +cordova platform add [email protected] +``` + +For new installs targeting Cordova iOS 8, install `8.0.1` directly. + +## New minimum requirements + +Cordova iOS 8.x requires: + +* iOS deployment target 13.0 or newer +* Xcode 15 or newer +* Node.js `^20.17.0 || >=22.9.0` + +## Breaking changes to check + +### 1. Xcode project and target naming + +Cordova iOS now consistently generates an iOS project named `App`: + +* `App.xcodeproj` +* `App.xcworkspace` +* target name `App` + +If you have scripts or hooks that assumed the Xcode project name matches `<name>` in `config.xml`, update them. + +For Cordova hooks and tooling, use the `cordova-ios` API to discover paths instead of building paths manually. + +```js +const path = require('path'); +const cordova_ios = require('cordova-ios'); + +const projectRoot = context.opts.projectRoot; +const platformPath = path.join(projectRoot, 'platforms', 'ios'); +const iosProject = new cordova_ios('ios', platformPath); + +console.log(iosProject.locations.pbxproj); +``` + +### 2. Simulator tooling change + +`ios-sim` has been removed. Cordova now uses `simctl` directly. + +If you have custom automation around simulator management, migrate those scripts to use `xcrun simctl` or Cordova's updated platform commands. + +### 3. Status bar behavior + +Cordova iOS 8 adds built-in status bar handling for common cases. + +In many apps, the separate StatusBar plugin `cordova-plugin-statusbar` is no longer required. + +Status bar visibility is controlled by `viewport-fit` in your `<meta name="viewport">` tag: +- `viewport-fit=cover` will make the WebView cover the whole screen and give you access to CSS environment variables to implement your own status bar. +- `viewport-fit=contain` will keep the WebView below the status bar, with the status bar colours being determined by the `<meta name="theme-color">` tag. + +Validate your app's status bar behavior on device after upgrade. + +### 4. iOS Scene API adoption + +The template now uses iOS Scene APIs to support modern multi-window behavior, which is a requirement since iOS 26. + +If your app or custom native code assumed a single window (or directly depended on app delegate window properties), review and update that code. + +### 5. App template modernizations + +Cordova iOS 8 updates the generated native iOS project template, which is generated when you execute `cordova platform add ios`, to modern defaults, Swift-based app files and storyboard setup. + +If your build scripts or hooks modify native template files directly, review those customizations after upgrading, especially older Objective-C based patches. + +### 6. Icon workflow changes + +Cordova iOS 8 significantly updates icon handling (introduced in [GH-1465](https://github.com/apache/cordova-ios/pull/1465)). + +#### Single icon source + +For most apps, provide one 1024x1024 PNG and let Xcode generate the required icon sizes: + +```xml +<platform name="ios"> + <icon src="appicon.png" /> +</platform> +``` + +This is the simplest migration path and works for standard iOS app icons. + +#### iOS 18 dark and tinted variants (Xcode 16+) + +This feature gives iOS extra source assets for icon styling. + +You still provide the normal app icon in `src`. +Then you can optionally provide two additional assets: + +* `foreground`: should typically contain only the foreground artwork on transparency for dark-mode icon composition. +* `monochrome`: grayscale mask that iOS can tint with the system-selected color + +Example `config.xml`: + +```xml +<platform name="ios"> + <icon src="appicon.png" + foreground="appicon-dark.png" + monochrome="appicon-tint.png" /> +</platform> +``` + +Sample source assets: + + + +What this means at runtime (conceptual example): + + + +Important compatibility note: + +* Variant processing requires Xcode 16 or newer. +* On Xcode 15 and older, these variant entries are ignored by Cordova's prepare logic. +* If you do not define `foreground` and `monochrome`, Cordova/iOS use only the base `src` icon. + +#### Platform-specific icon targets + +You can override the default icon source for specific Apple platforms with `target`: + +```xml +<platform name="ios"> + <icon src="appicon.png" /> + <icon src="watchicon.png" target="watchos" /> +</platform> +``` + +Supported target values: + +* `watchos` +* `mac` +* `spotlight` (iOS special-case target when manually assigning specific iOS icon slots) + +Notes: + +* If no `watchos` icon is provided, the default app icon is used. +* `foreground` and `monochrome` variants apply to iOS icons, not watchOS/macOS icon targets. +* macOS icons do not use the single-1024 auto-generation path; custom macOS icon sets require explicit size mapping. + +#### Providing full manual icon sets + +If you choose width/height-based icon declarations instead of the single-source workflow, treat that as a full manual set for that platform target. + +In other words, if you start providing explicit sized icons, provide the complete required set for that target (iOS, watchOS, or mac) to avoid missing icon slots at build/archive time. + +Note: Cordova iOS 8.0.0 does not support Xcode 26 Icon Composer format yet. + +## Notable improvements in 8.x + +These changes are not usually migration blockers, but are useful to know: + +* plugins can be distributed as Swift packages, including package dependencies +* CordovaLib is available as a Swift package for embedding +* improved Mac Catalyst support +* CordovaLib can target visionOS when embedded +* improved handling for media range requests, open URL routing, and crash recovery configuration +* improved deployment-target handling with CocoaPods + +## Suggested validation checklist after upgrade + +1. Build and run on a simulator and a physical device. +2. Verify launch behavior and splash screen behavior. +3. Verify status bar visibility/color in all key screens. +4. Confirm plugin functionality, especially plugins with native iOS code. +5. Confirm custom hooks that read or modify the Xcode project still work with `App.xcodeproj`. +6. Validate signing, provisioning, and release build output. +7. If you upgraded from `8.0.0`, also verify the 8.0.1 fix areas relevant to your app: Xcode library search paths, Unicode/non-ASCII project names (`PRODUCT_NAME` normalization), Swift Package Manager deployment target handling, and `/_app_file_/` URL loading. + +## References + +* [Cordova iOS 8.0.0 announcement](https://cordova.apache.org/announcements/2025/11/23/cordova-ios-8.0.0.html) +* [cordova-ios release notes](https://github.com/apache/cordova-ios/blob/rel/8.0.0/RELEASENOTES.md) +* [Upgrading Plugins to Cordova iOS 8.x](https://apache.github.io/cordova-ios/documentation/cordova/upgrading-8?language=objc) diff --git a/www/docs/en/latest/guide/platforms/ios/upgrade.md b/www/docs/en/latest/guide/platforms/ios/upgrade.md index 04e23aed98..8d629c4e25 100644 --- a/www/docs/en/latest/guide/platforms/ios/upgrade.md +++ b/www/docs/en/latest/guide/platforms/ios/upgrade.md @@ -30,6 +30,14 @@ how to update the version of the CLI. __NOTE__: You should use the latest shipped version of the iOS SDK, which is included with the latest version of Xcode. +## Upgrading to Cordova iOS 8.x + +If you are upgrading from Cordova iOS 7.x or earlier, use the dedicated guide: + +* [Upgrading to Cordova iOS 8.x](upgrade-to-8.html) + +The rest of this page contains historical upgrade instructions for much older Cordova iOS versions. + ## Upgrading 4.x projects ``` diff --git a/www/static/img/guide/platforms/ios/ios-icon-variants-result.svg b/www/static/img/guide/platforms/ios/ios-icon-variants-result.svg new file mode 100644 index 0000000000..1d1cf54e9c --- /dev/null +++ b/www/static/img/guide/platforms/ios/ios-icon-variants-result.svg @@ -0,0 +1,42 @@ +<svg xmlns="http://www.w3.org/2000/svg"; width="900" height="300" viewBox="0 0 900 300" role="img" aria-labelledby="title desc"> + <title id="title">How iOS can render icon variants</title> + <desc id="desc">Illustration of regular, dark, and tinted icon appearances.</desc> + <rect width="900" height="300" fill="#f6f7f9"/> + <g font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" fill="#1f2937"> + <text x="45" y="40" font-size="20" font-weight="700">How iOS renders variants</text> + <text x="45" y="64" font-size="14">Xcode 16+ can emit dark and tinted variants when foreground/monochrome are provided.</text> + </g> + + <g transform="translate(70,95)"> + <text x="90" y="-14" text-anchor="middle" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="14" fill="#111827">Regular appearance</text> + <rect x="10" y="8" width="160" height="160" rx="36" fill="#0ea5e9"/> + <rect x="10" y="8" width="160" height="160" rx="36" fill="url(#gradB)"/> + <circle cx="90" cy="88" r="56" fill="#ffffff" fill-opacity="0.25"/> + <path d="M79 74c0-8 6-14 14-14h21c20 0 36 16 36 36s-16 36-36 36H93c-8 0-14-6-14-14V74Zm22 6v32h13c9 0 16-7 16-16s-7-16-16-16h-13Z" fill="#fff"/> + </g> + + <g transform="translate(350,95)"> + <text x="90" y="-14" text-anchor="middle" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="14" fill="#111827">Dark appearance</text> + <rect x="10" y="8" width="160" height="160" rx="36" fill="#111827"/> + <path d="M79 74c0-8 6-14 14-14h21c20 0 36 16 36 36s-16 36-36 36H93c-8 0-14-6-14-14V74Zm22 6v32h13c9 0 16-7 16-16s-7-16-16-16h-13Z" fill="#f9fafb"/> + </g> + + <g transform="translate(630,95)"> + <text x="90" y="-14" text-anchor="middle" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="14" fill="#111827">Tinted appearance</text> + <rect x="10" y="8" width="160" height="160" rx="36" fill="url(#checkerR)"/> + <rect x="10" y="8" width="160" height="160" rx="36" fill="none" stroke="#9ca3af"/> + <path d="M79 74c0-8 6-14 14-14h21c20 0 36 16 36 36s-16 36-36 36H93c-8 0-14-6-14-14V74Zm22 6v32h13c9 0 16-7 16-16s-7-16-16-16h-13Z" fill="#8b5cf6"/> + </g> + + <defs> + <linearGradient id="gradB" x1="10" y1="8" x2="170" y2="168" gradientUnits="userSpaceOnUse"> + <stop offset="0" stop-color="#38bdf8"/> + <stop offset="1" stop-color="#0369a1"/> + </linearGradient> + <pattern id="checkerR" width="16" height="16" patternUnits="userSpaceOnUse"> + <rect width="16" height="16" fill="#f8fafc"/> + <rect x="0" y="0" width="8" height="8" fill="#e5e7eb"/> + <rect x="8" y="8" width="8" height="8" fill="#e5e7eb"/> + </pattern> + </defs> +</svg> diff --git a/www/static/img/guide/platforms/ios/ios-icon-variants-source-assets.svg b/www/static/img/guide/platforms/ios/ios-icon-variants-source-assets.svg new file mode 100644 index 0000000000..a4109c813e --- /dev/null +++ b/www/static/img/guide/platforms/ios/ios-icon-variants-source-assets.svg @@ -0,0 +1,54 @@ +<svg xmlns="http://www.w3.org/2000/svg"; width="920" height="340" viewBox="0 0 920 340" role="img" aria-labelledby="title desc"> + <title id="title">Cordova iOS icon source assets</title> + <desc id="desc">Examples of src, foreground, and monochrome source PNG files with real image bounds and transparency preview.</desc> + + <rect width="920" height="340" fill="#f6f7f9"/> + + <g font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" fill="#1f2937"> + <text x="40" y="36" font-size="20" font-weight="700">Icon source files in config.xml</text> + <text x="40" y="60" font-size="14">Each source file is a full square image. Transparent regions are shown with checkerboard.</text> + </g> + + <g font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="13" fill="#111827" text-anchor="middle"> + <text x="160" y="92">src="appicon.png"</text> + <text x="460" y="92">foreground="appicon-dark.png"</text> + <text x="760" y="92">monochrome="appicon-tint.png"</text> + </g> + + <!-- src: full-color image (normally opaque) --> + <g transform="translate(80,108)"> + <rect x="0" y="0" width="160" height="160" fill="url(#gradA)"/> + <circle cx="80" cy="80" r="56" fill="#ffffff" fill-opacity="0.25"/> + <path d="M69 66c0-8 6-14 14-14h21c20 0 36 16 36 36s-16 36-36 36H83c-8 0-14-6-14-14V66Zm22 6v32h13c9 0 16-7 16-16s-7-16-16-16H91Z" fill="#ffffff"/> + </g> + + <!-- foreground: transparent background + foreground artwork only --> + <g transform="translate(380,108)"> + <rect x="0" y="0" width="160" height="160" fill="url(#checker)"/> + <path d="M69 66c0-8 6-14 14-14h21c20 0 36 16 36 36s-16 36-36 36H83c-8 0-14-6-14-14V66Zm22 6v32h13c9 0 16-7 16-16s-7-16-16-16H91Z" fill="#111827"/> + </g> + + <!-- monochrome: transparent background + grayscale mask artwork --> + <g transform="translate(680,108)"> + <rect x="0" y="0" width="160" height="160" fill="url(#checker)"/> + <path d="M69 66c0-8 6-14 14-14h21c20 0 36 16 36 36s-16 36-36 36H83c-8 0-14-6-14-14V66Zm22 6v32h13c9 0 16-7 16-16s-7-16-16-16H91Z" fill="#6b7280"/> + </g> + + <g font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="12" fill="#4b5563" text-anchor="middle"> + <text x="160" y="290">Base icon image</text> + <text x="460" y="290">Foreground only, transparent background</text> + <text x="760" y="290">Single-color mask, transparent background</text> + </g> + + <defs> + <linearGradient id="gradA" x1="0" y1="0" x2="160" y2="160" gradientUnits="userSpaceOnUse"> + <stop offset="0" stop-color="#38bdf8"/> + <stop offset="1" stop-color="#0369a1"/> + </linearGradient> + <pattern id="checker" width="16" height="16" patternUnits="userSpaceOnUse"> + <rect width="16" height="16" fill="#f8fafc"/> + <rect x="0" y="0" width="8" height="8" fill="#e5e7eb"/> + <rect x="8" y="8" width="8" height="8" fill="#e5e7eb"/> + </pattern> + </defs> +</svg> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
