Membangun Aplikasi Mobile dengan Vue dan Capacitor

Dalam tutorial ini, kami akan memandu Anda mengubah aplikasi web Vue menjadi aplikasi mobile native menggunakan Capacitor. Anda juga bisa menambahkan Capgo Native Navigation dan Transitions agar terasa lebih native, serta menggunakan tailwind-capacitor untuk safe areas.

Tentang Capacitor

Capacitor adalah tool revolusioner yang memudahkan Anda mengintegrasikannya ke proyek web apa pun untuk mengubah aplikasi menjadi mobile app native. Tool ini membuatkan proyek Xcode dan Android Studio native untuk Anda serta menyediakan akses ke fitur perangkat native seperti kamera melalui JavaScript bridge.

Mempersiapkan Aplikasi Vue Anda

Pertama, buat aplikasi Vue baru dengan menjalankan perintah berikut:

vue create my-app
cd my-app
npm install

Untuk menyiapkan aplikasi Vue Anda untuk deployment mobile native, Anda perlu mengekspor proyek Anda. Tambahkan script di file package.json Anda untuk build dan menyalin proyek Vue:

{
  "scripts": {
    // ...
    "build": "vue-cli-service build"
  }
}

Setelah menjalankan perintah build , Anda seharusnya melihat folder baru dist di direktori root proyek Anda. Folder ini akan digunakan oleh Capacitor nanti.

Menambahkan Capacitor ke Aplikasi Vue Anda

Untuk mengubah aplikasi web Vue Anda menjadi kontainer mobile native, ikuti langkah-langkah berikut:

Instal Capacitor CLI sebagai dependensi development dan konfigurasikan di dalam proyek Anda. Terima nilai default untuk nama dan bundle ID saat setup.
Instal paket inti serta paket yang relevan untuk platform iOS dan Android.
Tambahkan platform, dan Capacitor akan membuat folder untuk setiap platform di root proyek Anda:

# Install the Capacitor CLI locally
npm install -D @capacitor/cli

# Initialize Capacitor in your Vue project
npx cap init

# Install the required packages
npm install @capacitor/core @capacitor/ios @capacitor/android

# Add the native platforms
npx cap add ios
npx cap add android

Sekarang Anda akan melihat folder iOS dan Android yang baru di proyek Vue Anda.

Perbarui capacitor.config.json untuk mengarahkan webDir ke hasil perintah build Anda:

{
  "appId": "com.example.app",
  "appName": "my-app",
  "webDir": "dist"
}

Sekarang, Anda bisa build proyek Vue dan menyinkronkannya dengan Capacitor:

npm run build
npx cap sync

Build dan Deploy Aplikasi Native

Untuk mengembangkan aplikasi iOS, Anda perlu menginstal Xcode, dan untuk aplikasi Android, Anda perlu menginstal Android Studio. Selain itu, Anda perlu mendaftar ke Apple Developer Program untuk iOS dan Google Play Console untuk Android agar dapat mendistribusikan aplikasi Anda di toko aplikasi.

Gunakan Capacitor CLI untuk membuka kedua proyek native:

npx cap open ios
npx cap open android

Deploy aplikasi Anda ke perangkat yang terhubung menggunakan Android Studio atau Xcode.

Live Reload Capacitor

Aktifkan live reload pada perangkat mobile Anda dengan membuat aplikasi Capacitor memuat konten dari URL tertentu di jaringan Anda.

Cari alamat IP lokal Anda dan perbarui capacitor.config.ts file dengan IP dan port yang benar:

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'dist',
  bundledWebRuntime: false,
  server: {
    url: 'http://192.168.x.xx:8080',
    cleartext: true
  }
};

export default config;

Terapkan perubahan ini dengan menyalinnya ke proyek native Anda:

npx cap copy

Sekarang, aplikasi Anda akan otomatis reload dan menampilkan perubahan saat Anda memperbarui aplikasi Vue Anda.

Menggunakan Plugin Capacitor

Instal plugin Capacitor, seperti plugin Share, dan gunakan di aplikasi Vue Anda:

npm i @capacitor/share

Import package dan panggil share() fungsi di aplikasi Anda:

<template>
  <div>
    <h1>Welcome to Vue and Capacitor!</h1>
    <button @click="share">Share now!</button>
  </div>
</template>

<script setup lang="ts">
import { Share } from '@capacitor/share';

async function share() {
  await Share.share({
    title: 'Open Youtube',
    text: 'Check new video on youtube',
    url: 'https://www.youtube.com',
    dialogTitle: 'Share with friends'
  });
}
</script>

Setelah menginstal plugin baru, jalankan sync perintah dan deploy ulang aplikasi ke perangkat Anda:

npx cap sync

Selanjutnya, Anda bisa membuat aplikasi terasa lebih native di iOS dan Android dengan navigasi dan transisi Capgo, serta memperbaiki masalah layout iOS yang umum menyebabkan horizontal overflow atau safe area terpotong.

Saya sudah bertahun-tahun bekerja dengan Ionic untuk membangun aplikasi cross-platform, tetapi mengintegrasikannya dengan Vue terasa hacky dan jarang sepadan jika Anda sudah menggunakan Tailwind CSS.

Untuk feel mobile native di aplikasi Vue + Capacitor, gunakan plugin Capgo alih-alih UI kit khusus web seperti Konsta UI:

@capgo/capacitor-native-navigation — navbar native, Liquid Glass tab bar di iOS, dan gaya tab bar blur di Android. Vue router Anda tetap memegang state route; plugin yang mengurus native chrome.
@capgo/capacitor-transitions — transisi halaman ala Ionic dan fitur iOS edge swipe-back di layer WebView, tanpa harus memakai Ionic UI.

Install keduanya:

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

Konfigurasi navigasi native dengan mode inset CSS agar konten web menyesuaikan dengan bar native:

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

Render Liquid Glass tab bar (iOS menggunakan rendering dari sistem; Android menggunakan backdrop WebView yang blur):

await NativeNavigation.setTabbar({
  selectedId: 'home',
  labelVisibilityMode: 'labeled',
  icons: true,
  colors: { dynamic: true },
  tabs: [
    { id: 'home', title: 'Home', icon: { svg: '...' } },
    { id: 'settings', title: 'Settings', icon: { svg: '...' } },
  ],
});

await NativeNavigation.addListener('tabSelect', ({ id }) => {
  router.push(`/${id}`);
});

Tambahkan transisi halaman native di app shell Anda:

<script setup>
import { ref, onMounted } from 'vue';
import { useRouter } from 'vue-router';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/vue';

initTransitions({ platform: 'auto' });

const router = useRouter();
const outletRef = ref(null);

onMounted(() => {
  if (outletRef.value) {
    setupRouterOutlet(outletRef.value, { platform: 'auto', swipeGesture: 'auto' });
  }
});

const openSettings = () => {
  setDirection('forward');
  router.push('/settings');
};
</script>

<template>
  <cap-router-outlet ref="outletRef">
    <router-view />
  </cap-router-outlet>
</template>

Bungkus halaman yang di-route dengan cap-router-outlet, cap-page, dan cap-content, dan panggil setDirection('forward') atau setDirection('back') sebelum navigasi. Jangan duplikasi header atau footer web kalau navigasi native sudah menangani area tersebut.

Lihat panduan lengkapnya: Menggunakan @capgo/capacitor-native-navigation dan Menggunakan @capgo/capacitor-transitions.

Safe areas dengan Tailwind

Untuk safe area perangkat di Tailwind CSS, gunakan @capgo/tailwind-capacitor (diterbitkan sebagai tailwind-capacitor pada npm). Ini menyediakan safe-areas utilitas dan plugin Tailwind lain yang kompatibel dengan Capacitor:

bun add -D tailwind-capacitor

Di src/assets/main.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

Gunakan utilitas seperti pt-safe, pb-safe, dan px-safe daripada menyisipkan env(safe-area-inset-*) secara manual. Proyek ini dikembangkan secara aktif — jika ada yang kurang untuk setup Vue Anda, buka PR di GitHub.

Memperbaiki Masalah Layout iOS (Viewport, Safe Area, dan Horizontal Overflow)

Jika konten terlihat terpotong, bergeser, atau bisa di-scroll secara horizontal di iOS, menambahkan lebih banyak overflow-x: hidden atau hanya mengutak-atik tag viewport saja biasanya tidak memperbaikinya. Lakukan pemeriksaan ini secara berurutan.

Pastikan meta tag viewport diterapkan dengan benar

Tambahkan viewport meta tag di index.html di dalam <head>:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

Tangani iOS safe area hanya dari satu root wrapper

Buat satu app shell dan terapkan safe area padding di sana — bukan di beberapa komponen bersarang:

html,
body,
#app {
  width: 100%;
  min-height: 100%;
  margin: 0;
  padding: 0;
  overflow-x: hidden;
}

* {
  box-sizing: border-box;
}

.app-shell {
  min-height: 100dvh;
  width: 100%;
  padding-top: env(safe-area-inset-top);
  padding-right: env(safe-area-inset-right);
  padding-bottom: env(safe-area-inset-bottom);
  padding-left: env(safe-area-inset-left);
}

Bungkus seluruh konten halaman di dalam .app-shell. Padding safe-area yang dobel di header, modal, dan wrapper layout sering membuat UI terlihat terpotong atau terlalu besar.

Dengan @capgo/tailwind-capacitor, Anda bisa menggunakan padding yang sama dengan utility seperti pt-safe pb-safe px-safe pada satu shell tersebut.

Atur Capacitor iOS `contentInset` ke `never` dulu

Di capacitor.config.ts, lebih baik nonaktifkan native inset dan biarkan CSS (atau Native Navigation’s contentInsetMode: 'css') mengatur safe area:

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

Mencampur automatic content inset dari Capacitor dengan CSS env(safe-area-inset-*) padding sering kali menjadi penyebab spasi ganda.

Temukan elemen yang benar-benar overflow

Penyebab umumnya adalah elemen yang menggunakan 100vw, Tailwind w-screen, lebar pixel tetap, atau ukuran yang besar min-width.

Di Safari Web Inspector, jalankan:

[...document.querySelectorAll('*')]
  .filter(el => el.scrollWidth > document.documentElement.clientWidth)
  .map(el => ({
    el,
    tag: el.tagName,
    class: el.className,
    scrollWidth: el.scrollWidth,
    clientWidth: document.documentElement.clientWidth,
  }));

Dengan Tailwind, ganti w-screen dengan w-full jika memungkinkan. Banyak masalah overflow horizontal berasal dari 100vw / w-screen, duplikasi safe-area padding, atau container berukuran tetap — bukan dari viewport meta tag itu sendiri.

Kesimpulan

Capacitor adalah opsi hebat untuk membangun aplikasi native dari proyek web yang sudah ada. Dengan tambahan Capgo, menambahkan Live Updates ke aplikasi Anda jadi lebih mudah, sehingga pengguna selalu mendapat fitur terbaru dan perbaikan bug.

Learn how Capgo can help you build better apps faster, sign up for a free account hari ini.

Lanjutkan dari Building Mobile Apps with Vue and Capacitor

Jika Anda menggunakan Membangun Aplikasi Mobile dengan Vue dan Capacitor untuk merencanakan perilaku media dan antarmuka native, hubungkan dengan Menggunakan @capgo/capacitor-live-activities untuk kemampuan native di Menggunakan @capgo/capacitor-live-activities, @capgo/capacitor-live-activities untuk detail implementasi di @capgo/capacitor-live-activities, Menggunakan @capgo/capacitor-video-player untuk kapabilitas native saat menggunakan @capgo/capacitor-video-player, @capgo/capacitor-video-player untuk detail implementasi di @capgo/capacitor-video-player, dan Menggunakan @capgo/capacitor-native-navigation untuk kapabilitas native saat menggunakan @capgo/capacitor-native-navigation.