Lompat ke konten utama
Tutorial

Convert Your Nuxt App to iOS & Android with Capacitor 8

Transform your existing Nuxt 4 web application into native iOS and Android mobile apps using Capacitor 8. A complete guide to configuring static generation, adding native plugins, and deploying to app stores.

Kredit Artikel

Martin Donadieu

Pengarang

Valeria

Pengulas

Jordan

Editor

Mengubah Aplikasi Nuxt Anda ke iOS & Android dengan Capacitor 8

Pendahuluan

Apakah Anda memiliki aplikasi web Nuxt yang sudah ada? Dalam panduan ini, Anda akan belajar cara mengubahnya menjadi aplikasi mobile native iOS dan Android menggunakan Capacitor context: Halaman/area: Halaman produk Capgo yang berupdate secara langsung. Peran: Judul bagian atau halaman. Dilihat di: halaman live-update.astro. Simpan Capgo produk/merek dan istilah pengembang secara tepat. Kunci pesan `live_update_platform_capacitor_title` (Judul Platform Capacitor Berupdate Secara Langsung).

Capacitor wraps your web app in a native container, giving you access to device APIs like camera, filesystem, and push notifications while keeping your existing Vue codebase. Unlike Flutter or React Native, you don’t need to rewrite anything — your Nuxt code runs as-is.

__CAPGO_KEEP_0__ mengelilingi aplikasi web Anda dengan kontainer native, memberikan akses ke API perangkat seperti kamera, sistem file, dan notifikasi push sambil menjaga kodebase Vue yang sudah ada. Berbeda dengan Flutter atau React Native, Anda tidak perlu menulis ulang apa pun — aplikasi Nuxt __CAPGO_KEEP_1__ berjalan secara langsung.

  • Apakah yang akan Anda pelajari:
  • Add Capacitor 8 with essential native plugins
  • Menggunakan __CAPGO_KEEP_0__ 8 dengan plugin native yang penting
  • Membangun dan menguji di simulator iOS dan Android
  • Perbaiki masalah tata letak iOS yang umum (viewport, area aman, keluaran horizontal)
  • Tambahkan antarmuka yang terasa asli dengan Capgo Navigasi dan Transisi Asli

Berminat memulai proyek baru dari awal? Cek panduan kami tentang Membangun Aplikasi Mobile Nuxt dari Awal.

Manfaat Menggunakan Nuxt dan Capacitor

  • Code Reusabilitas: Bagikan komponen Vue dan logika antara aplikasi web dan mobile.
  • Kinerjacontext: Halaman/area: Bagian/daerah masalah/penyelesaian. Peran: Judul bagian atau halaman. Dilihat di: halaman premium-support.astro. Pesan kunci `ps_help_performance_title` (Ps Bantuan Judul Kinerja).
  • : Pengembangan statis Nuxt menciptakan bundle yang dioptimalkan sempurna untuk mobile.: Access device features like camera, geolocation, and filesystem through Capacitor plugins.
  • : Akses fitur perangkat seperti kamera, lokasi geografis, dan filesystem melalui __CAPGO_KEEP_0__ plugin.: Gunakan pola Vue/Nuxt yang familiar tanpa harus belajar pengembangan native.

Prasyarat

Sebelum Anda memulai, pastikan Anda telah memiliki:

  • Node.js 18+ terinstal
  • Aplikasi Nuxt yang sudah ada Xcode (hanya untuk pengembangan iOS di macOS)
  • Android Studio (hanya untuk pengembangan Android)
  • Building a Native Mobile App with Nuxt and Capacitor Dalam artikel ini, kita akan membahas cara membuat aplikasi mobile native dengan menggunakan Nuxt dan Capacitor.

Konfigurasi Aplikasi Nuxt Anda untuk Mobile

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

Pastikan Anda memiliki package.json context

{
  "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"
  }
}

script pengenerate: If you’re using server-side features (API routes, server middleware, etc.), you’ll need to refactor those to use client-side alternatives or external APIs.

Jika Anda menggunakan fitur server-side (__CAPGO_KEEP_0__ rute, middleware server, dll.), Anda perlu meredefinisikan fitur-fitur tersebut menggunakan alternatif klien atau API eksternal.

bun run generate

Tes pengembangan statis dengan menjalankan: .output/public folder with your static files. This is what Capacitor will bundle into your native app.

folder dengan file-file statis. Ini adalah apa yang Capacitor akan bundel ke dalam aplikasi native Anda.

Mengintegrasikan __CAPGO_KEEP_0__ ke Dalam Projek Anda

  1. Install Capacitor core and CLI:
bun add @capacitor/core
bun add -D @capacitor/cli
  1. Pasang plugin umum Capacitor yang mungkin Anda butuhkan:
bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/status-bar @capacitor/preferences

Plugin ini menyediakan fitur penting:

  • @capacitor/app: Menghandle kejadian siklus aplikasi (depan/belakang, tautan dalam)
  • @capacitor/keyboard: Mengontrol perilaku keyboard di perangkat mobile
  • @capacitor/splash-screen: Mengelola layar splash native
  • @capacitor/status-bar: Mengatur tampilan bar status perangkat
  • @capacitor/preferences: Penyimpanan nilai kunci (seperti localStorage tetapi native)
  1. Mulai dengan 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).

  1. Buat atau update file dengan konfigurasi yang tepat: capacitor.config.ts Pasang platform native:
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;
  1. Tambahkan folder platform native:
bun add @capacitor/ios @capacitor/android
  1. __CAPGO_KEEP_0__ akan membuat
bunx cap add ios
bunx cap add android

Capacitor will create ios folder di root proyek Anda yang berisi proyek native. android Untuk membangun proyek Android, Anda membutuhkan

__CAPGO_KEEP_0__ akan membuat dan folder di root proyek Anda yang berisi proyek native. Studio Android. Untuk iOS, Anda membutuhkan Mac dengan Xcode.

  1. Build dan sinkronkan proyek Anda:
bun run mobile

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

Pembangunan dan Pengiriman Aplikasi Native

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

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

  1. Mulai 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
  1. Bangun dan jalankan aplikasi:

android-studio-run

  • Pada Android Studio, 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 melakukannya sebelumnya, Xcode akan mengarahkan Anda melalui prosesnya (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 Anda ke perangkat mobile.

nuxtjs-mobile-app

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

Capacitor Reload Sederhana Hidup

Selama pengembangan, Anda dapat memanfaatkan reload sederhana hidup untuk melihat perubahan secara langsung di perangkat mobile Anda. Untuk mengaktifkan fitur ini, ikuti langkah-langkah berikut:

  1. Cari alamat IP lokal Anda:
  • Pada macOS, jalankan perintah berikut di terminal:

    ipconfig getifaddr en0
  • Pada Windows, jalankan:

    ipconfig

    Cari alamat IPv4 di hasilnya.

  1. Ubah 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).

  1. Aplikasikan perubahan ke proyek native Anda:
bunx cap copy

Hasilnya adalah copy perintah ini menyalin folder web dan perubahan konfigurasi ke proyek native tanpa memperbarui proyek seluruhnya.

  1. Mulai server pengembang Nuxt dan rebuild di Xcode/Android Studio:
bun run dev

Sekarang, setiap kali Anda membuat perubahan pada aplikasi Nuxt, 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 memperbarui proyek native karena pengisian ulang hidup hanya berlaku untuk perubahan web code.

Menggunakan Capacitor Plugin

Capacitor plugin memungkinkan Anda untuk mengakses fitur perangkat native dari aplikasi Nuxt. Mari kita jelajahi cara menggunakan plugin Share sebagai contoh: Instal plugin Share: Buat atau perbarui halaman untuk menggunakan plugin Share. Pada Nuxt 4, halaman berada di

  1. Sinkronkan perubahan dengan proyek native:
bun add @capacitor/share
  1. __CAPGO_KEEP_0__ 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>
  1. __CAPGO_KEEP_0__
bun run mobile

atau hanya sinkronisasi tanpa membangun ulang:

bunx cap sync
  1. Membangun ulang dan menjalankan aplikasi di perangkat Anda.

Sekarang, ketika Anda mengklik tombol “Bagikan sekarang!”, dialog berbagi 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.

Aplikasi UI yang terasa native dengan Capgo Navigasi dan Transisi Native

Saya telah bekerja selama bertahun-tahun dengan Ionic untuk membangun aplikasi multi-platform, tetapi mengintegrasikannya dengan Nuxt adalah hacky dan jarang berharga ketika Anda sudah memiliki Tailwind CSS.

Untuk merasakan aplikasi mobile native di Nuxt + Capacitor, gunakan Capgo plugin alih-alih kit UI web seperti Konsta UI:

  • @capgo/capacitor-native-navigation — navbar native, tab bar Liquid Glass di iOS, dan gaya tab bar yang diblur di Android. Router Nuxt Anda tetap menjaga status jalur; plugin ini menguasai chrome native.
  • capgo/capacitor-transisi --- Transisi halaman Ionic dan pengembalian ke belakang iOS di layer WebView, tanpa menerima UI Ionic.

Install kedua-duanya:

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

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

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

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

Tampilkan tab bar kaca cair (iOS menggunakan rendering milik sistem; Android menggunakan latar belakang WebView yang diboroskan):

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 shell aplikasi:

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

Wrap halaman yang diarahkan dalam cap-router-outlet, cap-pagedan cap-contentdan panggil setDirection('forward') atau setDirection('back') context

HTML fragment teks dari string UI Capgo yang lebih panjang (kunci induk `alternatives_cta_questions`). Halaman/area: Halaman perbandingan pembaruan hidup Capacitor. Peran: Paragraf pemasaran atau hukum yang panjang. Dilihat di: halaman alternatives.astro. Simpanlah istilah produk/brand dan istilah developer Capgo secara tepat. Kunci pesan `alternatives_cta_questions` (Pertanyaan Tindakan Alternatif). | Fragment teks HTML dari string UI Capgo yang lebih panjang (kunci induk `appflow_cta_questions`). Halaman/area: Halaman perbandingan/migrasi pemasaran Appflow. Peran: Paragraf pemasaran atau hukum yang panjang. Dilihat di: halaman ionic-appflow.astro. Simpanlah istilah produk/brand dan istilah developer Capgo secara tepat. Kunci pesan `appflow_cta_questions` (Pertanyaan Tindakan Appflow). | Fragment teks HTML dari string UI Capgo yang lebih panjang (kunci induk `capwesome_cta_questions`). Halaman/area: Halaman perbandingan Capawesome. Peran: Paragraf pemasaran atau hukum yang panjang. Dilihat di: halaman capwesome.astro. Simpanlah istilah produk/brand dan istilah developer Capgo secara tepat. Kunci pesan `capwesome_cta_questions` (Pertanyaan Tindakan Capwesome). | Halaman/area: Halaman layanan konsultasi. Peran: Judul atau tagline bagian. Dilihat di: halaman consulting.astro. Simpanlah istilah produk/brand dan istilah developer Capgo secara tepat. Kunci pesan `consulting_faq_subtitle` (Judul FAQ Layanan Konsultasi). | Halaman/area: Halaman perbandingan/migrasi pemasaran Appflow. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman ionic-appflow.astro, halaman ionic-enterprise-plugins.astro, halaman solusi/ionic-enterprise-plugins.astro. Kunci pesan `appflow_plugins_or` (Appflow Plugins Atau). Menggunakan @capgo/capacitor-navigasi-nativa dan Menggunakan @capgo/capacitor-transisi.

Daerah aman dengan Tailwind

Untuk daerah aman perangkat di Tailwind CSS, gunakan @capgo/tailwind-capacitor (diterbitkan sebagai tailwind-capacitor di npm). Ini menyediakan safe-areas utilitas dan plugin-plugin lainnya yang Capacitor-ramah 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, simpan import ini di file CSS yang dirujuk dari nuxt.config.ts.

Gunakan utilitas seperti pt-safe, pb-safedan px-safe bukan dengan menaburkannya secara manual. env(safe-area-inset-*) terutama karena proyek ini aktif dikembangkan — jika ada sesuatu yang hilang untuk pengaturan Nuxt Anda, buka PR di GitHub.

Pengaturan Layout iOS (Viewport, Area Aman, dan Overflows Horizontal)

Jika konten terlihat dipotong, bergeser, atau dapat di-scroll secara horizontal di iOS, menambahkan lebih banyak overflow-x: hidden atau menyesuaikan tag viewport saja biasanya tidak cukup untuk memperbaikinya. Lakukan 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',
        },
      ],
    },
  },
});

Pengaturan Area Aman iOS dari satu wrapper root saja

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

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

Terapkan semua konten halaman di dalam .app-shellJangan menambahkan padding area aman yang berulang di header, modal, dan pembungkus tata letak sering membuat UI terlihat dipotong atau terlalu besar.

Dengan @capgo/tailwind-capacitorkamu bisa mengekspresikan padding yang sama dengan utilitas seperti pt-safe pb-safe px-safe di shell tunggal itu.

Setel Capacitor iOS contentInset ke never context: Halaman/area: Halaman produk update langsung. Peran: Label UI singkat atau item navigasi. Kunci pesan `live_update_dynamic_label_to` (Live Update Dynamic Label To).

pertama capacitor.config.tsDalam contentInsetMode: 'css', lebih baik mengaktifkan inset asli dan biarkan CSS (atau Native Navigation’s " ) mengelola area aman:

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

Menggabungkan Capacitor’s konten otomatis dengan CSS env(safe-area-inset-*) Menggunakan padding CSS untuk menghindari jarak ganda

Cari elemen yang sebenarnya mengalami overflows

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

Dalam 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 banyak masalah overflows horizontal berasal dari 100vw / w-screen, padding area aman yang duplikat, atau kontainer dengan lebar tetap — bukan dari tag meta viewport itu sendiri

Kesimpulan

You’ve successfully converted your existing Nuxt web application into native iOS and Android apps using Capacitor 8. Your Vue codebase now runs natively on mobile devices with access to device APIs.

Apakah yang kamu capai:

  • Konfigurasi Nuxt untuk pengembangan statis
  • Added Capacitor 8 with essential plugins
  • Bangun dan terapkan ke simulator iOS dan Android
  • Aktifkan ulang reload untuk pengembangan
  • Perbaiki masalah layout iOS yang umum (viewport, area aman, overflow)
  • Added native-feeling UI with Capgo Native Navigation and Transitions

Langkah selanjutnya:

  • Konfigurasi Capgo untuk pembaruan secara nirkabel tanpa pengulangan aplikasi di toko aplikasi
  • Tambahkan lebih banyak plugin native seperti Kamera, Lokasi, atau Notifikasi Push
  • Konfigurasi ikon aplikasi dan layar splash untuk produksi
  • Siapkan aplikasi Anda untuk pengiriman ke App Store dan Google Play

Membuat aplikasi mobile Nuxt dari awal Untuk panduan langkah demi langkah. Sumber Daya

Dokumentasi Nuxt

Apa yang bisa dilakukan Capgo untuk membantu Anda membuat aplikasi yang lebih baik dengan lebih cepat, daftar diri Anda untuk akun gratis hari ini.

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

Jika Anda menggunakan Mengubah Aplikasi Nuxt Anda ke iOS &amp; Android dengan Capacitor 8 untuk merencanakan pekerjaan plugin asli, hubungkannya dengan Capgo Plugin Directory 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 kerja produk di Alternatif Plugin Enterprise Ionic, dan Capgo Pembangunan Nativ untuk alur kerja produk di Capgo Pembangunan Nativ

Update langsung untuk Capacitor aplikasi

Ketika bug layer web masih aktif, kirimkan perbaikan melalui Capgo daripada menunggu hari-hari untuk persetujuan toko aplikasi. Pengguna mendapatkan update di latar belakang sementara perubahan native tetap dalam jalur review normal.

dukungan manusia dari Martin

Mulai Sekarang

Terbaru dari Blog Kami

Capgo memberikan Anda wawasan terbaik yang Anda butuhkan untuk membuat aplikasi mobile yang profesional.