capacitor-vue

What this skill does

# Capacitor with Vue

Vue-specific patterns and best practices for Capacitor app development — Composition API, composables, reactivity, lifecycle hooks, Vue Router integration, and framework-specific guidance for Quasar and Nuxt.

## Prerequisites

1. **Capacitor 6, 7, or 8** app with Vue 3.
2. Node.js and npm installed.
3. For iOS: Xcode installed.
4. For Android: Android Studio installed.

## Agent Behavior

- **Auto-detect before asking.** Check the project for `vite.config.ts`, `vite.config.js`, `quasar.config.js`, `quasar.config.ts`, `nuxt.config.ts`, `package.json`, `capacitor.config.ts` or `capacitor.config.json`, and existing directory structure. Only ask the user when something cannot be detected.
- **Guide step-by-step.** Walk the user through the process one step at a time.
- **Detect the meta-framework.** Determine whether the project uses plain Vue (Vite), Quasar, or Nuxt, and adapt instructions accordingly.

## Procedures

### Step 1: Analyze the Project

Auto-detect the following by reading project files:

1. **Vue version**: Read `vue` version from `package.json`.
2. **Capacitor version**: Read `@capacitor/core` version from `package.json`. If not present, Capacitor has not been added yet — proceed to Step 2.
3. **Meta-framework**: Detect the framework by checking for these files in order:
   - `quasar.config.js` or `quasar.config.ts` — **Quasar** project. Proceed to `references/quasar.md`.
   - `nuxt.config.ts` or `nuxt.config.js` — **Nuxt** project. Proceed to `references/nuxt.md`.
   - `vite.config.ts` or `vite.config.js` — **Plain Vue (Vite)** project. Continue with the steps below.
4. **Platforms**: Check which directories exist (`android/`, `ios/`).
5. **Capacitor config format**: Check for `capacitor.config.ts` (TypeScript) or `capacitor.config.json` (JSON).
6. **Build output directory**: Read `build.outDir` from `vite.config.ts` or `vite.config.js`. The default is `dist`.

### Step 2: Add Capacitor to a Vue Project

Skip if `@capacitor/core` is already in `package.json`. Skip if the project uses Quasar (Quasar has its own Capacitor integration — see `references/quasar.md`).

1. Install Capacitor core and CLI:

   ```bash
   npm install @capacitor/core
   npm install -D @capacitor/cli
   ```

2. Initialize Capacitor:

   ```bash
   npx cap init
   ```

   When prompted, set the **web directory** to the Vue build output path detected in Step 1. For Vite-based Vue projects, this is typically `dist`.

3. Verify the `webDir` value in the generated `capacitor.config.ts` or `capacitor.config.json` matches the Vue build output path. If incorrect, update it:

   **`capacitor.config.ts`:**
   ```typescript
   import type { CapacitorConfig } from '@capacitor/cli';

   const config: CapacitorConfig = {
     appId: 'com.example.app',
     appName: 'my-app',
     webDir: 'dist',
   };

   export default config;
   ```

   **`capacitor.config.json`:**
   ```json
   {
     "appId": "com.example.app",
     "appName": "my-app",
     "webDir": "dist"
   }
   ```

4. Build the Vue app and add platforms:

   ```bash
   npm run build
   npm install @capacitor/android @capacitor/ios
   npx cap add android
   npx cap add ios
   npx cap sync
   ```

### Step 3: Project Structure

A Capacitor Vue project (Vite-based) has this structure:

```
my-app/
├── android/                  # Android native project
├── ios/                      # iOS native project
├── public/
├── src/
│   ├── assets/
│   ├── components/
│   ├── composables/          # Custom composables for Capacitor plugins
│   ├── router/
│   │   └── index.ts          # Vue Router configuration
│   ├── views/
│   ├── App.vue
│   └── main.ts
├── capacitor.config.ts       # or capacitor.config.json
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts
```

Key points:
- The `android/` and `ios/` directories contain native projects and should be committed to version control.
- The `src/` directory contains the Vue app, which is the web layer of the Capacitor app.
- Place custom composables that wrap Capacitor plugins in `src/composables/`.
- Capacitor plugins are called from Vue components or composables inside `src/`.

### Step 4: Using Capacitor Plugins in Vue

Capacitor plugins are plain TypeScript APIs. Import and call them directly in Vue components using the Composition API.

#### Direct Usage in a Component

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { Geolocation } from '@capacitor/geolocation';

const latitude = ref<number | null>(null);
const longitude = ref<number | null>(null);

async function getCurrentPosition() {
  const position = await Geolocation.getCurrentPosition();
  latitude.value = position.coords.latitude;
  longitude.value = position.coords.longitude;
}
</script>

<template>
  <div>
    <p>Latitude: {{ latitude }}</p>
    <p>Longitude: {{ longitude }}</p>
    <button @click="getCurrentPosition">Get Location</button>
  </div>
</template>
```

#### Wrapping Plugins in Composables (Recommended)

Wrapping Capacitor plugins in composables provides reusability, encapsulated reactive state, and automatic cleanup:

```typescript
// src/composables/useCamera.ts
import { ref } from 'vue';
import { Camera, CameraResultType, CameraSource } from '@capacitor/camera';
import type { Photo } from '@capacitor/camera';

export function useCamera() {
  const photo = ref<Photo | null>(null);
  const error = ref<string | null>(null);

  async function takePhoto(): Promise<void> {
    try {
      error.value = null;
      photo.value = await Camera.getPhoto({
        quality: 90,
        allowEditing: false,
        resultType: CameraResultType.Uri,
        source: CameraSource.Camera,
      });
    } catch (e) {
      error.value = e instanceof Error ? e.message : String(e);
    }
  }

  async function pickFromGallery(): Promise<void> {
    try {
      error.value = null;
      photo.value = await Camera.getPhoto({
        quality: 90,
        allowEditing: false,
        resultType: CameraResultType.Uri,
        source: CameraSource.Photos,
      });
    } catch (e) {
      error.value = e instanceof Error ? e.message : String(e);
    }
  }

  return {
    photo,
    error,
    takePhoto,
    pickFromGallery,
  };
}
```

Use the composable in a component:

```vue
<script setup lang="ts">
import { useCamera } from '@/composables/useCamera';

const { photo, error, takePhoto } = useCamera();
</script>

<template>
  <div>
    <button @click="takePhoto">Take Photo</button>
    <p v-if="error">Error: {{ error }}</p>
    <img v-if="photo?.webPath" :src="photo.webPath" alt="Captured photo" />
  </div>
</template>
```

### Step 5: Plugin Event Listeners with Lifecycle Hooks

Capacitor plugin event listeners must be registered in `onMounted` and removed in `onUnmounted` to prevent memory leaks. Vue's reactivity system picks up `ref` changes automatically, so there is no NgZone-equivalent issue — but cleanup is still critical.

#### Composable with Automatic Cleanup

```typescript
// src/composables/useNetwork.ts
import { ref, onMounted, onUnmounted } from 'vue';
import { Network } from '@capacitor/network';
import type { ConnectionStatus } from '@capacitor/network';
import type { PluginListenerHandle } from '@capacitor/core';

export function useNetwork() {
  const status = ref<ConnectionStatus | null>(null);
  let listenerHandle: PluginListenerHandle | null = null;

  onMounted(async () => {
    status.value = await Network.getStatus();
    listenerHandle = await Network.addListener('networkStatusChange', (newStatus) => {
      status.value = newStatus;
    });
  });

  onUnmounted(async () => {
    await listenerHandle?.remove();
  });

  return {
    status,
  };
}
```

Usage in a component:

```vue
<script setup lang="ts">
import { useNetwork } from '@/composables/useNetwork';

const { status } = useNetwork();
</script>

<template>
  <p v-if="status">Network: {{ status.connected ? 'Online' : 'Offline' }}</p>
</template>
```

#### App-Wide Listeners via App.v