Ubah 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 bagaimana mengubahnya menjadi aplikasi seluler 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 — kode React Next.js code berjalan seperti biasa.

Apa yang Anda akan pelajari:

Konfigurasi aplikasi Next.js yang sudah ada untuk eksport statis
Tambahkan Capacitor 8 dengan plugin native yang penting
Bangun dan tes pada simulator iOS dan Android
Aktifkan reload hidup untuk pengembangan yang lebih cepat
Perbaiki masalah tata letak iOS yang umum (viewport, area aman, keluaran horizontal)
Tambahkan UI yang terasa native dengan Capgo Native Navigation dan Transitions

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

Keuntungan 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 upaya pengembangan.
Kinerja: Next.js menawarkan optimasi kinerja yang dibangun secara built-in, seperti rendering sisi server dan code splitting, memastikan 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, memungkinkan Anda membangun aplikasi mobile yang kaya fitur.
Pengembangan yang Sederhana: Dengan Capacitor, Anda dapat mengembangkan dan menguji aplikasi mobile Anda menggunakan teknologi web yang familiar, mengurangi kurva belajar dan mempercepat proses pengembangan.

Prasyarat

Sebelum Anda memulai, pastikan Anda memiliki:

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

Langkah pertama adalah mengonfigurasi aplikasi Next.js Anda untuk ekspor statis. __CAPGO_KEEP_0__ memerlukan 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.

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

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

module.exports = nextConfig;

Pengaturan ini menginstruksikan Next.js untuk menghasilkan file HTML statis, dan output: 'export' menghindari pengoptimalan gambar Next.js yang memerlukan server. images: { unoptimized: true } Perlu diingat:

Jika Anda menggunakan fitur yang memerlukan server (__CAPGO_KEEP_0__ rute, komponen server dengan pengambilan data, dll.), Anda perlu meredefinisi fitur-fitur tersebut untuk menggunakan alternatif sisi klien atau API eksternal. If you’re using features that require a server (API routes, server components with data fetching, etc.), you’ll need to refactor those to use client-side alternatives or external APIs.

Uji coba ekspor statis dengan menjalankan: 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"
  }
}

Anda seharusnya melihat folder

bun run build

di root proyek Anda. Folder ini berisi semua file statis yang __CAPGO_KEEP_0__ akan bundel ke dalam aplikasi native. out folder at the root of your project. This contains all the static files that Capacitor will bundle into your native app.

Menambahkan 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: Mengelola event kehidupan aplikasi (depan/belakang, URL)
@capacitor/keyboard: Mengontrol perilaku keyboard di mobile
@capacitor/splash-screen: Mengelola layar splash native
@capacitor/preferences: Simpan data nilai-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;

Pasang 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 proyek Anda yang berisi proyek native.

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

Membangun dan sinkronkan proyek Anda:

bun run mobile

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

Membangun dan Mengirimkan Aplikasi Mobile Asli

Untuk membangun dan mengirimkan aplikasi mobile asli Anda, ikuti langkah-langkah berikut: Untuk mengembangkan aplikasi iOS, Anda perlu memiliki Xcode terpasang, dan untuk aplikasi Android, Anda perlu memiliki Android Studio terpasang. Selain itu, jika Anda berencana untuk mendistribusikan aplikasi Anda di toko aplikasi, 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

Buat dan jalankan aplikasi:

android-studio-run

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

Selamat! Anda telah berhasil mengirimkan aplikasi web Next.js Anda ke perangkat mobile.

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

Capacitor Reload Langsung Hidup

Pada tahap pengembangan, Anda dapat memanfaatkan fitur reload langsung untuk melihat perubahan secara instan pada perangkat mobile. 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.

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

Menggunakan Capacitor Plugins

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

Instal plugin Bagikan:

bun add @capacitor/share

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

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 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 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 merasakan mobile native di aplikasi Next.js + Capacitor, gunakan plugin Capgo daripada kit UI web seperti Konsta UI:

@capgo/capacitor-native-navigation — navbar native, tab bar Liquid Glass pada iOS, dan gaya tab bar yang diboroskan pada Android. Router Next.js Anda menjaga keadaan jalur; plugin ini menguasai chrome native.
@capgo/capacitor-transisi — transisi halaman Ionic gaya dan swipe-back iOS 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 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 dalam shell aplikasi Anda:

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

initTransitions({ platform: 'auto' });

Kemas halaman yang dilalui dengan cap-router-outlet, cap-page, dan cap-content, dan panggil setDirection('forward') atau setDirection('back') sebelumnya router.push() atau router.back(). Jangan duplikat header atau footer web ketika navigasi asli menguasai permukaan tersebut.

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

Wilayah aman dengan Tailwind

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

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 menambahkannya secara manual. Projek ini aktif dikembangkan — jika ada 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. Jalani periksaan-periksaan ini secara berurutan. overflow-x: hidden Pastikan tag meta viewport diterapkan dengan benar

App Router

: export (app/Pengaturan Layout iOS (Viewport, Area Aman, dan Overflows Horizontal) viewport Dari app/layout.tsx:

import type { Viewport } from 'next';

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

Pengaturan Halaman (pages/) masukkan tag meta viewport di pages/_app.tsx, tidak _document.tsx (Next.js mungkin tidak menerapkan tag dari _document.tsx pemahaman perilaku viewport Anda).

Handle area aman iOS dari satu wrapper root saja

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

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

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

Set Capacitor iOS `contentInset` ke `never` pertama

In capacitor.config.tsprefer inset native disabled dan biarkan CSS (atau Native Navigation’s) contentInsetMode: 'css') menguasai area 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 benar-benar mengalami keluaran

Biasanya, pelaku adalah elemen yang menggunakan 100vw, Tailwind 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 ketika memungkinkan. Banyak masalah keluaran horizontal berasal dari 100vw / w-screen, padding area aman yang diulang, atau kontainer lebar tetap — bukan dari tag meta viewport itu sendiri.

Optimasi Kinerja

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

Mengurangi ukuran aplikasi dengan menghapus dependensi dan aset yang tidak digunakan.
Optimalkan gambar dan file media lainnya untuk mengurangi waktu muat.
Implementasikan pengisian secara santai untuk komponen dan halaman untuk meningkatkan kinerja muat awal.
Gunakan rendering sisi server (SSR) dengan Next.js untuk meningkatkan kecepatan muat aplikasi dan optimasi mesin pencari (SEO).
Maksimalkan Capacitor’s optimasi bawaan, seperti caching tampilan 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.

Apa 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 tata letak iOS yang umum (viewport, area aman, overflow)
Mengambahkan tampilan UI yang terasa native dengan Capgo Native Navigation dan Transisi

Langkah-langkah selanjutnya:

Konfigurasi Capgo untuk pembaruan melalui udara tanpa pengajuan ulang 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 pengajuan ke App Store dan Google Play

Membuat proyek baru? Cek Membuat Aplikasi Mobile dari Nol dengan Next.js untuk panduan langkah demi langkah.

Sumber Daya

Dokumentasi Next.js
@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 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 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, 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.

Ubah Aplikasi Next.js Anda ke iOS &amp; Android dengan Capacitor 8