Konversi Aplikasi Nuxt Anda ke iOS & Android dengan Capacitor 8

Introduction

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

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

Apakah yang Anda akan pelajari:
Add Capacitor 8 with essential native plugins
Tambahkan Capacitor 8 dengan plugin native yang penting
Bangun dan tes di simulator iOS dan Android
Aktifkan reload hidup untuk pengembangan yang lebih cepat
Add native-feeling UI with Capgo Native Navigation and Transitions

Si Anda ingin memulai proyek baru dari awal? Building a Nuxt Mobile App from Scratch.

Keuntungan Menggunakan Nuxt dan Capacitor

Code Reusability: Bagikan komponen Vue dan logika antara aplikasi web dan mobile.
Kinerjacontext: Halaman/area: Bagian homepage masalah/penyelesaian. Peran: Judul bagian atau halaman. Dilihat di: halaman premium-support.astro. Kunci pesan `ps_help_performance_title` (Ps Help Performance Title).
: Pengoptimalan statis Nuxt menciptakan bundle yang optimal 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.Pengembangan yang Sederhana

: Gunakan pola Vue/Nuxt yang familiar tanpa harus belajar pengembangan native.

Sebelum Anda memulai, pastikan Anda memiliki:

Node.js 18+ terpasang
Suatu aplikasi Nuxt 4 Xcode
(untuk pengembangan iOS, macOS hanya) Android Studio
(untuk pengembangan Android) Pengaturan Aplikasi Nuxt untuk Mobile

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

Capacitor

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

Penting: Jika Anda menggunakan fitur server-side (API rute, middleware server, dll.), Anda perlu meredefinisi itu untuk menggunakan alternatif sisi klien atau API eksternal.

Tes generasi statis dengan menjalankan:

bun run generate

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

Menggunakan Capacitor 8 di Projek Anda

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

Pasang Capacitor core dan CLI:

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

Pasang plugin Capacitor umum yang Anda mungkin butuhkan:

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

Plugin ini menyediakan fitur penting:

@capacitor/aplikasi : Menghandle kejadian siklus aplikasi (depan/belakang, tautan dalam)
@capacitor/keyboard : Mengontrol perilaku keyboard di ponsel
@capacitor/layar-splash : Mengelola layar splash native
@capacitor/status-bar : Mengatur baris status perangkat
@capacitor/preferensi : Penyimpanan nilai kunci (seperti localStorage tetapi native)

Mulai Capacitor dengan detail proyek Anda:

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

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

Buat atau update file dengan konfigurasi yang tepat: capacitor.config.ts Instal 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;

Tambahkan folder platform native:

bun add @capacitor/ios @capacitor/android

__CAPGO_KEEP_0__ akan membuat

bunx cap add ios
bunx cap add android

Capacitor will create ios context: Halaman/area: Situs web pemasaran Capgo. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman trust.astro. Kunci pesan `dan` (Dan). android folder di root proyek Anda yang berisi proyek native.

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

Build dan sinkronkan proyek Anda:

bun run mobile

Ini menjalankan skrip kustom Anda yang menghasilkan bangunan statis Nuxt dan sinkronisasi file dengan platform native.

Membangun dan Mengembangkan Aplikasi Native

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

Untuk mengembangkan aplikasi iOS, Anda memerlukan Xcode terinstal, dan untuk aplikasi Android, Anda memerlukan Android Studio 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.

Buka proyek native:

Untuk iOS:

bun run mobile:ios

For Android:

bun run mobile:android

atau secara langsung dengan Capacitor CLI:

bunx cap open ios
bunx cap open android

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

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

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

Capacitor Live Reload

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

Temukan alamat IP lokal Anda:

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

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

Aplikasikan perubahan ke proyek native Anda:

bunx cap copy

Perintah copy mengcopy folder web dan perubahan konfigurasi ke proyek native tanpa memperbarui proyek seluruhnya.

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

bun run dev

Now, 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 membangun kembali 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 jelajahi cara menggunakan plugin Share sebagai contoh: Instal plugin Share: Buat atau perbarui halaman untuk menggunakan plugin Share. Pada Nuxt 4, halaman berada di

Sinkronkan perubahan dengan proyek native:

bun add @capacitor/share

Atau sinkronkan tanpa membangun ulang: 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>

Bangun ulang dan jalankan aplikasi pada perangkat Anda.

bun run mobile

Install the Share plugin:

bunx cap sync

Create or update a page to use the Share plugin. In Nuxt 4, pages go in

Now, ketika Anda mengklik tombol “Bagikan sekarang!”, dialog berbagi native akan muncul.

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

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

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

@capgo/capacitor-native-navigation – 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-transitions – transisi halaman Ionic dan swipe-back di lapisan WebView iOS tanpa mengadopsi UI Ionic.

Install kedua:

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

Konfigurasi navigasi native dengan mode inset CSS 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 Glass Liquid (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>

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

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

Wilayah aman dengan Tailwind

Untuk wilayah 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 digunakan sebagai nuxt.config.ts.

Pakai utilitas seperti pt-safe, pb-safe, dan px-safe sebaliknya dari menyebarkan env(safe-area-inset-*) oleh tangan. Projek 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 overflow-x: hidden atau mengatur tag viewport sendiri biasanya tidak dapat memperbaikinya. Jalankan periksaan-periksaan 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',
        },
      ],
    },
  },
});

Pengaturan Area Aman iOS dari satu wrapper root saja

Buatlah sebuah 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-shellPenggunaan 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 mengekspresikan padding yang sama dengan utilitas seperti pt-safe pb-safe px-safe di shell tunggal itu.

Set Capacitor iOS `contentInset` ke `never` pertama

Dalam capacitor.config.ts, lebih baik menggunakan inset native yang dinonaktifkan 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 padding CSS adalah penyebab umum dari jarak ganda. env(safe-area-inset-*) to

Temukan elemen yang benar-benar mengalir melebihi

Biasanya, penyebabnya adalah elemen yang menggunakan 100vw, Tailwind w-screen, lebar piksel yang tetap, atau lebar yang sangat 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-screen, padding 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 ada menjadi aplikasi 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:

Konfigurasi Nuxt untuk pengembangan statis
Menambahkan Capacitor 8 dengan plugin yang penting
Membangun dan mengirimkan ke simulator iOS dan Android
Mengaktifkan ulang reload untuk pengembangan
Mengatasi masalah tata letak iOS yang umum (viewport, area aman, overflow)
Menambahkan antarmuka yang terasa asli dengan Capgo Navigasi dan Transisi Native

Langkah selanjutnya:

Pengaturan Capgo Mengaktifkan pembaruan melalui udara tanpa resubmisi ke toko aplikasi
Tambahkan lebih banyak plugin native seperti Kamera, Lokasi, atau Notifikasi Push
Konfigurasi ikon aplikasi dan layar splash untuk produksi
Mengsiapkan Aplikasi Anda untuk Pengiriman ke App Store dan Google Play

Membuat Aplikasi Mobile Nuxt dari Awal? Membuat Aplikasi Mobile Nuxt dari Awal Untuk Panduan Langkah demi Langkah.

Sumber Daya

Dokumentasi Nuxt
Dokumentasi Capacitor 8
@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

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 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 Plugins oleh Capgo Tambahkan atau Perbarui Plugins untuk detail implementasi di Tambahkan atau Perbarui Plugins Alternatif Plugin Bisnis Ionic untuk alur kerja produk di Alternatif Plugin Bisnis Ionic, dan Capgo Build Nativ untuk alur kerja produk di Capgo Build Nativ.

Mengubah Aplikasi Nuxt Anda ke iOS & Android dengan Capacitor 8