Ubah Aplikasi 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 seluler iOS dan Android asli menggunakan Capacitor 8 — versi terbaru dengan kinerja yang ditingkatkan dan fitur baru.

Capacitor mengelilingi aplikasi web Anda dengan kontainer asli, 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 — Nuxt code berjalan seperti biasa.

Apa yang Anda akan pelajari:

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

Mencari proyek baru dari awal? Cek 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: Pengembangan statis Nuxt menciptakan bundle yang dioptimalkan sempurna untuk mobile.
• Kemampuan Asli: Akses fitur perangkat seperti kamera, lokasi geografis, dan filesystem melalui Capacitor plugin.
• Pengembangan yang Sederhana: Gunakan pola Vue/Nuxt yang familiar tanpa harus belajar pengembangan asli.

Prasyarat

Sebelum Anda memulai, pastikan Anda memiliki:

• Node.js 18+ terinstal
• Aplikasi yang sudah ada Nuxt 4 Xcode
• (hanya untuk pengembangan iOS di macOS) Android Studio
• (hanya untuk pengembangan Android) Mengonfigurasi Aplikasi Nuxt Anda untuk Mobile

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

Capacitor

Pastikan Anda memiliki skrip generate: package.json Penting:

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

Jika Anda menggunakan fitur server-side (__CAPGO_KEEP_0__ rute, middleware server, dll.), Anda perlu meredefinisi fitur-fitur tersebut untuk menggunakan alternatif sisi klien atau API eksternal. 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.

Anda seharusnya melihat sebuah

bun run generate

folder dengan file-file statis Anda. Ini adalah apa yang __CAPGO_KEEP_0__ akan bundel ke dalam aplikasi native Anda. .output/public folder with your static files. This is what Capacitor will bundle into your native app.

Adding Capacitor 8 to Your Project

Pasang __CAPGO_KEEP_0__ core dan __CAPGO_KEEP_1__:

1. Install Capacitor core and CLI:

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

2. Install common Capacitor plugins you’ll likely need:

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

Plugin-plugin ini menyediakan fitur-fitur penting:

• @capacitor/app@__CAPGO_KEEP_0__/keyboard
• @capacitor/splash-screen@__CAPGO_KEEP_0__/status-bar
• @capacitor/preferencesMulai __CAPGO_KEEP_0__ dengan detail proyek Anda:
• @capacitor/status-barGanti __CAPGO_KEEP_0__ dengan detail proyek Anda:
• Ganti capacitor dengan detail proyek Anda:Ganti __CAPGO_KEEP_0__ dengan detail proyek Anda:

3. Ganti Capacitor dengan detail proyek Anda:

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

Ganti __CAPGO_KEEP_0__ dengan detail proyek Anda: my-app dengan nama aplikasi Anda dan com.example.myapp dengan ID aplikasi Anda (notasi domain terbalik).

4. Buat atau update capacitor.config.ts file 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. Pasang 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 proyek Anda yang berisi proyek native.

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

7. Membangun dan sinkronkan proyek Anda:

bun run mobile

Hal ini menjalankan skrip kustom Anda yang menghasilkan bangunan statis Nuxt dan sinkronkan 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 memerlukan mendaftar ke Program Pengembang Apple 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. Buat dan jalankan aplikasi:

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

• Di 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 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:

1. Temukan alamat IP lokal Anda:

• Pada macOS, jalankan perintah berikut di terminal:

  ipconfig getifaddr en0

• Pada Windows, jalankan:

  ipconfig

  Cari alamat IPv4 di output.

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

3. Aplikasikan perubahan ke proyek asli Anda:

bunx cap copy

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

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

Catatan: Jika Anda menginstal plugin baru atau membuat perubahan pada file native, Anda perlu membangun kembali proyek native karena reload live hanya berlaku untuk perubahan web code.

Menggunakan Capacitor Plugin

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

1. Instal plugin Share:

bun add @capacitor/share

2. Buat atau perbarui halaman untuk menggunakan plugin Share. 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. Bongkar dan jalankan aplikasi pada perangkat Anda.

Sekarang, ketika Anda mengklik tombol “Bagikan sekarang!”, dialog berbagi asli akan muncul.

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

Antarmuka yang terasa asli dengan Capgo Navigasi dan Transisi Asli

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 asli di aplikasi Nuxt + Capacitor , gunakan Capgo plugin alih-alih kit UI web seperti Konsta UI:

• @capgo/capacitor-native-navigation — navbar asli, Liquid Glass tab bar di iOS, dan gaya tab bar yang diblur di Android. Router Nuxt Anda tetap menjaga status rute; plugin ini yang menguasai chrome asli.
• @capgo/capacitor-transitions — transisi halaman yang mirip dengan Ionic dan swipe-back di lapisan WebView di iOS tanpa mengadopsi UI Ionic.

Pasang kedua:

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

Konfigurasi navigasi native dengan mode CSS inset sehingga 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 milik sistem; Android menggunakan latar belakang WebView yang dibor):

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

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

Bungkus 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-native-navigation dan Menggunakan @capgo/capacitor-transisi.

Wilayah aman dengan Tailwind

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

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 oleh nuxt.config.ts.

Gunakan fasilitas seperti pt-safe, pb-safe, dan px-safe sebaliknya dari menyebarkan env(safe-area-inset-*) dengan tangan. Projek ini aktif dikembangkan — jika ada yang hilang untuk pengaturan 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, menambahkan lebih overflow-x: hidden atau mengatur tag viewport saja biasanya tidak dapat memperbaikinya. Kerjakan 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',
        },
      ],
    },
  },
});

Tangani area aman iOS dari satu wrapper root saja

Buat sebuah shell aplikasi tunggal dan aplikasikan padding area aman di sana — bukan di komponen-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);
}

Bungkus semua konten halaman di dalam .app-shell. Penggunaan 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 pada shell tunggal tersebut.

Atur Capacitor iOS contentInset ke never pertama

Dalam capacitor.config.ts, lebih baik mengaktifkan 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 sebenarnya mengalir melebihi batas

Biasanya, penyebabnya adalah elemen yang menggunakan 100vwTailwind w-screen, lebar piksel tetap, atau besar min-width.

Di 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 bila memungkinkan. Banyak masalah aliran horizontal berasal dari 100vw / w-screenpadding aman yang diulang, atau kontainer 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 berjalan secara native di perangkat mobile dengan akses ke API perangkat.

Apa yang Anda capai:

• Dikonfigurasikan Nuxt untuk penggabungan 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 pengguna yang terasa asli dengan Capgo Native Navigation dan Transisi

Langkah-langkah selanjutnya:

• Atur Capgo untuk pembaruan melalui udara tanpa pengiriman ulang ke toko aplikasi
• Tambahkan plugin native lain seperti Kamera, Lokasi, atau Notifikasi Push
• Konfigurasi ikon aplikasi dan layar splash untuk produksi
• Persiapkan aplikasi Anda untuk pengiriman ke App Store dan Google Play

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

Sumber Daya

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

Pelajari 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 Direktori Plugin Capgo untuk alur kerja produk di Direktori Plugin Capgo Plugin Capacitor oleh Capgo untuk detail implementasi di Capacitor Plugins oleh Capgo, Menambahkan atau Mengupdate Plugins untuk detail implementasi di Menambahkan atau Mengupdate Plugins, Alternatif Plugin Enterprise Ionic untuk alur kerja produk di Alternatif Plugin Enterprise Ionic, dan Capgo Build Natively untuk alur kerja produk di Capgo Build Natively.