Konversi Aplikasi Nuxt Anda ke iOS & Android dengan Capacitor 8

Pendahuluan

Sudah memiliki aplikasi web Nuxt? Dalam panduan ini, Anda akan belajar bagaimana mengubahnya menjadi aplikasi mobile native iOS dan Android menggunakan Capacitor 8 — versi terbaru dengan kinerja yang lebih baik dan fitur baru.

Capacitor menggabungkan aplikasi web Anda ke dalam kontainer native, memberikan akses ke API perangkat seperti kamera, sistem file, dan pemberitahuan push sambil menjaga kodebase Vue yang sudah ada. Berbeda dengan Flutter atau React Native, Anda tidak perlu menulis ulang apa pun — aplikasi Nuxt code berjalan seperti semula.

Apa yang akan Anda pelajari:

Konfigurasi aplikasi Nuxt yang sudah ada untuk penghasilan statik
Tambahkan Capacitor 8 dengan plugin native yang penting
Bangun dan tes pada simulator iOS dan Android
Aktifkan ulang muat untuk pengembangan yang lebih cepat
Perbaiki masalah tata letak iOS yang umum (viewport, area aman, keluaran horizontal)
Tambahkan antarmuka yang terasa native dengan Capgo Native Navigation dan Transisi

Mencari proyek baru dari awal? Periksa panduan kami tentang Membangun Aplikasi Mobile Nuxt dari Awal.

Manfaat Menggunakan Nuxt dan Capacitor

Reusabilitas Code: Bagikan komponen Vue dan logika antara aplikasi web dan mobile.
Kinerja: Penggabungan statis Nuxt menciptakan bundle yang dioptimalkan sempurna untuk mobile.
Kemampuan Asli: Akses fitur perangkat seperti kamera, lokasi geografis, dan sistem file melalui Capacitor plugin.
Pengembangan yang Sederhana: Gunakan pola Vue/Nuxt yang familiar tanpa perlu belajar pengembangan native.

Persyaratan Sebelumnya

: Pastikan Anda telah memenuhi syarat-syarat berikut sebelum memulai:

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

Mengonfigurasi Aplikasi Nuxt Anda untuk Mobile

Langkah pertama adalah mengonfigurasi aplikasi Nuxt Anda untuk pengembangan statis. Capacitor memerlukan file HTML/JS/CSS statis untuk dijadikan aplikasi native.

Pastikan Anda memiliki package.json mengandung skrip 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"
  }
}

Perlu diingat: Jika Anda menggunakan fitur sisi server (API rute, middleware server, dll.), Anda perlu meredefinisikan fitur-fitur tersebut untuk menggunakan alternatif sisi klien atau API eksternal.

Tes generasi statis dengan menjalankan:

bun run generate

Anda harus melihat sebuah .output/public folder dengan file-file statis Anda. Ini adalah apa Capacitor akan bundel ke dalam aplikasi native Anda.

Menambahkan Capacitor 8 ke Projek Anda

Untuk mengemas aplikasi Nuxt Anda ke dalam kontainer mobile native, ikuti langkah-langkah berikut:

Pasang Capacitor core dan CLI:

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

Pasang plugin-plugin Capacitor umum yang Anda mungkin butuhkan:

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

Plugin-plugin ini menyediakan fitur-fitur penting:

@capacitor/app: Menghandle kejadian siklus aplikasi (depan/belakang, tautan dalam)
@capacitor/keyboard: Mengontrol perilaku keyboard di mobile
@capacitor/splash-screen: Atur layar splash native
@capacitor/status-bar: Gaya baris status perangkat
@capacitor/preferences: Penyimpanan nilai kunci (seperti localStorage tetapi 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 ID aplikasi Anda (notasi domain terbalik).

Buat atau perbarui file capacitor.config.ts 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;

Instalasi platform native:

bun add @capacitor/ios @capacitor/android

Tambahkan folder-folder platform native:

bunx cap add ios
bunx cap add android

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

Untuk membangun proyek Android, Anda membutuhkan Android Studio. Untuk iOS, Anda membutuhkan Mac dengan Xcode.

Pembangunan dan Pengiriman Aplikasi Native

bun run mobile

Membangun dan sinkronisasi proyek Anda:

Langkah ini menjalankan skrip kustom Anda yang menghasilkan build statis Nuxt dan sinkronisasi file dengan platform native.

Untuk membangun dan mengirimkan aplikasi seluler native Anda, ikuti langkah-langkah berikut:

Untuk mengembangkan aplikasi iOS, Anda memerlukan Xcode terpasang, dan untuk aplikasi Android, Anda memerlukan Android Studio terpasang. Selain itu, jika Anda berencana untuk mendistribusikan aplikasi Anda di toko aplikasi, Anda memerlukan mendaftar ke Program Pengembang Apple untuk iOS dan Google Play Console untuk Android.

Buka proyek-proyek 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

Buat dan jalankan aplikasi:

android-studio-run

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

xcode-run

Pada Xcode, atur akun tanda tangan Anda untuk mengirimkan aplikasi ke perangkat nyata. Jika Anda belum pernah melakukannya sebelumnya, Xcode akan mengantarkan Anda melalui proses (perlu diingat bahwa Anda harus terdaftar dalam Program Pengembang Apple). Setelah diatur, klik tombol “Play” untuk menjalankan aplikasi pada perangkat yang terhubung.

Selamat! Anda telah berhasil mengirimkan aplikasi web Nuxt ke perangkat mobile.

Tapi tunggu dulu, ada cara yang lebih cepat untuk melakukannya selama pengembangan…

Capacitor Live Reload

Pada pengembangan, Anda dapat memanfaatkan live reloading untuk melihat perubahan secara instan pada perangkat mobile. Untuk mengaktifkan fitur ini, ikuti langkah-langkah berikut:

Cari alamat IP lokal Anda:

Pada macOS, jalankan perintah berikut di terminal:
```
ipconfig getifaddr en0
```
Pada Windows, jalankan:
```
ipconfig
```
Cari alamat IPv4 di hasilnya.

Perbarui pengaturan Anda capacitor.config.ts untuk mengarah ke server pengembangan 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 asli Anda:

bunx cap copy

Perintah copy mengcopy folder web dan perubahan konfigurasi ke proyek asli tanpa mengupdate proyek seluruhnya.

Mulai server pengembangan Nuxt Anda dan rebuild di Xcode/Android Studio:

bun run dev

Sekarang, setiap kali Anda membuat perubahan pada aplikasi Nuxt Anda, aplikasi mobile akan secara otomatis reload untuk menampilkan perubahan tersebut.

Perlu diingat: Jika Anda menginstal plugin baru atau membuat perubahan pada file native, Anda perlu rebuild proyek native karena pengaturan reload hidup hanya berlaku untuk perubahan web code.

Menggunakan Capacitor Plugin

Capacitor plugin memungkinkan Anda mengakses fitur perangkat native dari aplikasi Nuxt Anda. Mari kita jelajahi cara menggunakan plugin Bagikan plugin sebagai contoh:

Pasang plugin Bagikan:

bun add @capacitor/share

Buat atau perbarui halaman untuk menggunakan plugin Bagikan. 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 hanya sinkronkan tanpa membangun ulang:

bunx cap sync

Buat ulang dan jalankan aplikasi di perangkat Anda.

Sekarang, ketika Anda mengklik tombol “Bagikan sekarang!”, dialog bagikan native akan muncul.

Selanjutnya, Anda dapat membuat aplikasi terasa lebih native di iOS dan Android dengan Capgo navigasi dan transisi, dan memperbaiki masalah layout iOS yang umum menyebabkan overflow horizontal atau area aman yang dipotong.

Saya telah bekerja selama tahun-tahun dengan Untuk membangun aplikasi multi-platform, tetapi mengintegrasikannya dengan Nuxt adalah sulit dan jarang berharga ketika Anda sudah memiliki Untuk tampilan mobile asli di aplikasi Nuxt + __CAPGO_KEEP_0__ gunakan plugin __CAPGO_KEEP_1__ bukan kit UI web seperti Konsta UI: @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation.

For a native mobile feel in a Nuxt + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:

@capgo/capacitor-transitions — transisi halaman Ionic dan swipe balik iOS di layer WebView, tanpa menerima UI Ionic.
@capgo/capacitor-transitions Konfigurasi navigasi native dengan mode CSS inset agar konten web menghormati bar-bar native:

Tampilkan tab bar Liquid Glass (iOS menggunakan rendering yang dimiliki sistem; Android menggunakan latar belakang WebView yang terblurr):

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

Tambahkan transisi halaman native di shell aplikasi:

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

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

Untuk membangun aplikasi multi-platform, tetapi mengintegrasikannya dengan Nuxt adalah sulit dan jarang berharga ketika Anda sudah memiliki Tailwind CSS

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}`);
});

Untuk tampilan mobile asli di aplikasi Nuxt + __CAPGO_KEEP_0__ gunakan plugin __CAPGO_KEEP_1__ bukan kit UI web seperti Konsta UI:

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

Terapungkan halaman yang diarahkan dalam cap-router-outlet, cap-page, dan cap-content, dan panggil setDirection('forward') atau setDirection('back') sebelum berpindah. Jangan duplikat header atau footer web ketika navigasi asli menguasai permukaan tersebut.

Lihat panduan lengkap: Menggunakan @capgo/capacitor-navigasi-asli dan Menggunakan @capgo/capacitor-transisi.

Area yang aman dengan Tailwind

Untuk area yang aman perangkat dalam Tailwind CSS, gunakan @capgo/tailwind-capacitor (diterbitkan sebagai tailwind-capacitor pada npm). Ini menyediakan safe-areas utilitas dan plugin lainnya yang Capacitor-friendly Tailwind:

bun add -D tailwind-capacitor

Dalam 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, pastikan untuk menyimpan import ini di file CSS yang digunakan sebagai referensi nuxt.config.ts.

Gunakan utilitas seperti pt-safe, pb-safe, dan px-safe dibandingkan dengan menambahkannya env(safe-area-inset-*) secara manual. Projek ini aktif dikembangkan — jika ada sesuatu yang hilang untuk konfigurasi Nuxt Anda, buka PR di GitHub.

Mengatasi Masalah Layout iOS (Viewport, Area Aman, dan Horizontal Overflow)

Jika konten terlihat dipotong, bergeser, atau dapat di-scroll secara horizontal di iOS, tambahkan overflow-x: hidden atau mengatur tag viewport sendiri biasanya tidak dapat memperbaiki masalah ini. Jalankan periksaan-periksaan ini secara berurutan.

Pastikan tag meta 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 area aman iOS dari wrapper root saja

Buat shell aplikasi tunggal dan aplikasikan padding area aman di sana — bukan di komponen-komponen nested yang banyak:

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 semua konten halaman di dalam .app-shellPengaturan padding area aman yang berulang di header, modal, dan wrapper layout sering membuat UI terlihat dipotong atau terlalu besar.

Dengan @capgo/tailwind-capacitor, Anda dapat mengungkapkan padding yang sama dengan utilitas seperti pt-safe pb-safe px-safe di shell tunggal tersebut.

Set Capacitor iOS menjadi `contentInset` ke `never` pertama

Di capacitor.config.ts, lebih baik menggunakan inset native dan biarkan CSS (atau Native Navigation’s contentInsetMode: 'css') mengontrol area yang aman:

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

Menggabungkan Capacitor’s automatic content inset dengan CSS env(safe-area-inset-*) padding adalah penyebab umum dari jarak ganda.

Temukan elemen yang benar-benar mengalir keluar

Penyebab biasanya adalah elemen yang menggunakan 100vw, Tailwind w-screen, lebar piksel tetap, atau besar min-width.

In 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 ketika memungkinkan. Banyak masalah overflow horizontal berasal dari 100vw / w-screenpadding area yang aman yang diulang, atau kontainer dengan lebar tetap — bukan dari tag meta viewport itu sendiri.

Kesimpulan

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

Apa yang Anda capai:

Mengonfigurasi Nuxt untuk pengembangan statis
Menambahkan Capacitor 8 dengan plugin yang penting
Membangun dan mengirimkan ke simulator iOS dan Android
Mengaktifkan reload hidup untuk pengembangan
Masalah tata letak iOS umum telah diperbaiki (viewport, area aman, overflow)
Tampilan UI yang terasa asli dengan Capgo Navigasi dan Transisi Native

Langkah-langkah selanjutnya:

Konfigurasi Capgo untuk pembaruan melalui udara tanpa resubmission ke toko aplikasi
Tambahkan lebih banyak plugin native seperti Kamera, Lokasi, atau Notifikasi Push
Konfigurasi ikon aplikasi dan layar splash untuk produksi
Persiapkan aplikasi Anda untuk pengajuan ke App Store dan Google Play

Membuat proyek baru? Cek Membangun Aplikasi Mobile Nuxt dari Awal untuk panduan langkah demi langkah.

Sumber Daya

Documentasi Nuxt
Capacitor 8 Dokumentasi
@capgo/capacitor-navigasi native — Boks Tab Liquid Glass dan Chrome Native
@capgo/capacitor-transisi — Transisi Halaman yang Terasa Sama dengan Native
@capgo/tailwind-capacitor — Utilitas Area yang Aman dari Tailwind untuk Capacitor
Capgo - Update Hidup untuk Aplikasi Capacitor

Belajar bagaimana Capgo dapat membantu Anda membangun aplikasi yang lebih baik dengan lebih cepat, daftar diri untuk akun gratis hari ini.

Teruskan dari Mengubah Aplikasi Nuxt Anda ke iOS & Android dengan Capacitor 8

Jika Anda menggunakan Mengubah Aplikasi Nuxt Anda ke iOS & Android dengan Capacitor 8 untuk merencanakan pekerjaan plugin native, hubungkannya dengan Capgo Direktori Plugin untuk alur kerja produk di Capgo Direktori Plugin, Capacitor Plugin oleh Capgo untuk detail implementasi di Capacitor Plugin oleh Capgo, Menambahkan atau Mengupdate Plugin untuk detail implementasi di Menambahkan atau Mengupdate Plugin, Alternatif Plugin Enterprise Ionic untuk alur produk di Ionic Enterprise Plugin Alternatif, dan Capgo Pembangunan Nativ untuk alur produk di Capgo Pembangunan Nativ.