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

Introduction

Apakah Anda 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 lebih baik 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 React codebase. Unlike React Native, you don’t need to rewrite anything — your Next.js code runs as-is.

Apa yang akan Anda pelajari:

Konfigurasi aplikasi Next.js Anda untuk eksport statis
Add Capacitor 8 with essential native plugins
Bangun dan tes pada simulator iOS dan Android
Aktifkan reload hidup untuk pengembangan yang lebih cepat
Perbaiki masalah layout iOS yang umum (viewport, area aman, overflow horizontal)
Add native-feeling UI with Capgo Native Navigation and Transitions

Si Anda ingin memulai proyek baru dari awal? Membangun Aplikasi Mobile Next.js dari Awal.

Kelebihan Menggunakan Next.js dan Capacitor

Code Reusabilitas: Next.js memungkinkan Anda menulis komponen yang dapat digunakan kembali dan berbagi code antara aplikasi web dan mobile Anda, sehingga menghemat waktu dan upaya pengembangan.
Kinerja: Next.js offers built-in performance optimizations, such as server-side rendering and code splitting, ensuring fast loading times and a smooth user experience.
: Next.js menawarkan optimasi kinerja bawaan, seperti rendering server-side dan __CAPGO_KEEP_0__ splitting, sehingga memastikan waktu muat yang cepat dan pengalaman pengguna yang halus.: Capacitor provides access to native device features like the camera, geolocation, and more, allowing you to build feature-rich mobile apps.
: __CAPGO_KEEP_0__ memberikan akses ke fitur perangkat asli seperti kamera, lokasi geografis, dan lain-lain, sehingga memungkinkan Anda membangun aplikasi mobile yang kaya fitur.: With Capacitor, you can develop and test your mobile app using familiar web technologies, reducing the learning curve and streamlining the development process.

: Dengan __CAPGO_KEEP_0__, Anda dapat mengembangkan dan menguji aplikasi mobile Anda menggunakan teknologi web yang familiar, sehingga mengurangi kurva belajar dan mempercepat proses pengembangan.

Sebelum Anda memulai, pastikan Anda memiliki:

Node.js 18+ terpasang
Aplikasi Next.js yang sudah ada Next.js 15+ Xcode
untuk pengembangan iOS (hanya macOS) Android Studio
untuk pengembangan Android Mengonfigurasi Aplikasi Next.js Anda untuk Mobile

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

The first step is to configure your Next.js app for static export. Capacitor needs static HTML/JS/CSS files to bundle into the native app.

Terbuka file Anda 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 memberitahu Next.js untuk menghasilkan file HTML statis, dan images: { unoptimized: true } menghindari Next.js image optimization yang memerlukan server.

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

Tambahkan skrip khusus mobile ke file 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"
  }
}

Tes ekspor statis dengan menjalankan:

bun run build

Anda seharusnya melihat sebuah out folder di root project Anda. Folder ini berisi semua file statis yang Capacitor akan bundel ke dalam aplikasi native Anda.

Mengambahkan Capacitor 8 ke Projek Anda

Untuk mengemas aplikasi Next.js Anda ke dalam kontainer mobile native, ikuti langkah-langkah berikut:

Instal Capacitor core dan CLI:

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

Instal 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: Mengontrol perilaku keyboard di mobile
@capacitor/splash-screen: Mengelola layar splash native
@capacitor/preferencesSimpan data nilai secara persisten

Mulai Capacitor dengan detail proyek Anda:

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

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

Buat atau perbarui file capacitor.config.ts 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 context: Halaman/area: Situs web pemasaran Capgo. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman trust.astro. Kunci pesan `dan` (Dan).

To build the Android project, you need __CAPGO_KEEP_0__ Android Studio. For iOS, you need a Mac with __CAPGO_KEEP_0__ Xcode.

Build and sync your project:

bun run mobile

This runs your custom script that builds the Next.js project and syncs the static files with the native platforms.

Building and Deploying Native Apps

To build and deploy your native mobile app, follow these steps: To develop iOS apps, you need to have __CAPGO_KEEP_0__ Xcode installed, and for Android apps, you need to have __CAPGO_KEEP_0__ Android Studio 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.

Mulai aplikasi native:

For iOS:

bun run mobile:ios

For Android:

bun run mobile:android

Atau 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.
Pada Xcode, atur akun tanda tangan Anda untuk mengirimkan aplikasi ke perangkat nyata. Jika Anda belum pernah melakukannya sebelumnya, Xcode akan membantu Anda melalui proses tersebut (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 Next.js ke perangkat mobile.

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

Capacitor Reload Hidup

Pada tahap pengembangan, Anda dapat memanfaatkan reload hidup untuk melihat perubahan secara langsung di perangkat mobile Anda. Untuk mengaktifkan fitur ini, ikuti langkah-langkah berikut:

Cari alamat IP lokal Anda:

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

Ubah 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 pada proyek native Anda:

bunx cap copy

Hasilnya adalah copy Perintah ini menyalin folder web dan perubahan konfigurasi ke proyek native tanpa memperbarui proyek seluruhnya.

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 membangun proyek native kembali karena pengisian ulang hidup hanya berlaku untuk perubahan code web.

Menggunakan Capacitor Plugin

Capacitor plugin memungkinkan Anda untuk mengakses fitur perangkat native dari aplikasi Next.js. Mari kita jelajahi cara menggunakan plugin Share sebagai contoh: Instal plugin Share: Update file untuk menggunakan plugin Share:

Sinkronkan perubahan dengan proyek native:

bun add @capacitor/share

Sekarang, setiap kali Anda membuat perubahan pada aplikasi Next.js, aplikasi mobile akan secara otomatis reload untuk menampilkan perubahan-perubahan tersebut. pages/index.js Penting: Jika Anda menginstal plugin baru atau membuat perubahan pada file native, Anda perlu membangun proyek native kembali karena pengisian ulang hidup hanya berlaku untuk perubahan __CAPGO_KEEP_0__ web.

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

Menggunakan __CAPGO_KEEP_0__ Plugin

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

Rebuild 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 di iOS dan Android dengan Capgo navigasi dan transisi, dan memperbaiki masalah layout iOS yang umum menyebabkan overflow horizontal atau area aman yang dipotong. ## UI 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 merasakan mobile native di aplikasi Next.js + Capacitor, gunakan Capgo plugin alih-alih UI web-only seperti Konsta UI:

@capgo/capacitor-navigasi-native --- navbar native, tab bar Liquid Glass di iOS, dan gaya tab bar yang terhalang di Android. Router Next.js Anda menjaga keadaan jalur; plugin menguasai chrome native.
@capgo/capacitor-transisi --- Transisi halaman Ionic gaya dan iOS swipe-back di lapisan WebView, tanpa menerima UI Ionic.

Instal keduanya:

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 terhalang):

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:

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-pagedan cap-contentdan panggil setDirection('forward') atau setDirection('back') context: Fragment teks HTML dari string UI Capgo yang lebih panjang (kunci induk `alternatives_cta_questions`). Halaman/area: Halaman perbandingan alternatif Capacitor live-update. Peran: Paragraf pemasaran atau hukum yang panjang. Dilihat di: halaman perbandingan-alternatif.astro. Simpanlah istilah produk/brand dan istilah pengembang Capgo secara tepat. Kunci pesan `alternatives_cta_questions` (Pertanyaan Tindakan Alternatif). | Fragment teks HTML dari string UI Capgo yang lebih panjang (kunci induk `appflow_cta_questions`). Halaman/area: Halaman perbandingan/migrasi pemasaran Appflow. Peran: Paragraf pemasaran atau hukum yang panjang. Dilihat di: halaman ionic-appflow.astro. Simpanlah istilah produk/brand dan istilah pengembang Capgo secara tepat. Kunci pesan `appflow_cta_questions` (Pertanyaan Tindakan Appflow). | Fragment teks HTML dari string UI Capgo yang lebih panjang (kunci induk `capwesome_cta_questions`). Halaman/area: Halaman perbandingan Capawesome. Peran: Paragraf pemasaran atau hukum yang panjang. Dilihat di: halaman capwesome.astro. Simpanlah istilah produk/brand dan istilah pengembang Capgo secara tepat. Kunci pesan `capwesome_cta_questions` (Pertanyaan Tindakan Capwesome). | Halaman/area: Halaman jasa konsultasi. Peran: Judul atau tagline bagian. Dilihat di: halaman jasa-konsultasi.astro. Simpanlah istilah produk/brand dan istilah pengembang Capgo secara tepat. Kunci pesan `consulting_faq_subtitle` (Judul FAQ Jasa Konsultasi). | Halaman/area: Halaman perbandingan/migrasi pemasaran Appflow. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman ionic-appflow.astro, halaman ionic-enterprise-plugins.astro, halaman solusi/ionic-enterprise-plugins.astro. Kunci pesan `appflow_plugins_or` (Appflow Plugins Atau). router.push() atau router.back()Jangan duplikasi header atau footer web ketika navigasi native menguasai permukaan-permukaan tersebut.

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

bun add -D tailwind-capacitor

Menggunakan styles/globals.css:

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

Fasilitas seperti pt-safe, pb-safe, dan px-safe daripada menambahkannya secara manual. Projek ini aktif dikembangkan — jika ada sesuatu yang hilang untuk pengaturan Next.js Anda, env(safe-area-inset-*) buka PR di __CAPGO_KEEP_0__ open a PR on GitHub.

Jika konten terlihat dipotong, bergeser, atau dapat di-scroll secara horizontal di iOS, menambahkan lebih banyak

atau mengatur tag viewport saja biasanya tidak dapat memperbaikinya. Lakukan periksaan-periksaan ini secara berurutan. overflow-x: hidden Pastikan tag meta viewport diterapkan dengan benar

Router Aplikasi

: export (app/App Router viewport dari app/layout.tsx:

import type { Viewport } from 'next';

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

Router Halaman (pages/) masukkan tag meta viewport di pages/_app.tsx, bukan _document.tsx (Next.js mungkin tidak menerapkan tag-tag dari cara Anda mengharapkan untuk perilaku viewport). _document.tsx Tangani area aman iOS dari wrapper root saja

Buat shell aplikasi tunggal dan terapkan padding area aman di sana — bukan di komponen nested yang banyak:

Bungkus semua konten halaman di dalam

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

Pengulangan padding area aman di header, modal, dan wrapper layout sering membuat UI terlihat dipotong atau terlalu besar. .app-shellDengan

@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitorKamu bisa mengekspresikan padding yang sama dengan utilitas seperti pt-safe pb-safe px-safe di dalam shell tunggal itu.

Set Capacitor iOS `contentInset` ke `never` context

Page/area: Halaman produk live update. Peran: Label UI pendek atau item navigasi. Kunci pesan `live_update_dynamic_label_to` (Label Dinamis Live Update To). capacitor.config.tspertama contentInsetMode: 'css'Dalam

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-*) ) mengontrol area yang aman:

Menggabungkan __CAPGO_KEEP_0__’s automatic content inset dengan CSS

padding adalah penyebab umum dari jarak ganda. 100vwTailwind, w-screenlebar piksel tetap, atau 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,
  }));

With Tailwind, ganti w-screen dengan w-full ketika memungkinkan. Banyak masalah keluaran 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 pengisian data secara santai 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).
Maksimalkan 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. Kodebase web Anda sekarang berjalan secara native di perangkat mobile dengan akses ke API perangkat.

Apakah yang Anda capai:

Mengonfigurasi Next.js untuk ekspor statis
Menambahkan Capacitor 8 dengan plugin yang penting
Membangun dan mengirim ke simulator iOS dan Android
Mengaktifkan reload hidup untuk pengembangan
Mengatasi masalah layout iOS yang umum (viewport, area aman, overflow)
Menggunakan UI yang terasa native dengan Capgo Native Navigation dan Transisi

Langkah selanjutnya:

Konfigurasi Capgo untuk 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
Siapkan aplikasi Anda untuk pengiriman ke App Store dan Google Play

Membuat proyek baru? Cek Building a Next.js Mobile App from Scratch untuk panduan langkah demi langkah.

Sumber Daya

Next.js Documentation
@capgo/capacitor-native-navigation – Baja Kaca tab bar dan chrome asli
Capacitor 8 Dokumentasi
@capgo/capacitor-transisi – transisi halaman yang terasa asli
@capgo/tailwind-capacitor – utilitas daerah aman Tailwind untuk Capacitor
Capgo - Update Hidup untuk Aplikasi Capacitor

Belajar bagaimana Capgo dapat membantu Anda membuat aplikasi yang lebih baik dengan lebih cepat, daftar diri Anda untuk akun gratis hari ini.

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

Jika Anda menggunakan Ubah 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 Plugin oleh Capgo, Menambahkan atau Mengupdate Plugin untuk detail implementasi di Menambahkan atau Mengupdate Plugin, Alternatif Plugin Enterprise Ionic untuk alur kerja produk di Alternatif Plugin Enterprise Ionic, dan Capgo Pembangunan Native untuk alur kerja produk di Capgo Pembangunan Native.

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