From 028c8e14b0cb078528103f2a293f34fc8fce6e2b Mon Sep 17 00:00:00 2001 From: ShaneK Date: Fri, 15 May 2026 11:02:48 -0700 Subject: [PATCH 1/2] docs(vue): add troubleshooting entry for blank screen in Capacitor builds --- docs/vue/troubleshooting.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/vue/troubleshooting.md b/docs/vue/troubleshooting.md index 6f728e01a4a..6db73b61c55 100644 --- a/docs/vue/troubleshooting.md +++ b/docs/vue/troubleshooting.md @@ -116,3 +116,25 @@ await modal.present(); ``` This is done to align with how developers bind events in their Vue templates by using kebab-case: https://vuejs.org/guide/essentials/component-basics.html#case-insensitivity + +## Blank white screen in Capacitor native build + +If your app runs correctly in the browser but shows a blank white screen when launched in a Capacitor iOS or Android build, the most common cause is a non-default `base` in `vite.config.js` (or `publicPath` in `vue.config.js` for legacy Vue CLI projects). + +This option is often added so the app can be hosted from a subdirectory, such as a GitHub Pages deploy: + +```js +// vite.config.js +export default defineConfig({ + base: '/my-repo/', +}); +``` + +In a Capacitor build the bundled assets are served from a local origin (`capacitor://localhost` on iOS and `https://localhost` on Android by default), so the prefixed paths never resolve and the app fails to bootstrap. + +To fix it, reset `base` to `/` (or remove the option) before running `npx cap copy`. If you need both targets, keep a separate config file for each and select it at build time with `vite build --config`. + +To confirm this is the cause, inspect the device log for 404s on the prefixed asset paths: + +- **Android:** Run `adb logcat` from the command line, or open **Logcat** in Android Studio. +- **iOS:** Open Safari's **Develop** menu and inspect the Simulator or device webview. From b7cd864f83d8ca8e6cadf6149778bcc268c1af32 Mon Sep 17 00:00:00 2001 From: Shane Date: Tue, 19 May 2026 06:01:42 -0700 Subject: [PATCH 2/2] docs(vue): improving example Co-authored-by: Maria Hutt --- docs/vue/troubleshooting.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/vue/troubleshooting.md b/docs/vue/troubleshooting.md index 6db73b61c55..60b9ca00158 100644 --- a/docs/vue/troubleshooting.md +++ b/docs/vue/troubleshooting.md @@ -132,7 +132,16 @@ export default defineConfig({ In a Capacitor build the bundled assets are served from a local origin (`capacitor://localhost` on iOS and `https://localhost` on Android by default), so the prefixed paths never resolve and the app fails to bootstrap. -To fix it, reset `base` to `/` (or remove the option) before running `npx cap copy`. If you need both targets, keep a separate config file for each and select it at build time with `vite build --config`. +To fix it, reset `base` to `/` (or remove the option) before running `npx cap copy`. + +```js +// vite.config.js +export default defineConfig({ + base: '/', +}); +``` + +If you need both targets, keep a separate config file for each and select it at build time with `vite build --config`. To confirm this is the cause, inspect the device log for 404s on the prefixed asset paths: