Mengubah Aplikasi Web Nuxt Anda ke iOS & Android dengan Capacitor 8

Pendahuluan

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 8 — versi terbaru dengan kinerja yang ditingkatkan dan fitur baru.

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

Apa yang akan Anda pelajari:

• Konfigurasi aplikasi Nuxt Anda untuk pengembangan statis
• Tambahkan Capacitor 8 dengan plugin native yang penting
• Buat dan tes pada simulator iOS dan Android
• Aktifkan ulang untuk pengembangan yang lebih cepat
• Perbaiki masalah layout iOS yang umum (viewport, area aman, keluaran horizontal)
• Tambahkan antarmuka yang terasa native dengan Capgo Native Navigation dan Transisi

Mau memulai proyek baru dari awal? Cek panduan kami pada Membuat Aplikasi Mobile Nuxt dari Awal.

Manfaat Menggunakan Nuxt dan Capacitor

• Reusabilitas Code: Bagikan komponen Vue dan logika antara aplikasi web dan mobile.
• Kinerja:Nuxt membuat bundle statis yang dioptimalkan, cocok 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 harus belajar pengembangan asli.

Prerequisites

: Pastikan Anda telah memiliki:

• Node.js 18+ terpasang
• Sistem yang ada Nuxt 4 Aplikasi
• Xcode (untuk pengembangan iOS, macOS hanya)
• Studio Android (untuk pengembangan Android)

Mengatur Aplikasi Nuxt Anda untuk Mobile

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

Pastikan Anda memiliki package.json Mempunyai skrip penghasilan:

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

Important: Jika Anda menggunakan fitur server-side (API rute, middleware server, dll.), Anda perlu merestrukturisasi fitur-fitur tersebut untuk menggunakan alternatif sisi klien atau API eksternal.

Tes generasi statis dengan menjalankan:

bun run generate

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

Mengambahkan Capacitor 8 ke Projek Kamu

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

1. Install Capacitor core dan CLI:

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

2. Install plugin-plugin Capacitor yang umum yang kamu 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: Mengelola layar splash native
• @capacitor/status-bar: Mengatur bar status perangkat
• @capacitor/preferences: Penyimpanan nilai kunci (seperti localStorage tetapi native)

3. Mulai 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).

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

5. Instalasi platform native:

bun add @capacitor/ios @capacitor/android

6. Tambahkan folder platform native:

bunx cap add ios
bunx cap add android

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

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

7. Membangun dan Sinkronisasi Proyek:

bun run mobile

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

Membangun dan Mengembangkan Aplikasi Native

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

To mengembangkan aplikasi iOS, Anda membutuhkan Xcode terinstal, dan untuk aplikasi Android, Anda membutuhkan 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. Buka 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

2. Bangun dan jalankan aplikasi:

• Pada Android Studio, tunggu proyek siap, lalu klik tombol "Run" untuk mengirimkan aplikasi ke perangkat yang terhubung atau emulator.

• Pada Xcode, atur akun tanda tangan Anda untuk mengirimkan aplikasi ke perangkat nyata. Jika Anda belum pernah 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.

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

Capacitor Reload Hidup

Selama pengembangan, Anda dapat memanfaatkan fitur reload hidup untuk melihat perubahan secara instan pada perangkat mobile. 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.

2. Perbarui capacitor.config.ts untuk mengarahkan 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).

3. Aplikasikan perubahan ke proyek native Anda:

bunx cap copy

The copy perintah mengcopy folder web dan perubahan konfigurasi ke proyek native tanpa memperbarui proyek secara keseluruhan

4. Mulai server pengembang Nuxt dan merekonstruksi di Xcode/Android Studio:

bun run dev

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

Note: If you install new plugins or make changes to native files, you’ll need to rebuild the native project since live reloading only applies to web code changes.

Capacitor plugin memungkinkan Anda untuk mengakses fitur perangkat native dari aplikasi Nuxt. Mari kita eksplorasi cara menggunakan plugin tersebut.

"Capacitor plugin memungkinkan Anda untuk mengakses fitur perangkat native dari aplikasi Nuxt Anda. Mari kita cari tahu cara menggunakan"} Plugin berbagi sebagai contoh:

1. Instal plugin berbagi:

bun add @capacitor/share

2. Buat atau perbarui halaman untuk menggunakan plugin berbagi. 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>

3. Sinkronkan perubahan dengan proyek native:

bun run mobile

atau hanya sinkronkan tanpa membangun ulang:

bunx cap sync

4. Rebuild dan jalankan aplikasi di perangkat Anda.

Sekarang, ketika Anda mengklik tombol “Berbagi sekarang!”, dialog berbagi native akan muncul.

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

UI yang terasa lebih native dengan Capgo Navigasi dan Transisi Native

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

Untuk merasakan sentuhan seluler asli dalam aplikasi Nuxt + Capacitor , gunakan plugin Capgo daripada UI web-only seperti Konsta UI:

• @capgo/capacitor-navigasi native — navbar native, Liquid Glass tab bar di iOS, dan gaya tab bar yang diboroskan di Android. Router Nuxt Anda tetap menjaga status jalur; plugin ini menguasai chrome native.
• @capgo/capacitor-transisi — transisi halaman gaya Ionic dan swipe-back di lapisan WebView iOS, 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 Liquid Glass (iOS menggunakan rendering yang dimiliki 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 dalam 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>

Terapkan halaman yang dilalui cap-router-outlet, cap-pagedan, dan cap-contentdan panggil setDirection('forward') atau setDirection('back') Sebelum berpindah. Jangan duplikat header atau footer web ketika navigasi native menguasai permukaan tersebut.

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

Area yang aman dengan Tailwind

Untuk area yang aman perangkat dengan Tailwind CSS, gunakan @capgo/tailwind-capacitor (diterbitkan sebagai tailwind-capacitor di npm). Ini menyediakan safe-areas fasilitas dan plugin Tailwind lainnya yang Capacitor-ramah:

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 Anda menyimpan import ini di file CSS yang diacu dari nuxt.config.ts.

Pakai fasilitas seperti pt-safe, pb-safe, dan px-safe alih-alih menyebarkan env(safe-area-inset-*) dengan tangan. Projek ini aktif dikembangkan — jika ada sesuatu yang hilang untuk pengaturan Nuxt Anda, Buka PR di GitHub.

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

Jika konten terlihat dipotong, bergeser, atau dapat di-scroll ke kiri pada iOS, tambahkan lebih banyak overflow-x: hidden atau hanya mengatur tag viewport saja biasanya tidak cukup untuk memperbaiki masalah tersebut. Jalankan periksa-periksa ini secara berurutan.

Pastikan tag meta viewport telah diterapkan dengan benar

In 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',
        },
      ],
    },
  },
});

Handle area aman iOS dari satu wrapper root saja

Buat sebuah shell aplikasi tunggal dan terapkan padding area aman di sana — bukan di komponen nested yang berbeda-beda:

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

Wrap semua konten halaman di dalam .app-shellPenambahan 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 menyatakan padding yang sama dengan utilitas seperti pt-safe pb-safe px-safe di shell tunggal tersebut.

Buat Capacitor iOS contentInset ke never pertama

Di capacitor.config.ts, lebih baik menggunakan inset disabled asli dan biarkan CSS (atau Native Navigation’s) contentInsetMode: 'css') mengendalikan 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 padding CSS env(safe-area-inset-*) Menemukan elemen yang sebenarnya mengalir ke luar

Temukan elemen yang mengalir melebihi

The usual culprit is an element using 100vw, Tailwind w-screenInspektor Web Safari, jalankan: min-width.

Jalankan di Safari Web Inspector:

[...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,
  }));

Memanfaatkan Tailwind, ganti w-screen dengan w-full ketika memungkinkan. Banyak masalah keluaran horizontal berasal dari 100vw / w-screenDari viewport meta tag itu sendiri, bukan dari padding area aman yang diulang, atau kontainer lebar tetap.

Kesimpulan

Anda telah berhasil mengonversi aplikasi web Nuxt yang sudah ada menjadi aplikasi mobile 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
• Mengatasi masalah layout iOS yang umum (viewport, area aman, keluaran)
• Menambahkan UI yang terasa asli dengan Capgo Navigasi dan Transisi Asli

Langkah berikutnya:

• Konfigurasi Capgo untuk pembaruan melalui udara tanpa resubmisi aplikasi di toko aplikasi
• Tambahkan lebih banyak plugin asli 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

Starting a brand new project? Check out Membangun Aplikasi Mobile Nuxt dari Awal untuk panduan langkah demi langkah.

Sumber Daya

• Nuxt Dokumentasi
• Capacitor 8 Dokumentasi
• @capgo/capacitor-navigasi-nasional --- Tab Baja Kaca Liquid dan Chrome Nasional
• @capgo/capacitor-transisi --- Transisi Halaman yang Terasa Nasional
• @capgo/tailwind-capacitor --- Utilitas Daerah Aman untuk Capacitor
• Capgo - Perbarui Hidup untuk Aplikasi Capacitor

Learn how Capgo can help you build better apps faster, daftar untuk akun gratis hari ini. sekarang.

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 kerja 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, Mengambah atau Mengupdate Plugin untuk detail implementasi di Mengambah atau Mengupdate Plugin, Alternatif Plugin Enterprise Ionic untuk alur kerja produk di Alternatif Plugin Enterprise Ionic, dan Capgo Pembangunan Aplikasi Mobile Asli untuk alur kerja produk dalam Capgo Pembangunan Aplikasi Mobile Asli.