Konversi Aplikasi Next.js Anda ke iOS & Android dengan Capacitor 8

Pendahuluan

Memiliki aplikasi web Next.js 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 React yang sudah ada. Berbeda dengan React Native, Anda tidak perlu menulis ulang apa pun — aplikasi Next.js code berjalan seperti biasa.

Apa yang akan Anda pelajari:

Konfigurasi aplikasi Next.js Anda yang sudah ada untuk eksport 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 UI yang terasa native dengan Capgo Native Navigation dan Transisi

Mencari proyek baru untuk dimulai dari awal? Cek panduan kami di Membangun Aplikasi Mobile Next.js dari Awal.

Manfaat Menggunakan Next.js dan Capacitor

Reusabilitas Code: Next.js memungkinkan Anda menulis komponen yang dapat digunakan kembali dan berbagi code antara aplikasi web dan mobile Anda, menghemat waktu dan usaha pengembangan.
Kinerja: Next.js menawarkan optimasi kinerja bawaan, seperti rendering server-side dan code splitting, sehingga memungkinkan waktu muat yang cepat dan pengalaman pengguna yang halus.
Kemampuan Asli: Capacitor memberikan akses ke fitur perangkat asli seperti kamera, lokasi geografis, dan lain-lain, sehingga memungkinkan Anda untuk membangun aplikasi seluler yang kaya fitur.
Pengembangan yang Sederhana: Dengan Capacitor, Anda dapat mengembangkan dan menguji aplikasi seluler Anda menggunakan teknologi web yang familiar, sehingga mengurangi kurva belajar dan mempercepat proses pengembangan.

Prerequisites

: Sebelum Anda memulai, pastikan Anda telah:

Node.js 18+ terinstal
An existing Next.js 15+ Aplikasi
Xcode (untuk pengembangan iOS, macOS hanya)
Studio Android (untuk pengembangan Android)

Konfigurasi Aplikasi Next.js Anda untuk Mobile

Langkah pertama adalah mengonfigurasi aplikasi Next.js Anda untuk eksport statis. Capacitor membutuhkan file HTML/JS/CSS statis untuk dijadikan aplikasi native.

Buka file next.config.js (atau next.config.ts) file dan tambahkan konfigurasi ekspor:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
};

module.exports = nextConfig;

The output: 'export' pengaturan ini memerintahkan Next.js untuk menghasilkan file HTML statis, dan images: { unoptimized: true } menghindari optimasi gambar Next.js yang memerlukan server.

Perlu diingat: Jika Anda menggunakan fitur yang memerlukan server (API rute, komponen server dengan pengambilan data, dll.), Anda perlu meredefinisi fitur tersebut untuk menggunakan alternatif sisi klien atau API eksternal.

Tambahkan skrip khusus ponsel ke aplikasi Anda package.json:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "mobile": "bun run build && bunx cap sync",
    "mobile:ios": "bun run mobile && bunx cap open ios",
    "mobile:android": "bun run mobile && bunx cap open android"
  }
}

Uji coba ekspor statis dengan menjalankan:

bun run build

Kami harap Anda melihat sebuah out folder di root proyek Anda. Folder ini berisi semua file statis yang Capacitor akan bundel ke dalam aplikasi mobile native.

Mengintegrasikan Capacitor 8 ke Dalam Proyek Anda

Untuk mengemas aplikasi Next.js Anda ke dalam kontainer 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/preferences

Plugin ini menyediakan fitur-fitur penting:

@capacitor/app: Menghandle kejadian siklus aplikasi (depan/belakang, URL)
@capacitor/keyboard: Mengelola layar splash native
@capacitor/splash-screenMulai __CAPGO_KEEP_0__ dengan detail proyek Anda:
@capacitor/preferencesdengan nama aplikasi Anda dan

Initialize Capacitor with your project details:

bunx cap init my-app com.example.myapp --web-dir out

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

Membuat atau memperbarui 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: 'out',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      showSpinner: false,
      splashFullScreen: true,
      splashImmersive: true,
    },
  },
};

export default config;

Instal platform native:

bun add @capacitor/ios @capacitor/android

Tambahkan folder platform native:

bunx cap add ios
bunx cap add android

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

folder di root proyek Anda yang berisi proyek native. Studio AndroidAnda memerlukan Mac untuk iOS Xcode.

Bangun dan sinkronkan proyek Anda:

bun run mobile

ini menjalankan skrip kustom Anda yang membangun proyek Next.js dan sinkronisasi file statis dengan platform native.

Membangun dan Mengembangkan Aplikasi Nativ

Untuk membangun dan mengirimkan aplikasi mobile native Anda, ikuti langkah-langkah berikut: Untuk mengembangkan aplikasi iOS, Anda memerlukan Xcode installed, and for Android apps, you need to have Studio Android installed. Moreover, if you plan to distribute your app on the app store, you need to enroll in the Apple Developer Program for iOS and the Google Play Console for Android.

Buka proyek-proyek native:

Untuk iOS:

bun run mobile:ios

Untuk iOS:

bun run mobile:android

Dengan cara langsung menggunakan Capacitor CLI.

bunx cap open ios
bunx cap open android

atau secara langsung dengan __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ :

Studio Android Jalankan

In Studio Android, tunggu proyek siap, lalu klik tombol “Run” untuk mengirimkan aplikasi ke perangkat yang terhubung atau emulator.
In Xcode, atur akun tanda tangan Anda untuk mengirimkan aplikasi ke perangkat nyata. Jika Anda belum melakukannya sebelumnya, Xcode akan mengarahkan Anda melalui proses (perlu diingat bahwa Anda harus terdaftar di Program Pengembang Apple). Setelah diatur, klik tombol “Play” untuk menjalankan aplikasi pada perangkat yang terhubung.

Selamat! Anda telah berhasil mengirimkan aplikasi web Next.js 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:

Temukan alamat IP lokal Anda:

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

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: 'out',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
};

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 menyalin folder web dan perubahan konfigurasi ke proyek native tanpa mengupdate proyek secara keseluruhan.

Rebuild dan jalankan aplikasi di perangkat Anda menggunakan Android Studio atau Xcode.

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

Penting: Jika Anda menginstal plugin baru atau membuat perubahan pada file native, Anda perlu merebuild proyek native karena pengisian ulang hidup hanya berlaku untuk perubahan-perubahan web code.

Menggunakan Capacitor Plugin

Capacitor plugin memungkinkan Anda mengakses fitur perangkat native dari aplikasi Next.js Anda. Mari kita jelajahi cara menggunakan plugin Bagikan plugin sebagai contoh:

Pasang plugin Share:

bun add @capacitor/share

Update pages/index.js file untuk menggunakan plugin Share:

import Head from 'next/head';
import styles from '../styles/Home.module.css';
import { Share } from '@capacitor/share';

export default function Home() {
  const share = async () => {
    await Share.share({
      title: 'Open Youtube',
      text: 'Check new video on youtube',
      url: 'https://www.youtube.com',
      dialogTitle: 'Share with friends',
    });
  };

  return (
    <div className={styles.container}>
      <Head>
        <title>Create Next App</title>
        <meta name="description" content="Generated by create next app" />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className={styles.main}>
        <h1 className={styles.title}>
          Welcome to <a href="https://nextjs.org">Capgo!</a>
        </h1>

        <p className={styles.description}>
          <h2>Cool channel</h2>
          <button onClick={() => share()}>Share now!</button>
        </p>
      </main>
    </div>
  );
}

Sinkronkan perubahan dengan proyek native:

As yang telah disebutkan sebelumnya, ketika menginstal plugin baru, kita perlu melakukan operasi sinkronisasi dan kemudian redeploy aplikasi ke perangkat kita. Untuk melakukan ini, jalankan perintah berikut:

bun run mobile

atau hanya sinkronisasi tanpa membangun ulang:

bunx cap sync

Bangun ulang dan jalankan aplikasi di perangkat Anda.

Sekarang, ketika Anda mengklik tombol “Bagikan sekarang!”, dialog bagikan native akan muncul, memungkinkan Anda untuk membagikan konten dengan aplikasi lain.

Selanjutnya, Anda dapat membuat aplikasi terasa lebih native pada iOS dan Android dengan Capgo navigasi dan transisi, serta memperbaiki masalah layout iOS yang umum menyebabkan overflow horizontal atau area aman yang dipotong. ## UI yang terasa native dengan Capgo Navigasi dan Transisi Native

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

Untuk mendapatkan perasaan native mobile di aplikasi Next.js + Capacitor , gunakan plugin-plugin Capgo daripada kit UI web saja seperti Konsta UI.

@capgo/capacitor-navigasi native — navbar native, Liquid Glass tab bar pada iOS, dan gaya tab bar yang diblurkan pada Android. Router Next.js Anda tetap menjaga status route; plugin ini yang menguasai chrome native.
@capgo/capacitor-transisi — transisi halaman Ionic-style dan swipe-back iOS pada layer WebView, tanpa mengadopsi UI Ionic.

Install kedua-duanya:

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

Render sebuah tab bar kaca 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 asli di shell aplikasi Anda:

import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';

initTransitions({ platform: 'auto' });

Wrap halaman yang diarahkan dalam cap-router-outlet, cap-page, dan cap-content, dan panggil setDirection('forward') atau setDirection('back') context router.push() atau router.back()Jangan duplikasi header atau footer web ketika navigasi native mengendalikan permukaan-permukaan tersebut.

Lihat panduan lengkap: Menggunakan @capgo/capacitor-navigasi native and Gunakan @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 Tailwind yang Capacitor-ramah:

bun add -D tailwind-capacitor

In styles/globals.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

Pakai utilitas seperti pt-safe, pb-safe, dan px-safe sebagai ganti dari menambahkan secara manual. env(safe-area-inset-*) Projek ini aktif dikembangkan — jika ada yang hilang untuk pengaturan Next.js Anda, Membuka 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 mengatur tag viewport saja biasanya tidak dapat memperbaikinya. Jalankan periksaan-periksaan ini secara berurutan.

Pastikan tag meta viewport diterapkan dengan benar

Router Aplikasi (app/export dari viewport from app/layout.tsx:

import type { Viewport } from 'next';

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  viewportFit: 'cover',
};

): masukkan tag meta viewport di (pages/Tetapkan tag meta viewport pages/_app.tsx, not _document.tsx (Mungkin Next.js tidak menerapkan tag dari) _document.tsx seperti yang Anda harapkan untuk perilaku viewport).

Tangani zona aman iOS dari wrapper root saja

Buatlah shell aplikasi tunggal dan aplikasikan padding zona aman di sana — bukan di komponen nested beberapa kali:

html,
body,
#__next {
  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);
}

Tutup semua konten halaman di dalam .app-shell. Pengulangan padding zona aman di header, modal, dan wrapper layout sering membuat UI terlihat dipotong atau terlalu besar.

Dengan @capgo/tailwind-capacitoranda dapat menyatakan padding yang sama dengan utilitas seperti pt-safe pb-safe px-safe di shell tunggal itu.

Setel Capacitor iOS `contentInset` ke `never` context

Ini capacitor.config.tsgunakan inset disabled native dan biarkan CSS (atau Native Navigation's) contentInsetMode: 'css'Mengontrol 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-*) Biasanya, penyebabnya adalah elemen yang menggunakan

Temukan elemen yang mengalir melebihi

, lebar piksel yang tetap, atau lebar yang besar 100vw, Tailwind w-screenlebar piksel tetap, atau besar 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,
  }));

Dengan Tailwind, ganti w-screen with w-full ketika memungkinkan. Banyak masalah overflow horizontal berasal dari 100vw / w-screenpadding area aman yang diulang, atau kontainer lebar tetap — bukan dari tag meta viewport itu sendiri.

Pengoptimalan Kinerja

Untuk memastikan kinerja optimal dari aplikasi Next.js dan Capacitor Anda, pertimbangkan praktik terbaik berikut:

Minimalkan ukuran aplikasi dengan menghapus dependensi dan aset yang tidak digunakan.
Optimalkan gambar dan file media lainnya untuk mengurangi waktu muat.
Implementasikan penggunaan muatan yang cerdas untuk komponen dan halaman untuk meningkatkan kinerja muat awal.
Gunakan rendering server-side (SSR) dengan Next.js untuk meningkatkan kecepatan muat aplikasi dan optimasi mesin pencari (SEO).
Manfaatkan Capacitor’s optimasi bawaan, seperti caching view web dan penggabungan aplikasi.

Kesimpulan

Anda telah berhasil mengonversi aplikasi web Next.js yang sudah ada menjadi aplikasi native iOS dan Android menggunakan Capacitor 8. Kode web Anda sekarang berjalan secara native di perangkat mobile dengan akses ke API perangkat.

Apakah yang Anda capai:

Konfigurasi Next.js untuk ekspor statis
Ditambahkan Capacitor 8 dengan plugin-plugin penting
Membangun dan mengirimkan ke simulator iOS dan Android
Mengaktifkan ulang hidup untuk pengembangan
Mengatasi masalah tata letak iOS yang umum (viewport, area aman, overflow)
Menambahkan UI yang terasa asli dengan Capgo Navigasi dan Transisi Nativ

Langkah berikutnya:

Pengaturan Capgo untuk pembaruan melalui udara tanpa resubmisi aplikasi toko
Tambahkan lebih banyak plugin native 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

Membuat proyek baru? Cek keluaran terbaru Membuat Aplikasi Mobile Next.js dari Awal untuk panduan langkah demi langkah.

Sumber Daya

Dokumentasi Next.js
@capgo/capacitor-navigasi native — Tab Bar Kaca Liquid dan Chrome Asli
Capacitor 8 Dokumentasi
@capgo/capacitor-transisi @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transisi
@capgo/tailwind-capacitor – Utilitas area aman Tailwind untuk Capacitor
Capgo - Update Hidup untuk Aplikasi Capacitor

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

Teruskan dari Mengubah Aplikasi Next.js Anda ke iOS & Android dengan Capacitor 8

Jika Anda menggunakan Mengubah Aplikasi Next.js Anda ke iOS & Android dengan Capacitor 8 untuk merencanakan pekerjaan 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 Enterprise Ionic untuk alur kerja produk di Alternatif Plugin Enterprise Ionic, dan Capgo Pembangunan Nativ untuk alur kerja produk di Capgo Pembangunan Nativ.

Mengubah Aplikasi Web Anda ke iOS & Android dengan Capacitor 8