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

Pendahuluan

Apakah Anda memiliki aplikasi web Next.js yang sudah ada? Dalam panduan ini, Anda akan belajar bagaimana mengubahnya menjadi aplikasi mobile native iOS dan Android menggunakan Capacitor 8 — versi terbaru dengan kinerja yang ditingkatkan dan fitur baru.

Capacitor membungkus aplikasi web Anda dalam 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 — Next.js code berjalan seperti semula.

Apakah yang akan Anda pelajari:

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

Inginkan memulai proyek baru dari awal? Cek panduan kami pada Membangun Aplikasi Mobile Next.js dari Awal.

Manfaat 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.
Page/area: Homepage problem/solution section. Role: Section or page heading. Seen in: page premium-support.astro. Message key `ps_help_performance_title` (Ps Help Performance Title).: Next.js menawarkan optimasi kinerja bawaan, seperti rendering server-side dan Capacitor splitting, sehingga 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, sehingga memungkinkan Anda membangun aplikasi mobile yang kaya fitur.

Pengembangan yang Sederhana

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

Prasyarat : Sebelum Anda memulai, pastikan Anda telah:
Node.js 18+ terinstal Next.js 15+ aplikasi
Xcode (untuk pengembangan iOS, macOS hanya)
Android Studio (untuk pengembangan Android)

Konfigurasi Aplikasi Next.js untuk Mobile

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

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;

Yang output: 'export' pengaturan ini menginformasikan Next.js untuk menghasilkan file HTML statis, dan images: { unoptimized: true } menghindari pengoptimalan gambar Next.js 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 untuk perangkat mobile Anda 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 ekspor statis dengan menjalankan:

bun run build

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

Menggunakan Capacitor 8 di 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 mungkin Anda butuhkan:

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

Fitur-fitur ini menyediakan fitur penting:

@capacitor/app: Menghandle kejadian siklus aplikasi (latar depan/belakang, URL)
@capacitor/keyboard: Mengontrol perilaku kibor di perangkat mobile
@capacitor/splash-screen: Mengelola layar splash native
@capacitor/preferences: Menyimpan data nilai-kunci 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 dengan konfigurasi yang tepat: capacitor.config.ts Buat atau perbarui file 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

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

Bangun dan sinkronkan proyek Anda:

bun run mobile

Menggunakan ini menjalankan skrip kustom Anda yang membangun proyek Next.js dan menyinkronkan file statis 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 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 bergabung dalam Program Pengembang Apple untuk iOS dan Google Play Console untuk Android.

Buka proyek native:

Untuk iOS:

bun run mobile:ios

Untuk Android:

bun run mobile:android

Atau secara 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 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 Next.js Anda ke perangkat mobile.

Tapi tunggu, 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:

Temukan alamat IP lokal Anda:

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

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: '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 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 Anda, 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-perubahan web code.

Memanfaatkan Capacitor Plugin

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

Pasang plugin Bagikan:

bun add @capacitor/share

Update file untuk menggunakan plugin Bagikan: pages/index.js Sinkronkan perubahan dengan proyek native:

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

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

Atau hanya sinkronisasi tanpa membangun ulang:

bun run mobile

Rebuild dan jalankan aplikasi di perangkat Anda.

bunx cap sync

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

Installasi plugin Bagikan:

Next, you can make the app feel more native on iOS and Android with Capgo navigation and transitions, and fix common iOS layout issues that cause horizontal overflow or cropped safe areas. ## Native-feeling UI with Capgo Native Navigation and Transitions

Membuat Aplikasi Seluler Asli dengan __CAPGO_KEEP_0__ Aplikasi Seluler Asli dengan __CAPGO_KEEP_0__ Saya telah bekerja selama bertahun-tahun dengan Ionic.

For a native mobile feel in a Next.js + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:

@capgo/capacitor-native-navigation Untuk merasakan aplikasi seluler asli dalam aplikasi Next.js + __CAPGO_KEEP_0__, gunakan plugin __CAPGO_KEEP_1__ alih-alih UI web-only seperti Konsta UI:
@capgo/capacitor-native-navigation — navbar native, Liquid Glass tab bar pada iOS, dan gaya tab bar yang diboroskan pada Android. Router Next.js Anda tetap menjaga status jalur; plugin ini menguasai chrome native.

@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions

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

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

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

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

Render tab bar Glass 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 native di dalam 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-page, dan cap-content, dan panggil setDirection('forward') atau setDirection('back') sebelum router.push() atau router.back(). Jangan duplikasi header atau footer web ketika navigasi native menguasai permukaan tersebut.

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

Area yang aman dengan Tailwind

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

bun add -D tailwind-capacitor

Dalam 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 daripada menaburkannya env(safe-area-inset-*) oleh tangan. Projek ini aktif dikembangkan — jika ada sesuatu yang hilang untuk pengaturan Next.js Anda, buka 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 overflow-x: hidden atau mengatur tag viewport sendiri biasanya tidak dapat memperbaikinya. Jalankan periksaan-periksaan ini secara berurutan.

Pastikan tag meta viewport diterapkan dengan benar

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

import type { Viewport } from 'next';

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

Pages Router (pages/letakkan tag meta viewport di pages/_app.tsx, bukan _document.tsx Untuk (Next.js mungkin tidak mengaplikasikan tag dari cara Anda mengharapkan untuk perilaku viewport). _document.tsx Atur zona aman iOS dari wrapper root saja.

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

Terapkan padding zona aman di shell tunggal tersebut.

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

Dengan menggunakan @__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__, Anda dapat mengungkapkan padding yang sama dengan utilitas seperti .app-shellon shell tunggal tersebut.

Setel __CAPGO_KEEP_0__ iOS ke @capgo/tailwind-capacitorlabel untuk live update pt-safe pb-safe px-safe label untuk live update

Set Capacitor iOS `contentInset` label untuk live update `never` pertama

Di capacitor.config.ts, lebih baik menggunakan inset native yang dinonaktifkan dan biarkan CSS (atau Navigasi Native) mengatur area yang aman: contentInsetMode: 'css'Menggabungkan __CAPGO_KEEP_0__’s automatic content inset dengan padding CSS

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-*) Temukan elemen yang sebenarnya mengalami kelebihan

Biasanya, penyebabnya adalah elemen yang menggunakan

, Tailwind 100vw, lebar piksel yang tetap, atau lebar yang sangat w-screenDi Safari Web Inspector, jalankan: min-width.

Dengan Tailwind, gantikan

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

__CAPGO_KEEP_0__ w-screen dengan w-full ketika memungkinkan. Banyak masalah keluaran horizontal berasal dari 100vw / w-screen, padding area aman yang di duplikat, 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:

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 sisi server (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. Kodebase web Anda sekarang berjalan secara native di perangkat mobile dengan akses ke API perangkat.

Apa yang telah Anda capai:

Mengatur Next.js untuk eksport statis
Menambahkan Capacitor 8 dengan plugin yang penting
Membangun dan mengirimkan ke simulator iOS dan Android
Mengaktifkan reload hidup untuk pengembangan
Mengatasi masalah tata letak iOS yang umum (viewport, area aman, overflow)
Menambahkan antarmuka yang terasa asli dengan Capgo Native Navigation dan Transisi

Langkah selanjutnya:

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

Membuat proyek baru? Cek Membangun 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 native
Capacitor 8 Dokumentasi
@capgo/capacitor-transisi — transisi halaman yang terasa native
@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 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 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 Natively untuk alur kerja produk di Capgo Pembangunan Natively

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