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

Pendahuluan

Punya aplikasi web Next.js? Di panduan ini, Anda akan belajar cara mengubahnya menjadi mobile app iOS dan Android native menggunakan Capacitor 8 — versi terbaru dengan performa yang lebih baik dan fitur-fitur baru.

Capacitor membungkus web app Anda dalam container native, memberi akses ke API perangkat seperti kamera, filesystem, dan push notifications tanpa mengubah codebase React Anda. Berbeda dengan React Native, Anda tidak perlu menulis ulang apa pun — code Next.js Anda berjalan apa adanya.

Yang akan Anda pelajari:

Konfigurasi app Next.js Anda untuk static export
Tambahkan Capacitor 8 dengan plugin native esensial
Build dan test di simulator iOS dan Android
Aktifkan live reload untuk development yang lebih cepat
Perbaiki masalah layout iOS yang umum (viewport, safe area, horizontal overflow)
Tambahkan UI yang terasa native dengan Capgo Native Navigation dan Transitions

Ingin mulai proyek baru dari nol? Cek panduan kami tentang Membangun Mobile App Next.js dari Nol.

Keuntungan Menggunakan Next.js dan Capacitor

Reusability dengan Code: Next.js memungkinkan Anda menulis komponen yang dapat digunakan kembali dan berbagi code antara aplikasi web dan mobile, sehingga menghemat waktu dan tenaga pengembangan.
Performa: Next.js menawarkan optimasi performa bawaan, seperti server-side rendering dan code splitting, untuk memastikan waktu loading yang cepat dan pengalaman pengguna yang mulus.
Kemampuan Native: Capacitor memberikan akses ke fitur native perangkat seperti kamera, geolocation, dan lainnya, sehingga Anda bisa membangun aplikasi mobile yang kaya fitur.
Pengembangan Lebih Simpel: Dengan Capacitor, Anda dapat mengembangkan dan menguji aplikasi mobile menggunakan teknologi web yang sudah familiar, sehingga kurva pembelajaran lebih pendek dan proses pengembangan lebih ringkas.

Prerequisites

Sebelum memulai, pastikan Anda sudah memiliki:

Node.js 18+ terinstal
Yang sudah ada Next.js 15+ aplikasi
Xcode (untuk pengembangan iOS, macOS saja)
Android Studio (untuk pengembangan Android)

Konfigurasi Aplikasi Next.js Anda untuk Mobile

Langkah pertama adalah mengonfigurasi aplikasi Next.js Anda untuk static export. Capacitor membutuhkan file HTML/JS/CSS statis untuk di-bundle ke dalam native app.

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

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

module.exports = nextConfig;

Panduan output: 'export' pengaturan ini memerintahkan Next.js untuk membuat file HTML statis, dan images: { unoptimized: true } melewati optimasi gambar Next.js yang membutuhkan server.

Penting: Jika Anda menggunakan fitur yang butuh server (API routes, server components dengan data fetching, dll.), Anda perlu me-refactor-nya ke alternatif client-side atau API eksternal.

Tambahkan script khusus mobile ke 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 static export dengan menjalankan:

bun run build

Anda akan melihat folder out di root project Anda. Ini berisi semua file statis yang akan di-bundle oleh Capacitor ke dalam native app Anda.

Menambahkan Capacitor 8 ke Project Anda

Untuk membungkus app Next.js Anda ke dalam container mobile native, ikuti langkah-langkah ini:

Install Capacitor core dan CLI:

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

Install plugin Capacitor umum yang mungkin Anda butuhkan:

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

Plugin-plugin ini menyediakan fitur esensial:

@capacitor/app: Menangani event lifecycle aplikasi (foreground/background, URL)
@capacitor/keyboard: Mengontrol perilaku keyboard di mobile
@capacitor/splash-screen: Mengelola splash screen native
@capacitor/preferences: Menyimpan data key-value secara persisten

Inisialisasi 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 app ID Anda (notasi reverse domain).

Buat atau perbarui capacitor.config.ts file dengan konfigurasi yang sesuai:

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;

Install 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 di root project Anda yang berisi project native.

Untuk build project Android, Anda butuh Android Studio. Untuk iOS, Anda butuh Mac dengan Xcode.

Build dan sync proyek Anda:

bun run mobile

Ini menjalankan custom script Anda untuk build proyek Next.js dan sync file statis ke platform native.

Build dan Deploy Native App

Untuk build dan deploy native mobile app Anda, ikuti langkah-langkah ini: Untuk develop aplikasi iOS, Anda perlu memiliki Xcode terinstal, dan untuk aplikasi Android, Anda perlu memiliki Android Studio terinstal. Selain itu, jika Anda berencana mendistribusikan aplikasi di app store, Anda perlu mendaftar di Apple Developer Program untuk iOS dan Google Play Console untuk Android.

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

Build dan jalankan aplikasinya:

android-studio-run

Di Android Studio, tunggu hingga proyek siap, lalu klik tombol “Run” untuk deploy aplikasi ke perangkat yang terhubung atau emulator.
Di Xcode, atur signing account Anda untuk deploy aplikasi ke perangkat asli. Jika belum pernah melakukannya, Xcode akan memandu Anda (catatan: Anda harus terdaftar di Apple Developer Program). Setelah selesai, klik tombol “Play” untuk menjalankan aplikasi di perangkat Anda.

Selamat! Anda berhasil men-deploy web app Next.js ke perangkat mobile.

Tapi tunggu dulu, ada cara yang lebih cepat saat proses development...

Live Reload Capacitor

Selama development, Anda bisa memanfaatkan live reloading untuk melihat perubahan secara instan di perangkat mobile. Untuk mengaktifkan fitur ini, ikuti langkah berikut:

Cari alamat IP lokal Anda:

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

Perbarui file capacitor.config.ts untuk mengarah ke server development 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).

Terapkan perubahan ke native project Anda:

bunx cap copy

Panduan copy perintah ini menyalin folder web dan perubahan konfigurasi ke native project tanpa memperbarui seluruh project.

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

Sekarang, setiap kali Anda mengubah aplikasi Next.js, aplikasi mobile akan otomatis reload untuk menampilkan perubahan tersebut.

Catatan: Jika Anda menginstal plugin baru atau mengubah file native, Anda perlu melakukan rebuild pada native project karena live reloading hanya berlaku untuk perubahan web code.

Menggunakan Plugin Capacitor

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

Instal plugin Share:

bun add @capacitor/share

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

Seperti yang disebutkan sebelumnya, saat menginstal plugin baru, kita perlu melakukan operasi sync lalu redeploy aplikasi ke perangkat. Untuk melakukannya, jalankan perintah berikut:

bun run mobile

Atau cukup sinkronkan tanpa rebuild:

bunx cap sync

Rebuild dan jalankan aplikasi di perangkat Anda.

Sekarang, saat Anda mengklik tombol “Share now!”, dialog share native akan muncul, memungkinkan Anda membagikan konten ke aplikasi lain.

Selanjutnya, Anda bisa membuat aplikasi terasa lebih native di iOS dan Android dengan navigasi dan transisi Capgo, serta memperbaiki masalah layout iOS umum yang menyebabkan overflow horizontal atau area safe area yang terpotong. ## UI rasa native dengan Capgo Native Navigation dan Transitions

Saya sudah bertahun-tahun bekerja dengan Ionic untuk membangun aplikasi cross-platform, tapi mengintegrasikannya dengan Next.js terasa kurang rapi dan jarang sepadan jika Anda sudah punya Tailwind CSS 4.

Untuk mendapatkan feel mobile native di aplikasi Next.js + Capacitor, gunakan plugin Capgo alih-alih UI kit khusus web seperti Konsta UI:

@capgo/capacitor-native-navigation — navbar native, Liquid Glass tab bar di iOS, dan gaya tab bar blur di Android. Router Next.js Anda tetap menjaga state route; plugin yang mengelola native chrome.
@capgo/capacitor-transitions — transisi halaman ala Ionic dan fitur iOS edge swipe-back di layer WebView, tanpa harus memakai Ionic UI.

Install keduanya:

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

Konfigurasi navigasi native dengan mode inset CSS agar konten web menyesuaikan dengan bar native:

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

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

Render Liquid Glass tab bar (iOS menggunakan rendering dari sistem; Android menggunakan backdrop WebView yang blur):

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

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

initTransitions({ platform: 'auto' });

Bungkus halaman yang di-route dengan cap-router-outlet, cap-page, dan cap-content, dan panggil setDirection('forward') atau setDirection('back') sebelum router.push() atau router.back(). Jangan duplikasi header atau footer web jika navigasi native sudah mengelola area tersebut.

Lihat panduan lengkapnya: Menggunakan @capgo/capacitor-native-navigation dan Menggunakan @capgo/capacitor-transitions.

Safe areas dengan Tailwind

Untuk safe area perangkat di Tailwind CSS, gunakan @capgo/tailwind-capacitor (diterbitkan sebagai tailwind-capacitor pada npm). Ini menyediakan safe-areas utilitas dan plugin Tailwind lain yang kompatibel dengan Capacitor:

bun add -D tailwind-capacitor

Di styles/globals.css:

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

Gunakan utilitas seperti pt-safe, pb-safe, dan px-safe daripada menyisipkan env(safe-area-inset-*) secara manual. Proyek ini terus dikembangkan — jika ada yang kurang untuk setup Next.js Anda, buka PR di GitHub.

Memperbaiki Masalah Layout iOS (Viewport, Safe Area, dan Horizontal Overflow)

Jika konten terlihat terpotong, bergeser, atau bisa di-scroll secara horizontal di iOS, menambahkan lebih banyak overflow-x: hidden atau hanya mengutak-atik tag viewport saja biasanya tidak memperbaikinya. Lakukan pemeriksaan ini secara berurutan.

Pastikan meta tag viewport diterapkan dengan benar

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

import type { Viewport } from 'next';

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

Pages Router (pages/): masukkan viewport meta tag ke dalam pages/_app.tsx, bukan _document.tsx (Next.js mungkin tidak menerapkan tag dari _document.tsx cara yang Anda harapkan untuk perilaku viewport).

Tangani iOS safe area hanya dari satu root wrapper

Buat satu app shell dan terapkan safe area padding di sana — bukan di beberapa komponen bersarang:

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

Bungkus seluruh konten halaman di dalam .app-shell. Padding safe-area yang dobel di header, modal, dan wrapper layout sering membuat UI terlihat terpotong atau terlalu besar.

Dengan @capgo/tailwind-capacitor, Anda bisa menggunakan padding yang sama dengan utility seperti pt-safe pb-safe px-safe pada satu shell tersebut.

Atur Capacitor iOS `contentInset` ke `never` dulu

Di capacitor.config.ts, lebih baik nonaktifkan native inset dan biarkan CSS (atau Native Navigation’s contentInsetMode: 'css') mengatur safe area:

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

Mencampur automatic content inset dari Capacitor dengan CSS env(safe-area-inset-*) padding sering kali menjadi penyebab spasi ganda.

Temukan elemen yang benar-benar overflow

Penyebab umumnya adalah elemen yang menggunakan 100vw, Tailwind w-screen, lebar pixel tetap, atau ukuran yang 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 jika memungkinkan. Banyak masalah overflow horizontal berasal dari 100vw / w-screen, duplikasi safe-area padding, atau container berukuran tetap — bukan dari viewport meta tag itu sendiri.

Optimasi Performa

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

Minimalkan ukuran aplikasi dengan menghapus dependency dan asset yang tidak terpakai.
Optimalkan gambar dan file media lainnya untuk mempercepat waktu loading.
Implementasikan lazy loading pada komponen dan halaman untuk meningkatkan performa initial load.
Gunakan server-side rendering (SSR) dengan Next.js untuk meningkatkan kecepatan loading aplikasi dan search engine optimization (SEO).
Manfaatkan optimasi bawaan Capacitor, seperti web view caching dan app bundling.

Kesimpulan

Anda telah berhasil mengonversi aplikasi web Next.js Anda menjadi aplikasi native iOS dan Android menggunakan Capacitor 8. Codebase web Anda kini berjalan secara native di perangkat mobile dengan akses ke API perangkat.

Apa yang telah Anda capai:

Konfigurasi Next.js untuk static export
Menambahkan Capacitor 8 dengan plugin esensial
Build dan deploy ke simulator iOS dan Android
Aktifkan live reload untuk development
Perbaiki masalah layout iOS umum (viewport, safe area, overflow)
Tambahkan UI rasa native dengan Capgo Native Navigation dan Transitions

Next steps:

Siapkan Capgo untuk over-the-air updates tanpa submit ulang ke app store
Tambahkan lebih banyak native plugin seperti Camera, Geolocation, atau Push Notifications
Konfigurasi ikon aplikasi dan splash screen untuk produksi
Siapkan aplikasi Anda untuk submit ke App Store dan Google Play

Mau mulai proyek baru? Cek di sini Membangun mobile app Next.js dari nol untuk panduan langkah demi langkah.

Sumber Daya

Dokumentasi Next.js
@capgo/capacitor-native-navigation — Liquid Glass tab bar dan native chrome
Dokumentasi Capacitor 8
@capgo/capacitor-transitions — transisi halaman yang terasa native
@capgo/tailwind-capacitor — utilitas safe-area Tailwind untuk Capacitor
Capgo - Live Updates untuk Aplikasi Capacitor

Pelajari cara Capgo membantu Anda membangun aplikasi lebih baik dan cepat, daftar akun gratis sekarang hari ini.

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

Jika Anda menggunakan Konversi Aplikasi Next.js Anda ke iOS & Android dengan Capacitor 8 untuk merencanakan pekerjaan plugin native, hubungkan dengan Direktori Plugin Capgo untuk alur kerja produk di Direktori Plugin Capgo, Plugin Capacitor oleh Capgo untuk detail implementasi pada Capacitor Plugins oleh Capgo Menambahkan atau Memperbarui Plugin untuk detail implementasi pada Menambahkan atau Memperbarui Plugin, Alternatif Plugin Ionic Enterprise untuk alur kerja produk di alternatif plugin Ionic Enterprise, dan Capgo Native Build untuk alur kerja produk di Capgo Native Builds.