Mengubah Aplikasi Web 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 membungkus aplikasi web Anda dalam sebuah 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 — Nuxt code berjalan seperti biasa.

What akan Anda pelajari:

• Konfigurasi aplikasi Nuxt yang sudah ada untuk pengembangan statis
• Tambahkan Capacitor 8 dengan plugin native yang penting
• Bangun dan tes pada simulator iOS dan Android
• Aktifkan reload hidup 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 untuk memulai proyek baru dari awal? Periksa panduan kami pada Building a Nuxt Mobile App from Scratch.

Manfaat Menggunakan Nuxt dan Capacitor

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

Persyaratan Sebelumnya

: Pastikan Anda telah memenuhi syarat-syarat berikut:

• Node.js 18+ : Terinstal
• : Sudah ada Nuxt 4 Aplikasi
• Xcode (untuk pengembangan iOS, macOS hanya)
• Android Studio (untuk pengembangan Android)

Mengatur Aplikasi Nuxt untuk Mobile

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

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

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

Testlah generasi statis dengan menjalankan:

bun run generate

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

Menambahkan Capacitor 8 ke Projek Anda

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

1. Pasang Capacitor core dan CLI:

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

2. 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 kibor di mobile
• @capacitor/layar-splash: Atur layar splash native
• @capacitor/status-bar: Gaya bar status perangkat
• @capacitor/preference: Penyimpanan nilai kunci (seperti localStorage tetapi native)

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

4. Buat atau perbarui file dengan konfigurasi yang tepat: capacitor.config.ts @__CAPGO_KEEP_0__/layar-splash

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-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. Pembangunan dan Sinkronisasi Proyek:

bun run mobile

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

Pembangunan dan Pengiriman Aplikasi Native

To build and deploy your native mobile app, follow these steps:

Membangun dan mengirimkan aplikasi mobile native Anda, ikuti langkah-langkah berikut: To develop iOS apps, you need to have Membuat aplikasi iOS, Anda memerlukan Xcode Xcode

1. terinstal, dan untuk aplikasi Android, Anda memerlukan

Android Studio

bun run mobile:ios

Android Studio

bun run mobile:android

Or directly with Capacitor CLI:

bunx cap open ios
bunx cap open android

2. Membuka proyek native:

• In 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 membantu 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 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:

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

Perintah copy menyalin folder web dan perubahan konfigurasi ke proyek native tanpa mengupdate proyek secara keseluruhan.

4. Mulai server pengembangan Nuxt dan merekonstruksi 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.

Penting: Jika Anda menginstal plugin baru atau membuat perubahan pada file native, Anda perlu merekonstruksi 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 Anda. Mari kita menjelajahi cara menggunakan plugin Plugin Berbagi sebagai contoh:

1. Instal plugin Berbagi:

bun add @capacitor/share

2. Buat atau perbarui halaman untuk menggunakan plugin Berbagi. Pada 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. Bangun ulang dan jalankan aplikasi di perangkat Anda.

Sekarang, ketika Anda mengklik tombol ‘Berbagi sekarang!’, dialog berbagi native akan muncul.

Next, you can make the app feel more native on iOS and Android with Capgo navigation and transitions, and fix common iOS layout issues that cause horizontal overflow or cropped safe areas.

Capgo navigasi dan transisi native, dan memperbaiki masalah layout iOS yang umum menyebabkan overflow horizontal atau area aman yang dipotong.

UI yang terasa native dengan navigasi dan transisi native Untuk membangun aplikasi seluler lintas platform, tetapi mengintegrasikannya dengan Nuxt adalah sulit dan jarang berharga ketika Anda sudah memiliki Untuk merasa seperti aplikasi seluler asli dalam aplikasi Nuxt + Capgo, gunakan plugin Capgo alih-alih UI web seperti Konsta UI: @Capgo/Capgo-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-native-navigation — transisi halaman seperti Ionic dan swipe balik di iOS di layer WebView, tanpa menerima UI Ionic.
• @capgo/capacitor-transitions Konfigurasi navigasi asli dengan mode CSS inset agar konten web menghormati bar-bar asli:

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

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

Tambahkan transisi halaman asli di shell aplikasi:

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

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

Untuk membangun aplikasi seluler lintas 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}`);
});

For a native mobile feel in a Nuxt + Capgo app, use Capgo plugins instead of web-only UI kits like 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>

Wrap 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 native menguasai permukaan tersebut.

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

Wilayah aman dengan Tailwind

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

bun add -D tailwind-capacitor

In 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 dikaitkan dengan nuxt.config.ts.

Pakai utilitas seperti pt-safe, pb-safe, dan px-safe sebagai ganti dari menambahkannya env(safe-area-inset-*) oleh tangan. Projek ini aktif dikembangkan — jika ada sesuatu yang hilang untuk setup Nuxt Anda, buka PR di GitHub.

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

Jika konten terlihat dipotong, bergeser, atau dapat di-scroll secara horizontal di iOS, tambahkan lebih overflow-x: hidden atau mengatur tag viewport saja biasanya tidak cukup. Lakukan periksa-periksa ini secara berurutan.

Pastikan tag meta viewport diterapkan dengan benar

Dalam 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

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

Selimuti semua konten halaman di dalam .app-shell. Menggunakan padding area aman yang sama 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.

Buat Capacitor iOS contentInset ke never Pertama

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

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

Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) Temukan elemen yang sebenarnya mengalami kelebihan

Biasanya, penyebabnya adalah elemen yang menggunakan

, Tailwind 100vw, lebar piksel tetap, atau besar w-screen, a fixed pixel width, or a large 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 keluaran horizontal datang dari 100vw / w-screenpadding area aman yang digandakan, 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 mobile native iOS dan Android menggunakan Capacitor 8. Kode Vue Anda sekarang 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 mengirim ke simulator iOS dan Android
• Mengaktifkan ulang reload untuk pengembangan
• Memperbaiki masalah tata letak iOS umum (viewport, area aman, keluaran)
• Menambahkan antarmuka native yang merasa dengan Capgo Navigasi dan Transisi Native

Langkah-langkah selanjutnya:

• Konfigurasi Capgo Mengatur untuk pembaruan melalui udara tanpa resubmisi toko aplikasi
• Tambahkan lebih banyak plugin native seperti Kamera, Lokasi, atau Pemberitahuan Push
• Konfigurasi ikon aplikasi dan layar splash untuk produksi
• Siapkan aplikasi Anda untuk pengiriman ke App Store dan Google Play

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

Ressourcer

• Referensi Nuxt
• Capacitor 8 Referensi
• @capgo/capacitor-navigasi-native — Tab Baja Kaca Liquid dan Chrome Asli
• @capgo/capacitor-transisi — Transisi Halaman yang Terasa Asli
• @capgo/tailwind-capacitor — Utilitas Area Aman Tailwind untuk Capacitor
• Capgo - Update Hidup untuk Aplikasi Capacitor

Apa itu Capgo? Pelajari bagaimana Capgo dapat membantu Anda membuat aplikasi yang lebih baik dengan lebih cepat, mendaftarlah untuk akun gratis Daftar 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 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 Ionic Enterprise Plugin Alternatives, dan Capgo Pembangunan Nativ untuk alur kerja produk di Capgo Pembangunan Nativ.