quasarframework · hawkeye64 · Jul 14, 2026
diff --git a/app-vite/lib/modes/capacitor/config-file.js b/app-vite/lib/modes/capacitor/config-file.js
@@ -110,7 +110,7 @@ export class CapacitorConfigFile {
       : '@jcesarmobile/ssl-skip'
 
     const nodePackager = await cacheProxy.getModule('nodePackager')
-    nodePackager[fn](nameParam, {
+    await nodePackager[fn](nameParam, {
       cwd: appPaths.capacitorDir
     })
 

diff --git a/app-vite/lib/quasar-config-file.js b/app-vite/lib/quasar-config-file.js
@@ -1205,8 +1205,8 @@ export class QuasarConfigFile {
     cfg.preFetch ||= false
 
     if (
-      this.#ctx.mode.capacitor &
-      (cfg.capacitor.capacitorCliPreparationParams.length === 0)
+      this.#ctx.mode.capacitor &&
+      cfg.capacitor.capacitorCliPreparationParams.length === 0
     ) {
       cfg.capacitor.capacitorCliPreparationParams = [
         'sync',

diff --git a/docs/src/pages/quasar-cli-vite/developing-capacitor-apps/app-icons-capacitor.md b/docs/src/pages/quasar-cli-vite/developing-capacitor-apps/app-icons-capacitor.md
@@ -63,7 +63,7 @@ scope:
                               - l: ic_launcher.png
                               - l: ic_launcher_foreground.png
                               - l: ic_launcher_round.png
-                          - l: mipmap-xxhdpi
+                          - l: mipmap-xxxhdpi
                             c:
                               - l: ic_launcher.png
                               - l: ic_launcher_foreground.png
@@ -126,8 +126,6 @@ Quickly bootstrap the necessary images with Icon Genie CLI. For a complete list
 icongenie generate -m capacitor -i /path/to/source/icon.png [-b /path/to/background.png]
 ```
 
-Depending on what packager (@electron/packager or electron-builder) you will be using, please see their docs on how to hook the icons.
-
 ## Manual instructions
 
 Unless you are using the Icon Genie app extension, these are the files that you need to replace:

diff --git a/docs/src/pages/quasar-cli-vite/developing-capacitor-apps/build-commands.md b/docs/src/pages/quasar-cli-vite/developing-capacitor-apps/build-commands.md
@@ -15,7 +15,7 @@ quasar dev --mode capacitor --target [ios|android]
 It will open the IDE (Android Studio / Xcode) and from there you can manually select the emulator (or multiple ones simultaneously!) and install the dev app on it/them. You can also run the dev app on a real mobile/tablet device.
 
 ::: warning
-In Android Studio, you will be greeted with a message recommending to upgrade the Gradle version. **DO NOT UPGRADE GRADLE** as it will break the Capacitor project. Same goes for any other requested upgrades.
+Do not accept Android Studio upgrade suggestions automatically. Check the requirements and upgrade guide for your Capacitor major version before changing Gradle, the Android Gradle Plugin, Java, or SDK versions.
 
 <img src="https://cdn.quasar.dev/img/gradle-upgrade-notice.png" alt="Gradle upgrade" class="q-my-md rounded-borders" style="max-width: 350px">
 
@@ -37,7 +37,7 @@ In order for you to be able to develop on a device emulator or directly on a pho
 If developing on a mobile phone/tablet, it is very important that the external IP address of your build machine is accessible from the phone/tablet, otherwise you'll get a development app with white screen only. Also check your machine's firewall to allow connections to the development chosen port.
 :::
 
-## Building for Production
+## Building for production
 
 ```bash
 quasar build -m capacitor -T [ios|android]
@@ -46,7 +46,7 @@ quasar build -m capacitor -T [ios|android]
 quasar build --mode capacitor --target [ios|android]
 ```
 
-- These commands parse and build your `/src` folder then overwrite `/src-capacitor/www` then use the Gradle/xcodebuild to generate the final assets that go into a phone/tablet.
+- These commands build `/src` into `/src-capacitor/www`, run the configured Capacitor preparation command, and then invoke Gradle or `xcodebuild` to produce the native output.
 
 - Built packages will be located in `/dist/capacitor` unless configured otherwise.
 
@@ -63,7 +63,7 @@ quasar build -m capacitor -T [ios|android] --ide
 ```
 
 ::: warning
-In Android Studio, you will be greeted with a message recommending to upgrade the Gradle version. **DO NOT UPGRADE GRADLE** as it will break the Capacitor project. Same goes for any other requested upgrades.
+Do not accept Android Studio upgrade suggestions automatically. Check the requirements and upgrade guide for your Capacitor major version before changing the generated native toolchain.
 
 <img src="https://cdn.quasar.dev/img/gradle-upgrade-notice.png" alt="Gradle upgrade" class="q-my-md rounded-borders" style="max-width: 350px">
 

diff --git a/docs/src/pages/quasar-cli-vite/developing-capacitor-apps/capacitor-api.md b/docs/src/pages/quasar-cli-vite/developing-capacitor-apps/capacitor-api.md
@@ -3,15 +3,13 @@ title: Capacitor APIs
 desc: (@quasar/app-vite) How to use the Capacitor plugins in a Quasar app.
 ---
 
-You can hook into the native device APIs by using [Capacitor APIs](https://capacitorjs.com/docs/apis).
+You can access native device features through [Capacitor plugins](https://capacitorjs.com/docs/plugins).
 
 ## Capacitor APIs
 
-A few examples of such APIs:
+A few examples include:
 
-- Background Task
 - Camera
-- Console
 - Device
 - Filesystem
 - Geolocation
@@ -28,15 +26,19 @@ Let's learn by taking some examples, assuming you've added Capacitor mode to you
 
 ### Example: Geolocation
 
-First step is to read the documentation of the Capacitor API that we want to use. We look at Capacitor's [Geolocation API](https://capacitorjs.com/docs/apis/geolocation).
+First install the plugin in `/src-capacitor`, then synchronize the native projects:
+
+```bash
+cd src-capacitor
+pnpm add @capacitor/geolocation
+pnpm exec cap sync
+```
+
+Review the plugin's [installation and permission requirements](https://capacitorjs.com/docs/apis/geolocation) for each target platform before using it.
 
 Now let's put this plugin to some good use. In one of your Quasar project's pages/layouts/components Vue file, we write:
 
 ```html
-// some Vue file // remember this is simply an example; // only look at how we
-use the API described in the plugin's page; // the rest of things here are of no
-importance
-
 <template>
   <div> GPS position: <strong>{{ position }}</strong> </div>
 </template>
@@ -47,43 +49,45 @@ importance
 
   const position = ref('determining...')
 
-  function getCurrentPosition() {
-    Geolocation.getCurrentPosition().then(newPosition => {
-      console.log('Current', newPosition)
-      position.value = newPosition
-    })
+  async function getCurrentPosition() {
+    const newPosition = await Geolocation.getCurrentPosition()
+    console.log('Current', newPosition)
+    position.value = newPosition
   }
 
   let geoId
 
-  onMounted(() => {
-    getCurrentPosition()
+  onMounted(async () => {
+    await getCurrentPosition()
 
     // we start listening
-    geoId = Geolocation.watchPosition({}, (newPosition, err) => {
+    geoId = await Geolocation.watchPosition({}, (newPosition, err) => {
+      if (err) {
+        console.error(err)
+        return
+      }
+
       console.log('New GPS position')
       position.value = newPosition
     })
   })
 
-  onBeforeUnmount(() => {
+  onBeforeUnmount(async () => {
     // we do cleanup
-    Geolocation.clearWatch(geoId)
+    if (geoId !== void 0) {
+      await Geolocation.clearWatch({ id: geoId })
+    }
   })
 </script>
 ```
 
 ### Example: Camera
 
-First step is to read the documentation of the Capacitor API that we want to use. We look at Capacitor's [Camera API](https://capacitorjs.com/docs/apis/camera).
+Install `@capacitor/camera` in `/src-capacitor`, run `pnpm exec cap sync`, and follow the [Camera plugin's platform setup](https://capacitorjs.com/docs/apis/camera) before using it.
 
 Now let's put this API to some good use. In one of your Quasar project's pages/layouts/components Vue file, we write:
 
 ```html
-// some Vue file // remember this is simply an example; // only look at how we
-use the API described in the plugin's page; // the rest of things here are of no
-importance
-
 <template>
   <div>
     <q-btn color="primary" label="Get Picture" @click="captureImage" />
@@ -114,10 +118,10 @@ importance
 </script>
 ```
 
-Some Capacitor plugins, such as Camera, have a web-based UI available when not running natively but in a standard web browser. To enable these controls, add @ionic/pwa-elements to your project:
+Some Capacitor plugins, such as Camera, have a web-based UI available when running in a browser. To enable these controls, add `@ionic/pwa-elements` to the main Quasar project:
 
 ```bash
-npm install @ionic/pwa-elements
+pnpm add @ionic/pwa-elements
 ```
 
 Then create a boot file to initialize them, for example `/src/boot/capacitor.js`:
@@ -137,19 +141,15 @@ Don't forget to call the boot script in the `quasar.config` file:
 boot: ['capacitor']
 ```
 
-Now you are able to use the Camera API not just in native Android or iOS, but also in web based projects like a SPA or PWA.
+You can now use the Camera API in native Android and iOS builds as well as browser-based modes such as SPA and PWA, subject to the plugin's platform support.
 
 ### Example: Device
 
-First step is to read the documentation of the Capacitor API that we want to use. Look at the Capacitor's [Device API](https://capacitorjs.com/docs/apis/device).
+Install `@capacitor/device` in `/src-capacitor`, run `pnpm exec cap sync`, and review the [Device plugin documentation](https://capacitorjs.com/docs/apis/device) before using it.
 
 Now let's put this API to some good use. In one of your Quasar project's pages/layouts/components Vue file, we write:
 
 ```html
-// some Vue file // remember this is simply an example; // only look at how we
-use the API described in the plugin's page; // the rest of things here are of no
-importance
-
 <template>
   <div>
     <div>Model: {{ model }}</div>

diff --git a/...rc/pages/quasar-cli-vite/developing-capacitor-apps/capacitor-version-support.md b/...rc/pages/quasar-cli-vite/developing-capacitor-apps/capacitor-version-support.md
@@ -9,22 +9,21 @@ The officially supported versions of Capacitor are v5+.
 
 If you previously used a lower version of Capacitor and you want to upgrade to a newer version, then:
 
-1. Delete the /src-capacitor/ios and /src-capacitor/android folders, but make sure that you are aware of any changes that you made in those folders as you will have to redo them after step 4.
-2. Change /src-capacitor/package.json to reflect the correct versions of Capacitor dependencies (you can read them in the next appropriate section related to your desired Capacitor version).
-3. Delete yarn.lock/package-lock.json then run `yarn` / `npm install` in /src-capacitor.
-4. At this point, you will have Capacitor installed. Now you can run `quasar dev -m capacitor -T [ios|android]` or `quasar build -m capacitor -T [ios|android]` and it will add the upgraded iOS/Android platform that corresponds to your Capacitor version.
+Follow Capacitor's official [upgrade guide](https://capacitorjs.com/docs/updating/8-0) for the target major version, using the documentation version selector when upgrading to an older supported major. The guides cover dependency updates, native project migrations, and required toolchain changes that cannot be handled safely by changing package versions alone.
+
+Before upgrading, commit or back up `/src-capacitor`, including any native changes. Run the migration commands from `/src-capacitor`, use the lockfile and package manager already selected by the project, and verify both native targets after the upgrade.
 
 It would also be wise to check the changelog of Capacitor itself to see what breaking changes it has.
 
 ## Capacitor v8
 
 ::: warning Requirements
 
-- Node v22.21.1+
+- Node v22.22+
 - Xcode 16+ (for iOS)
 - Xcode Command Line Tools
 - Homebrew
-- Cocoapods
+- CocoaPods
 - Android Studio 2024.2.1+
 - Android SDK (API 23+)
 
@@ -33,15 +32,17 @@ It would also be wise to check the changelog of Capacitor itself to see what bre
 Assuming that you've installed Capacitor mode already, this is how your dependencies in `/src-capacitor/package.json` should look like:
 
 ```json /src-capacitor/package.json
-dependencies: {
-  "@capacitor/app": "^8.0.0",
-  "@capacitor/cli": "^8.0.0",
-  "@capacitor/core": "^8.0.0",
-  "@capacitor/splash-screen": "^8.0.0"
+{
+  "dependencies": {
+    "@capacitor/app": "^8.0.0",
+    "@capacitor/cli": "^8.0.0",
+    "@capacitor/core": "^8.0.0",
+    "@capacitor/splash-screen": "^8.0.0"
+  }
 }
 ```
 
-The `@capacitor/app` and `@capacitor/splash-screen` are optional, but it helps Quasar with some UI functionality if they are installed.
+The `@capacitor/app` and `@capacitor/splash-screen` plugins are optional, but Quasar can provide additional UI behavior when they are installed.
 
 ## Capacitor v7
 
@@ -50,7 +51,7 @@ The `@capacitor/app` and `@capacitor/splash-screen` are optional, but it helps Q
 - Xcode 16+ (for iOS)
 - Xcode Command Line Tools
 - Homebrew
-- Cocoapods
+- CocoaPods
 - Android Studio 2024.2.1+
 - Android SDK (API 23+)
 
@@ -59,15 +60,17 @@ The `@capacitor/app` and `@capacitor/splash-screen` are optional, but it helps Q
 Assuming that you've installed Capacitor mode already, this is how your dependencies in `/src-capacitor/package.json` should look like:
 
 ```json /src-capacitor/package.json
-dependencies: {
-  "@capacitor/app": "^7.0.0",
-  "@capacitor/cli": "^7.0.0",
-  "@capacitor/core": "^7.0.0",
-  "@capacitor/splash-screen": "^7.0.0"
+{
+  "dependencies": {
+    "@capacitor/app": "^7.0.0",
+    "@capacitor/cli": "^7.0.0",
+    "@capacitor/core": "^7.0.0",
+    "@capacitor/splash-screen": "^7.0.0"
+  }
 }
 ```
 
-The `@capacitor/app` and `@capacitor/splash-screen` are optional, but it helps Quasar with some UI functionality if they are installed.
+The `@capacitor/app` and `@capacitor/splash-screen` plugins are optional, but Quasar can provide additional UI behavior when they are installed.
 
 ## Capacitor v6
 
@@ -81,15 +84,17 @@ The `@capacitor/app` and `@capacitor/splash-screen` are optional, but it helps Q
 Assuming that you've installed Capacitor mode already, this is how your dependencies in `/src-capacitor/package.json` should look like:
 
 ```json /src-capacitor/package.json
-dependencies: {
-  "@capacitor/app": "^6.0.0",
-  "@capacitor/cli": "^6.0.0",
-  "@capacitor/core": "^6.0.0",
-  "@capacitor/splash-screen": "^6.0.0"
+{
+  "dependencies": {
+    "@capacitor/app": "^6.0.0",
+    "@capacitor/cli": "^6.0.0",
+    "@capacitor/core": "^6.0.0",
+    "@capacitor/splash-screen": "^6.0.0"
+  }
 }
 ```
 
-The `@capacitor/app` and `@capacitor/splash-screen` are optional, but it helps Quasar with some UI functionality if they are installed.
+The `@capacitor/app` and `@capacitor/splash-screen` plugins are optional, but Quasar can provide additional UI behavior when they are installed.
 
 ## Capacitor v5
 
@@ -103,12 +108,14 @@ The `@capacitor/app` and `@capacitor/splash-screen` are optional, but it helps Q
 Assuming that you've installed Capacitor mode already, this is how your dependencies in `/src-capacitor/package.json` should look like:
 
 ```json /src-capacitor/package.json
-dependencies: {
-  "@capacitor/app": "^5.0.0",
-  "@capacitor/cli": "^5.0.0",
-  "@capacitor/core": "^5.0.0",
-  "@capacitor/splash-screen": "^5.0.0"
+{
+  "dependencies": {
+    "@capacitor/app": "^5.0.0",
+    "@capacitor/cli": "^5.0.0",
+    "@capacitor/core": "^5.0.0",
+    "@capacitor/splash-screen": "^5.0.0"
+  }
 }
 ```
 
-The `@capacitor/app` and `@capacitor/splash-screen` are optional, but it helps Quasar with some UI functionality if they are installed.
+The `@capacitor/app` and `@capacitor/splash-screen` plugins are optional, but Quasar can provide additional UI behavior when they are installed.
diff --git a/docs/src/pages/quasar-cli-vite/developing-capacitor-apps/configuring-capacitor.md b/docs/src/pages/quasar-cli-vite/developing-capacitor-apps/configuring-capacitor.md
@@ -135,7 +135,7 @@ Same goes for `QUASAR_PROD`, `QUASAR_CLIENT`, `QUASAR_SERVER`, and any other boo
 
 ### Running cap directly
 
-If you run cap CLI yourself from `/src-capacitor` (`npx cap sync`, `cap doctor`, IDE-triggered syncs), Quasar isn't in the loop to populate the environment. The file still loads, `defineCapacitorConfig` still defaults `webDir`, static fields still work. But anything that reads `process.env.QUASAR_*` or your own `.env` file values comes back `undefined`, because nothing put them there. Code defensively if a config branch matters in that path.
+If you run the Capacitor CLI yourself from `/src-capacitor` (`pnpm exec cap sync`, `pnpm exec cap doctor`, or an IDE-triggered sync), Quasar isn't in the loop to populate the environment. The file still loads, `defineCapacitorConfig` still defaults `webDir`, and static fields still work. But anything that reads `process.env.QUASAR_*` or your own `.env` file values comes back `undefined`, because nothing put them there. Code defensively if a config branch matters in that path.
 
 ### appId and appName
 

diff --git a/docs/src/pages/quasar-cli-vite/developing-capacitor-apps/introduction.md b/docs/src/pages/quasar-cli-vite/developing-capacitor-apps/introduction.md
@@ -3,4 +3,4 @@ title: What is Capacitor
 desc: (@quasar/app-vite) Introduction on one of the technologies behind Quasar mobile apps.
 ---
 
-[Capacitor](https://capacitorjs.com) is a cross-platform native runtime for deploying web applications to mobile. It is maintained by [Ionic](https://ionic.io) and designed as a modern successor to Cordova. It supports most, but not all Cordova plugins, as well as Capacitor-specific plugins (called APIs). It exposes native device APIs in the form of JavaScript modules.
+[Capacitor](https://capacitorjs.com) is a cross-platform native runtime for deploying web applications to mobile devices. It is maintained by [Ionic](https://ionic.io) and designed as a modern successor to Cordova. Capacitor plugins expose native device features through JavaScript APIs, and many Cordova plugins can also be used when a Capacitor equivalent is unavailable.