Konversi Aplikasi Nuxt Anda ke iOS & Android dengan Capacitor 8

Pendahuluan

Sudah punya aplikasi web Nuxt? Di panduan ini, Anda akan mempelajari cara mengubahnya menjadi aplikasi mobile native iOS dan Android menggunakan Capacitor 8 — versi terbaru dengan performa yang lebih baik dan fitur-fitur baru.

Capacitor membungkus web app Anda dalam container native, memberi akses ke API perangkat seperti kamera, filesystem, dan push notifications tanpa mengubah codebase Vue Anda. Berbeda dengan Flutter atau React Native, Anda tidak perlu menulis ulang apa pun — code Nuxt Anda berjalan apa adanya.

Yang akan Anda pelajari:

Konfigurasi aplikasi Nuxt Anda yang sudah ada untuk static generation
Tambahkan Capacitor 8 dengan plugin native esensial
Build dan test di simulator iOS dan Android
Aktifkan live reload untuk development yang lebih cepat
Perbaiki masalah layout iOS yang umum (viewport, safe area, horizontal overflow)
Tambahkan UI yang terasa native dengan Capgo Native Navigation dan Transitions

Ingin mulai proyek baru dari nol? Cek panduan kami tentang Membangun Aplikasi Mobile Nuxt dari Nol.

Keuntungan Menggunakan Nuxt dan Capacitor

Reusability dengan Code: Bagikan komponen Vue dan logika Anda di antara aplikasi web dan mobile.
Performa: Static generation Nuxt menghasilkan bundle optimal yang sempurna untuk mobile.
Kemampuan Native: Akses fitur perangkat seperti kamera, geolocation, dan filesystem melalui plugin Capacitor.
Pengembangan Lebih Simpel: Gunakan pola Vue/Nuxt yang sudah familiar tanpa harus belajar native development.

Prerequisites

Sebelum memulai, pastikan Anda sudah memiliki:

Node.js 18+ terinstal
Yang sudah ada Nuxt 4 aplikasi
Xcode (untuk pengembangan iOS, khusus macOS)
Android Studio (untuk pengembangan Android)

Konfigurasi Aplikasi Nuxt Anda untuk Mobile

Langkah pertama adalah mengonfigurasi aplikasi Nuxt Anda untuk static generation. Capacitor membutuhkan file HTML/JS/CSS statis untuk di-bundle ke dalam native app.

Make sure your package.json memiliki script generate:

{
  "scripts": {
    "dev": "nuxt dev",
    "build": "nuxt build",
    "generate": "nuxt generate",
    "preview": "nuxt preview",
    "mobile": "bun run generate && bunx cap sync",
    "mobile:ios": "bun run mobile && bunx cap open ios",
    "mobile:android": "bun run mobile && bunx cap open android"
  }
}

Penting: Jika Anda menggunakan fitur server-side (API routes, server middleware, dll.), Anda perlu melakukan refactor ke alternatif client-side atau API eksternal.

Tes static generation dengan menjalankan:

bun run generate

Anda akan melihat .output/public folder berisi file statis Anda. Inilah yang akan di-bundle oleh Capacitor ke dalam native app Anda.

Menambahkan Capacitor 8 ke Project Anda

Untuk membungkus app Nuxt Anda ke dalam container mobile native, ikuti langkah-langkah ini:

Install Capacitor core dan CLI:

bun add @capacitor/core
bun add -D @capacitor/cli

Install plugin Capacitor umum yang mungkin Anda butuhkan:

bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/status-bar @capacitor/preferences

Plugin-plugin ini menyediakan fitur esensial:

@capacitor/app: Menangani app lifecycle events (foreground/background, deep links)
@capacitor/keyboard: Mengontrol perilaku keyboard di mobile
@capacitor/splash-screen: Mengelola splash screen native
@capacitor/status-bar: Atur gaya status bar perangkat
@capacitor/preferences: Penyimpanan key-value (seperti localStorage tapi native)

Inisialisasi Capacitor dengan detail proyek Anda:

bunx cap init my-app com.example.myapp --web-dir .output/public

Ganti my-app dengan nama aplikasi Anda dan com.example.myapp dengan app ID Anda (notasi reverse domain).

Buat atau perbarui capacitor.config.ts file dengan konfigurasi yang tepat:

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

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: '.output/public',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      splashFullScreen: true,
      splashImmersive: true,
    },
    Keyboard: {
      resize: 'body',
      resizeOnFullScreen: true,
    },
    StatusBar: {
      style: 'dark',
    },
  },
};

export default config;

Instal platform native:

bun add @capacitor/ios @capacitor/android

Tambahkan folder platform native:

bunx cap add ios
bunx cap add android

Capacitor akan membuat ios dan android folder di root proyek yang berisi proyek native.

Untuk build proyek Android, Anda butuh Android Studio. Untuk iOS, Anda butuh Mac dengan Xcode.

Build dan sync proyek Anda:

bun run mobile

Ini menjalankan skrip kustom Anda untuk membuat build statis Nuxt dan menyinkronkan file ke platform native.

Build dan Deploy Native Apps

Untuk build dan deploy native mobile app Anda, ikuti langkah-langkah ini:

Untuk mengembangkan aplikasi iOS, Anda perlu memiliki Xcode terinstal, dan untuk aplikasi Android, Anda perlu memiliki Android Studio terinstal. Selain itu, jika Anda berencana mendistribusikan aplikasi di app store, Anda perlu mendaftar di Apple Developer Program untuk iOS dan Google Play Console untuk Android.

Buka project native:

Untuk iOS:

bun run mobile:ios

Untuk Android:

bun run mobile:android

Atau langsung dengan Capacitor CLI:

bunx cap open ios
bunx cap open android

Build dan jalankan app:

android-studio-run

Di Android Studio, tunggu hingga proyek siap, lalu klik tombol “Run” untuk deploy aplikasi ke perangkat yang terhubung atau emulator.

xcode-run

Di Xcode, atur signing account Anda untuk deploy aplikasi ke perangkat asli. Jika belum pernah melakukannya, Xcode akan memandu Anda (perlu dicatat Anda harus terdaftar di Apple Developer Program). Setelah selesai, klik tombol “Play” untuk menjalankan aplikasi di perangkat Anda.

Selamat! Anda telah berhasil deploy web app Nuxt ke perangkat mobile.

Tapi tunggu dulu, ada cara yang lebih cepat untuk melakukan ini saat development…

Live Reload Capacitor

Selama development, Anda bisa memanfaatkan live reloading untuk melihat perubahan secara instan di perangkat mobile. Untuk mengaktifkan fitur ini, ikuti langkah berikut:

Cari alamat IP lokal Anda:

Di macOS, jalankan perintah berikut di terminal:
```
ipconfig getifaddr en0
```
Di Windows, jalankan:
```
ipconfig
```
Cari alamat IPv4 pada output tersebut.

Perbarui file capacitor.config.ts untuk mengarah ke server development Anda:

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

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: '.output/public',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
  plugins: {
    // ... your plugin config
  },
};

export default config;

Ganti YOUR_IP_ADDRESS dengan alamat IP lokal Anda (misalnya, 192.168.1.100).

Terapkan perubahan ke proyek native Anda:

bunx cap copy

Panduan copy perintah ini menyalin folder web dan perubahan konfigurasi ke proyek native tanpa memperbarui seluruh proyek.

Jalankan Nuxt dev server dan rebuild di Xcode/Android Studio:

bun run dev

Sekarang, setiap kali Anda mengubah aplikasi Nuxt, aplikasi mobile akan otomatis reload untuk menerapkan perubahan tersebut.

Catatan: Jika Anda menginstal plugin baru atau mengubah file native, Anda perlu rebuild project native karena live reloading hanya berlaku untuk perubahan web code.

Menggunakan Plugin Capacitor

Plugin Capacitor memungkinkan Anda mengakses fitur native perangkat dari aplikasi Nuxt Anda. Mari kita pelajari cara menggunakan plugin Share sebagai contoh:

Instal plugin Share:

bun add @capacitor/share

Buat atau perbarui halaman untuk menggunakan plugin Share. Di Nuxt 4, halaman berada di app/pages/:

<template>
  <div class="p-6">
    <h1 class="text-2xl font-bold mb-4">Welcome to Nuxt + Capacitor!</h1>
    <button
      @click="shareContent"
      class="px-6 py-3 bg-blue-600 text-white rounded-lg font-semibold"
    >
      Share now!
    </button>
  </div>
</template>

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

async function shareContent() {
  await Share.share({
    title: 'Check this out!',
    text: 'Built with Nuxt and Capacitor',
    url: 'https://capacitorjs.com',
    dialogTitle: 'Share with friends',
  });
}
</script>

Sinkronkan perubahan dengan proyek native:

bun run mobile

Atau cukup sinkronkan tanpa rebuild:

bunx cap sync

Rebuild dan jalankan aplikasi di perangkat Anda.

Sekarang, saat Anda mengklik tombol “Share now!”, dialog share native akan muncul.

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, tapi integrasinya dengan Nuxt itu hacky dan jarang worth it saat Anda sudah punya Tailwind CSS.

Untuk tampilan mobile native di aplikasi Nuxt + 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. Nuxt router Anda menyimpan 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 app/assets/css/main.css:

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

Untuk Nuxt 4 dengan Tailwind CSS 4, pertahankan import ini di file CSS yang direferensikan dari nuxt.config.ts.

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 Nuxt 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

Di nuxt.config.ts, atur viewport melalui app.head:

export default defineNuxtConfig({
  app: {
    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,
#__nuxt {
  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: 'out',
  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

Anda telah berhasil mengonversi aplikasi web Nuxt yang sudah ada menjadi aplikasi native iOS dan Android menggunakan Capacitor 8. Codebase Vue Anda kini berjalan secara native di perangkat mobile dengan akses ke API perangkat.

Apa yang telah Anda capai:

Konfigurasi Nuxt untuk static generation
Menambahkan Capacitor 8 dengan plugin esensial
Build dan deploy ke simulator iOS dan Android
Mengaktifkan live reload untuk development
Memperbaiki masalah layout iOS umum (viewport, safe area, overflow)
Menambahkan UI rasa native dengan Capgo Native Navigation dan Transitions

Next steps:

Siapkan Capgo untuk update over-the-air tanpa perlu submit ulang ke app store
Tambah plugin native lainnya seperti Camera, Geolocation, atau Push Notifications
Konfigurasi ikon aplikasi dan splash screen untuk produksi
Siapkan aplikasi Anda untuk submit ke App Store dan Google Play

Mau mulai proyek baru? Cek di sini Membangun Aplikasi Mobile Nuxt dari Nol untuk panduan langkah demi langkah.

Sumber Daya

Dokumentasi Nuxt
Dokumentasi Capacitor 8
@capgo/capacitor-native-navigation — Liquid Glass tab bar dan native chrome
@capgo/capacitor-transitions — transisi halaman yang terasa native
@capgo/tailwind-capacitor — utilitas Tailwind safe-area untuk Capacitor
Capgo - Live Updates untuk Aplikasi Capacitor

Pelajari cara Capgo membantu Anda membangun aplikasi lebih baik dan cepat, daftar akun gratis sekarang hari ini.

Lanjutkan dari Convert Your Nuxt App to iOS & Android with Capacitor 8

Jika Anda menggunakan Konversi App Nuxt Kamu ke iOS & Android dengan Capacitor 8 untuk merencanakan pekerjaan plugin native, hubungkan dengan Direktori Plugin Capgo untuk alur kerja produk di Direktori Plugin Capgo, Plugin Capacitor oleh Capgo untuk detail implementasi pada Capacitor Plugins oleh Capgo Menambahkan atau Memperbarui Plugin untuk detail implementasi pada Menambahkan atau Memperbarui Plugin, Alternatif Plugin Ionic Enterprise untuk alur kerja produk di alternatif plugin Ionic Enterprise, dan Capgo Native Build untuk alur kerja produk di Capgo Native Builds.