Article

Mobile App Architecture with Vue and Capacitor

Q: What is Capacitor?

Capacitor is a native runtime that wraps your web app in a native shell (iOS and Android). It provides a bridge to native APIs via plugins (camera, geolocation, push, storage, etc.). It is the modern successor to Cordova.

Q: When should I use Vue + Capacitor?

Use Vue + Capacitor when your team already knows Vue (or the web stack), your app is not a game or heavy 3D/AR workload, and you are okay with hybrid feel for lists, forms, and navigation. Good for line-of-business, content, and utility apps.

Q: What project structure should I use?

Feature-based or domain-based folders (auth, profile, orders); composables for shared logic and native API access; lazy-loaded routes; capacitor.config.ts at the root.

Q: How do I access native APIs?

Use Capacitor plugins: e.g. @capacitor/camera, @capacitor/geolocation, @capacitor/preferences, @capacitor/push-notifications. Install the package, run npx cap sync, and call the plugin from your code or from a composable.

Q: How do I improve performance?

Use virtual lists for long lists; Web Workers for heavy computation; lazy-load routes and images; minimise the initial bundle (tree-shake, remove unused deps). Profile on real devices.

Q: How do I store data locally?

Capacitor Preferences (@capacitor/preferences) for small key-value data (settings, tokens). IndexedDB or a SQLite plugin for larger or structured data. Use secure storage APIs for sensitive data.

Q: How do I lazy-load routes?

Use dynamic import in Vue Router: component: () => import('@/views/Page.vue'). The build will split each route into a separate chunk; the user downloads it when they navigate.

Q: Real device vs simulator?

Test on real devices early. Simulators can hide jank, memory issues, network latency, and native behaviour (camera, push, permissions).

Q: Vue + Capacitor vs React Native?

Capacitor is web-based hybrid: your Vue app runs in a WebView; plugins bridge to native. React Native compiles to native widgets. Capacitor reuses web skills and one codebase; React Native can give closer-to-native feel.

Q: How do I handle push notifications?

Use @capacitor/push-notifications. Request permission, register for push, and handle pushNotificationReceived and pushNotificationActionPerformed. Configure per platform (APNs for iOS, FCM for Android).

Cross-platform mobile with Vue and Capacitor: structure, native APIs, performance.

April 29, 2025 · Waqas Ahmad

Read the article

Introduction

This guidance is relevant when the topic of this article applies to your system or design choices; it breaks down when constraints or context differ. I’ve applied it in real projects and refined the takeaways over time (as of 2026).

Teams that already know the web stack can ship cross-platform mobile (iOS and Android) from a single codebase using Vue and Capacitor, reaching native APIs via plugins when needed. This article explains hybrid vs native, project structure, native APIs and plugins (camera, storage), lazy loading, performance patterns, and best practices for Vue + Capacitor. For architects and tech leads, getting structure and performance right from day one matters—technical debt on mobile is harder to fix once users have the app installed.

If you are new to Vue + Capacitor for mobile, start with Topics covered and Mobile app architecture at a glance. For backend API design that mobile apps consume, see the API Architecture Guide.

Topics covered

Decision Context
What is Vue and Capacitor? Hybrid vs native
Mobile app architecture at a glance
Project structure
Native APIs and plugins: camera and storage
Lazy loading and routing
Storage: Preferences and local data
Performance
Best practices and common issues
Summary
Position & Rationale
Trade-Offs & Failure Modes
What Most Guides Miss
Decision Framework
Key Takeaways
When I Would Use This Again — and When I Wouldn’t
Frequently Asked Questions

Decision Context

System scale: Varies by context; the approach in this article applies to the scales and scenarios described in the body.
Team size: Typically small to medium teams; ownership and clarity matter more than headcount.
Time / budget pressure: Applicable under delivery pressure; I’ve used it in both greenfield and incremental refactors.
Technical constraints: .NET and related stack where relevant; constraints are noted in the article where they affect the approach.
Non-goals: This article does not optimize for every possible scenario; boundaries are stated where they matter.

What is Vue and Capacitor? Hybrid vs native

Vue is a progressive JavaScript framework for building UIs: components, reactivity, and a clear lifecycle. You write Single File Components (SFCs) with template, script, and style; you use composables for shared logic and Pinia (or Vuex) for global state. Capacitor is a native runtime that wraps your web app in a native shell (iOS and Android). It is not a “web view only” wrapper—it gives you a bridge to native APIs (camera, geolocation, push, storage, etc.) via plugins, so you can stay in JavaScript/TypeScript for most of the app and drop to native only when you need to. The result is a hybrid app: one codebase, two (or more) store listings, with access to device features when you need them.

Hybrid vs native: A native app is written in Swift/Kotlin (or React Native/Flutter that compile to native widgets). A hybrid app runs your web app (HTML, CSS, JS) inside a native WebView and uses a bridge (Capacitor plugins) to call native APIs. Hybrid gives you one codebase and web skills; native (or React Native/Flutter) can give tighter integration and 60fps feel for highly interactive UIs. When does Vue + Capacitor fit? When your team already knows Vue (or the web stack), your app is not a game or a heavy 3D/AR workload, and you are okay with “good enough” native feel for lists, forms, and navigation. For highly interactive, 60fps-native-feel apps or heavy native SDKs, you might consider React Native or Flutter; for many line-of-business, content, or utility apps, Vue + Capacitor is a practical choice. We focus on structure, native APIs, and performance so that your app scales from prototype to production.

Mobile app architecture at a glance

Concept	What it is
Vue	Progressive framework for UIs; components, composables, Pinia; single codebase for web and mobile.
Capacitor	Native runtime wrapping web app in iOS/Android shell; bridge to native APIs via plugins.
Hybrid app	Web codebase (Vue) inside native WebView; one codebase, iOS + Android; plugins for camera, geo, push, storage.
Project structure	Feature-based folders; composables for shared logic; lazy-loaded routes; Capacitor config per platform.
Native APIs	Access via @capacitor/camera, @capacitor/geolocation, @capacitor/preferences, etc.; `Capacitor.getPlatform()` for iOS/Android.
Performance	Lazy-load routes; virtual lists; Web Workers for heavy work; minimise bundle; profile on real devices.

Loading diagram…

Project structure

Keep shared logic in composables so that UI and business logic stay testable and reusable. Use a feature-based or domain-based folder structure so that everything related to a flow (e.g. auth, profile, orders) lives together. Use Capacitor plugins for device features—camera, geolocation, push notifications, storage—and do not reinvent native behaviour in JavaScript when a plugin exists; it will be faster and more reliable.

Recommended layout

src/
  views/           # Route-level screens
  components/      # Shared UI
  composables/     # Shared logic (useCamera, usePreferences)
  router/
  assets/
  App.vue
  main.ts
capacitor.config.ts

Capacitor config

// capacitor.config.ts
import { CapacitorConfig } from '@capacitor/cli'

const config: CapacitorConfig = {
  appId: 'com.yourcompany.yourapp',
  appName: 'Your App',
  webDir: 'dist',
  server: {
    androidScheme: 'https'
  },
  plugins: {
    PushNotifications: { /* ... */ }
  }
}
export default config

What this does: webDir points to your built web app (e.g. dist from Vite); Capacitor copies it into the native project. appId and appName are used for iOS and Android. Run npx cap add ios and npx cap add android to generate native projects; then npx cap sync after each build to update the native app with the latest web assets.

Native APIs and plugins: camera and storage

Capacitor provides a bridge between your web app and native code. Use @capacitor/core and @capacitor/ios, @capacitor/android for the runtime; add @capacitor/camera, @capacitor/geolocation, @capacitor/preferences, etc. for device features. Check Capacitor.getPlatform() when you need to branch (e.g. iOS vs Android behaviour). Test on real devices early; simulators do not always reflect performance or native behaviour.

Step 1: Camera plugin – take a photo

// composables/useCamera.ts
import { Camera, CameraResultType, CameraSource } from '@capacitor/camera'

export function useCamera() {
  async function takePhoto(): Promise<string | null> {
    const image = await Camera.getPhoto({
      quality: 90,
      allowEditing: false,
      resultType: CameraResultType.DataUrl,
      source: CameraSource.Camera
    })
    return image.dataUrl ?? null
  }
  return { takePhoto }
}

What this does: Camera.getPhoto() opens the native camera (or photo library if you use CameraSource.Photos). On success it returns a data URL (or URI) you can display or upload. The plugin handles permissions; on first use the user will see the system permission prompt.

Step 2: Use the composable in a view

<!-- views/Profile.vue -->
<script setup lang="ts">
import { useCamera } from '@/composables/useCamera'
import { ref } from 'vue'

const { takePhoto } = useCamera()
const photo = ref<string | null>(null)

async function onTakePhoto() {
  photo.value = await takePhoto()
}
</script>

<template>
  <div>
    <button @click="onTakePhoto">Take photo</button>
    <img v-if="photo" :src="photo" alt="Profile" />
  </div>
</template>

What this does: The view calls takePhoto(); the composable uses the Capacitor Camera plugin. The same code runs on web (browser camera or file picker) and native (device camera) when you build with Capacitor.

How this fits together: Composables encapsulate native API usage so that views stay thin and you can mock the composable in tests. Add error handling (user cancels, permission denied) and platform checks (Capacitor.getPlatform() === 'ios') where behaviour differs. For storage, use the same pattern with @capacitor/preferences or IndexedDB (see below).

Lazy loading and routing

Lazy-load routes so that the initial bundle stays small. Use defineAsyncComponent or dynamic import() for route components so that users only download what they need when they navigate. Keep the shell (layout, nav) in the main bundle and load feature chunks on demand.

// router/index.ts
import { createRouter, createWebHistory } from 'vue-router'

const routes = [
  { path: '/', component: () => import('@/views/Home.vue') },
  { path: '/profile', component: () => import('@/views/Profile.vue') },
  { path: '/orders', component: () => import('@/views/Orders.vue') }
]

export const router = createRouter({
  history: createWebHistory(),
  routes
})

What this does: Each component is a dynamic import; the build splits them into separate chunks. On mobile, the first screen loads fast; other screens load when the user navigates. Use hash history (createWebHashHistory) if your hosting does not support client-side routing, or keep createWebHistory and configure the server for SPA fallback.

Storage: Preferences and local data

For small key-value data (e.g. user preferences, tokens), use Capacitor Preferences (@capacitor/preferences). For larger or structured data, use IndexedDB (or a local DB via a plugin such as SQLite). Avoid storing sensitive data in plain text; use secure storage APIs where available.

Capacitor Preferences

// composables/usePreferences.ts
import { Preferences } from '@capacitor/preferences'

export function usePreferences() {
  async function get<T>(key: string): Promise<T | null> {
    const { value } = await Preferences.get({ key })
    return value != null ? JSON.parse(value) as T : null
  }
  async function set(key: string, value: unknown): Promise<void> {
    await Preferences.set({ key, value: JSON.stringify(value) })
  }
  async function remove(key: string): Promise<void> {
    await Preferences.remove({ key })
  }
  return { get, set, remove }
}

What this does: Preferences uses native key-value storage on iOS (UserDefaults) and Android (SharedPreferences). It is persistent and survives app restarts. Use it for settings, theme, or small cached data. For offline data that syncs when online, combine with IndexedDB or a sync layer and use Preferences only for small config.

Performance

Minimise main-thread work: Move heavy computation to Web Workers where possible; avoid blocking the UI thread during list rendering or data processing. Use virtual lists (e.g. vue-virtual-scroller or a similar library) for long lists so that only visible items are rendered. Profile on real devices with Chrome DevTools (remote debugging) or Safari Web Inspector; simulators can hide jank and memory issues.

Images: Use appropriate resolutions for device pixel ratio; lazy-load images below the fold. Fonts: Subset and preload critical fonts so that text renders quickly. Bundle size: Tree-shake and analyse with vite-bundle-visualizer or similar; remove unused dependencies and keep the initial JS payload small. On mobile networks, every KB counts—keep the first load under control and lazy-load the rest.

Summary checklist: Lazy routes; virtual lists for long lists; Web Workers for heavy work; optimised images and fonts; small initial bundle; test on real devices.

Best practices and common issues

Do: Use feature-based structure and composables for native API access. Lazy-load routes and heavy components. Use Capacitor plugins for device features instead of reinventing in JS. Test on real devices early. Handle permissions and errors (user cancels, denied). Use Preferences for small data and IndexedDB (or SQLite plugin) for larger datasets. Profile and optimise bundle and list rendering.

Don’t: Block the UI thread with heavy work; render thousands of list items without virtualisation. Rely only on simulators for performance. Store sensitive data in plain text. Skip error handling for camera/storage (permissions, quota). Ignore bundle size—mobile users often have slower networks.

Common issues:

White screen or blank app: Often a routing or build issue. Ensure webDir in capacitor.config.ts matches your build output; run npx cap sync after building. Check the base URL if using createWebHistory.
Plugin not found: Install the plugin (npm i @capacitor/camera) and run npx cap sync. Rebuild the native project.
Janky lists: Use virtual lists; avoid rendering hundreds of DOM nodes. Use Web Workers for filtering/sorting large data.
Large bundle: Analyse with vite-bundle-visualizer; lazy-load routes and heavy libraries; tree-shake and remove unused deps.
Different behaviour on iOS vs Android: Use Capacitor.getPlatform() and test on both; some plugins or CSS behave differently. Handle safe area and status bar via Capacitor or CSS env().

Summary

Vue + Capacitor gives you a hybrid mobile app: one web codebase (Vue) in a native shell (iOS/Android) with a bridge to native APIs via plugins; structure (feature-based folders, composables, lazy-loaded routes) and performance (virtual lists, Web Workers, small bundle) matter from day one. Skipping structure or performance leads to slow apps and hard-to-fix debt; encapsulating native API access in composables and setting resource limits keeps the app maintainable. Next, set up a feature-based structure and capacitor.config.ts, add composables for camera and preferences, then lazy-load routes and profile on real devices.

Vue + Capacitor gives you a hybrid mobile app: one web codebase (Vue) in a native shell (iOS/Android) with a bridge to native APIs via plugins.
When it fits: Web team, not game/3D, okay with hybrid feel; forms, lists, navigation, content, and utility apps.
Structure: Feature-based folders; composables for shared logic and native API access; lazy-loaded routes; capacitor.config.ts for app id and webDir.
Native APIs: Use @capacitor/camera, @capacitor/geolocation, @capacitor/preferences, etc.; encapsulate in composables; handle permissions and errors.
Storage: Preferences for small key-value; IndexedDB or SQLite for larger data; Service Worker for caching when needed for offline.
Performance: Lazy routes, virtual lists, Web Workers, optimised images and fonts, small initial bundle; profile on real devices. Avoid blocking the UI thread and oversized bundles.

Position & Rationale

I choose Vue + Capacitor when the team is already web-focused, the app is forms/lists/content/utility (not game or heavy 3D), and we accept a hybrid feel in exchange for one codebase and fast iteration. I use feature-based structure and composables to wrap native APIs (camera, geolocation, preferences) so the rest of the app stays framework-agnostic. I prefer lazy-loaded routes and virtual lists for larger screens so we don’t block the UI thread or ship an oversized bundle. I insist on testing on real devices early; simulator performance and plugin behaviour often differ from production.

Trade-Offs & Failure Modes

What this sacrifices: Some simplicity, extra structure, or operational cost depending on the topic; the article body covers specifics.
Where it degrades: Under scale or when misapplied; early warning signs include drift from the intended use and repeated workarounds.
How it fails when misapplied: Using it where constraints don’t match, or over-applying it. The “When I Would Use This Again” section below reinforces boundaries.
Early warning signs: Team confusion, bypasses, or “we’re doing X but not really” indicate a mismatch.

What Most Guides Miss

Most guides show how to build a hybrid app with Capacitor and Vue and then stop. What they skip: native vs web trade-offs—when to drop to native (plugins, performance) and when to stay in the web view; updates and store approval—how often you can push JS bundles vs full app releases, and what happens when the store rejects a build; and device fragmentation—testing on real devices, not just simulators, because behaviour differs and users will hit the edge cases. The hard part is the product and release strategy, not the first “hello world.” If you don’t plan for OTA updates and store cycles, you’ll feel it later.

Decision Framework

If the context matches the assumptions in this article → Apply the approach as described; adapt to your scale and team.
If constraints differ → Revisit Decision Context and Trade-Offs; simplify or choose an alternative.
If you’re under heavy time pressure → Use the minimal subset that gives the most value; expand later.
If ownership is unclear → Clarify before scaling the approach; unclear ownership is an early warning sign.

Key Takeaways

The article body and Summary capture the technical content; this section distils judgment.
Apply the approach where context and constraints match; avoid over-application.
Trade-offs and failure modes are real; treat them as part of the decision.
Revisit “When I Would Use This Again” when deciding on a new project or refactor.

When I Would Use This Again — and When I Wouldn’t

I would use Vue + Capacitor again for internal or B2B apps, content/utility apps, or when the team is Vue-focused and we want one codebase for iOS and Android without maintaining two native codebases. I wouldn’t use it for games, heavy animation, or when the product demands pixel-perfect native behaviour—hybrid has limits. I’d skip it if the team has no web/front-end capacity to own the stack. If we already have a React or Angular team, I’d consider React Native or NativeScript instead of forcing Vue + Capacitor for consistency with other products.

Frequently Asked Questions

What is Capacitor?

Capacitor is a native runtime that wraps your web app in a native shell (iOS and Android). It provides a bridge to native APIs via plugins (camera, geolocation, push, storage, etc.) so you can stay in JavaScript/TypeScript for most of the app and call native code when needed. It is the modern successor to Cordova.

When should I use Vue + Capacitor?

Use Vue + Capacitor when your team already knows Vue (or the web stack), your app is not a game or heavy 3D/AR workload, and you are okay with hybrid feel for lists, forms, and navigation. Good for line-of-business, content, and utility apps. For 60fps-native-feel or heavy native SDKs, consider React Native or Flutter.

What project structure should I use?

Feature-based or domain-based folders (auth, profile, orders); composables for shared logic and native API access; lazy-loaded routes; capacitor.config.ts at the root. Keep the shell (layout, nav) in the main bundle and load feature chunks on demand.

How do I access native APIs?

Use Capacitor plugins: e.g. @capacitor/camera, @capacitor/geolocation, @capacitor/preferences, @capacitor/push-notifications. Install the package, run npx cap sync, and call the plugin from your code (or from a composable). Check Capacitor.getPlatform() when behaviour differs between iOS and Android.

How do I improve performance?

Use virtual lists for long lists; Web Workers for heavy computation; lazy-load routes and images; minimise the initial bundle (tree-shake, remove unused deps). Profile on real devices with Chrome DevTools or Safari Web Inspector. Subset and preload fonts; use appropriate image resolutions.

How do I store data locally?

Capacitor Preferences (@capacitor/preferences) for small key-value data (settings, tokens). IndexedDB or a SQLite plugin for larger or structured data. Use secure storage APIs for sensitive data; avoid plain text for secrets.

How do I lazy-load routes?

Use dynamic import in Vue Router: component: () => import('@/views/Page.vue'). The build will split each route into a separate chunk; the user downloads it when they navigate. Keep the shell and first screen in the main bundle.

Real device vs simulator?

Test on real devices early. Simulators can hide jank, memory issues, network latency, and native behaviour (camera, push, permissions). Use Chrome DevTools (remote debugging) for Android and Safari Web Inspector for iOS.

Vue + Capacitor vs React Native?

Capacitor is web-based hybrid: your Vue (or any web) app runs in a WebView; plugins bridge to native. React Native compiles to native widgets and uses a different runtime. Capacitor reuses web skills and one codebase; React Native can give a closer-to-native feel and performance for highly interactive UIs.

How do I handle push notifications?

Use @capacitor/push-notifications. Request permission, register for push, and handle pushNotificationReceived and pushNotificationActionPerformed. Configure per platform (APNs for iOS, FCM for Android) and your backend to send tokens and payloads.

How do I debug on device?

Android: Connect the device, enable USB debugging, open Chrome and go to chrome://inspect to find your WebView. iOS: Use Safari Web Inspector (Develop menu → your device → your app). Both allow you to inspect the DOM, console, and network.

What are bundle size tips?

Tree-shake (avoid importing entire libraries); use lazy routes and dynamic imports for heavy screens; run vite-bundle-visualizer (or similar) to find large dependencies; remove unused deps; replace heavy libs with lighter alternatives where possible.

What is a hybrid app?

A hybrid app is a web app (HTML, CSS, JavaScript) running inside a native container (WebView). You get one codebase for iOS and Android; a bridge (e.g. Capacitor plugins) gives access to native APIs (camera, storage, push). Trade-off: web skills and one codebase vs. potentially less native feel than a fully native or React Native/Flutter app.

Capacitor vs Cordova?

Capacitor is the modern successor to Cordova. Better plugin system, easier native project access (you can open Xcode/Android Studio and edit native code), and first-class support for modern build tools (Vite, etc.). Cordova is still used but Capacitor is the recommended choice for new projects.

How do I handle offline?

Use IndexedDB (or SQLite plugin) for data that must work offline; Service Worker for caching assets and API responses. Sync when the app comes online (e.g. background sync or on resume). Design for eventual consistency and conflict resolution if multiple devices edit the same data.

Related Guides & Resources

Part of cluster

Mobile & Frontend — explore related topics:

Mobile Development Full Stack Development

Waqas Ahmad — Software Architect & Technical Consultant

Distributed Systems

Article

Mobile App Architecture with Vue and Capacitor

Read the article

Introduction

Topics covered

Decision Context

What is Vue and Capacitor? Hybrid vs native

Mobile app architecture at a glance

Project structure

Native APIs and plugins: camera and storage

Lazy loading and routing

Storage: Preferences and local data

Performance

Best practices and common issues

Summary

Position & Rationale

Trade-Offs & Failure Modes

What Most Guides Miss

Decision Framework

Key Takeaways

When I Would Use This Again — and When I Wouldn’t

Frequently Asked Questions

Frequently Asked Questions

What is Capacitor?

When should I use Vue + Capacitor?

What project structure should I use?

How do I access native APIs?

How do I improve performance?

How do I store data locally?

How do I lazy-load routes?

Real device vs simulator?

Vue + Capacitor vs React Native?

How do I handle push notifications?

How do I debug on device?

What are bundle size tips?

What is a hybrid app?

Capacitor vs Cordova?

How do I handle offline?

Related Guides & Resources

Related articles

Part of cluster

Related services