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

Pendahuluan

Sudah memiliki aplikasi web Next.js? 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 menggabungkan aplikasi web Anda ke dalam kontainer native, memberikan akses ke API perangkat seperti kamera, sistem file, dan notifikasi push sambil menjaga kode React yang ada. Berbeda dengan React Native, Anda tidak perlu menulis ulang apa pun — kode Next.js code berjalan seperti semula.

Apa yang akan Anda pelajari:

Konfigurasi aplikasi Next.js yang ada untuk ekspor statis
Tambahkan Capacitor 8 dengan plugin native yang penting
Bangun dan tes pada simulator iOS dan Android
Aktifkan ulang muat 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

Mencari proyek baru dari awal? Cek panduan kami pada Membangun Aplikasi Mobile dengan 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.
Performance: Next.js offers built-in performance optimizations, such as server-side rendering and code splitting, ensuring fast loading times and a smooth user experience.
Native Capabilities: Capacitor provides access to native device features like the camera, geolocation, and more, allowing you to build feature-rich mobile apps.
Simplified Development: With Capacitor, you can develop and test your mobile app using familiar web technologies, reducing the learning curve and streamlining the development process.

Prerequisites

Sebelum Anda memulai, pastikan Anda telah:

Node.js 18+ terinstal
Aplikasi web yang sudah ada Next.js 15+ Aplikasi
Xcode (untuk pengembangan iOS, macOS hanya)
Android Studio (untuk pengembangan Android)

Mengatur Aplikasi Next.js Anda untuk Mobile

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

The output: 'export' mengatur 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 ponsel 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"
  }
}

Uji coba 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 native.

Menggunakan Capacitor 8 di Proyek Anda

Untuk mengemas aplikasi Next.js Anda ke dalam kontainer ponsel 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 penting:

@capacitor/app@__CAPGO_KEEP_0__/keyboard
@capacitor/splash-screen@__CAPGO_KEEP_0__/preferences
Inisialisasi capacitor dengan detail proyek Anda:Ganti
@capacitor/preferences@__CAPGO_KEEP_0__/app

@Capacitor/keyboard

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

@__CAPGO_KEEP_0__/splash-screen my-app @__CAPGO_KEEP_0__/preferences com.example.myapp Dengan ID aplikasi Anda (notasi domain terbalik).

Buat atau perbarui capacitor.config.ts 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

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

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

Membangun dan sinkronkan proyek Anda:

bun run mobile

Perintah 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 memerlukan Xcode terpasang, dan untuk aplikasi Android, Anda memerlukan Android Studio terpasang. Selain itu, jika Anda berencana untuk mendistribusikan aplikasi Anda di toko aplikasi, Anda perlu mendaftar ke 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 langsung dengan Capacitor CLI:

bunx cap open ios
bunx cap open android

Build and run the 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 tanda tangan 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 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 dulu, 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:

Pada macOS, jalankan perintah berikut di terminal:
```
ipconfig getifaddr en0
```
Di 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).

Terapkan perubahan ke proyek asli Anda:

bunx cap copy

Fungsi copy mengcopy folder web dan perubahan konfigurasi ke proyek asli 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 seluler akan secara otomatis reload untuk menampilkan perubahan-perubahan tersebut.

Perlu diingat: Jika Anda menginstal plugin baru atau membuat perubahan pada file asli, Anda perlu membangun proyek asli kembali karena reload hidup hanya berlaku untuk perubahan web code.

Menggunakan Capacitor Plugin

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

Pasang plugin Bagikan:

bun add @capacitor/share

Perbarui pages/index.js file 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:

Seperti 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

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

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

## Tampilan UI yang Terasa Asli dengan __CAPGO_KEEP_1__ Navigasi dan Transisi Asli Saya telah bekerja selama bertahun-tahun dengan Ionic untuk membangun aplikasi lintas platform, tetapi mengintegrasikannya dengan Next.js adalah hacky dan jarang berharga ketika Anda sudah memiliki.

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

Untuk memberikan perasaan mobile asli pada aplikasi Next.js + capgo gunakan plugin capacitor bukan kit UI web saja seperti Konsta UI: @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation
@capgo/capacitor-transitions @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions

— transisi halaman yang mirip dengan Ionic dan swipe-back di lapisan WebView di iOS tanpa mengadopsi UI Ionic. Instal kedua:

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

Konfigurasi navigasi asli dengan mode CSS inset sehingga konten web menghormati bar-bar asli:

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 milik sistem; Android menggunakan latar belakang WebView yang diburamkan):

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 dalam shell aplikasi Anda:

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

initTransitions({ platform: 'auto' });

Bungkus halaman yang diarahkan 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 ketika navigasi asli menguasai permukaan tersebut.

Lihat panduan lengkap: Menggunakan @capgo/capacitor-native-navigation And 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. safe-areas utilities and other Capacitor-friendly Tailwind plugins:

bun add -D tailwind-capacitor

fasilitas dan plugin lainnya yang __CAPGO_KEEP_0__-ramah Tailwind: styles/globals.css:

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

Dalam pt-safe, pb-safeGunakan fasilitas seperti px-safe , dan env(safe-area-inset-*) dengan tangan. Projek ini aktif dikembangkan — jika ada sesuatu yang hilang untuk pengaturan Next.js Anda, buka PR di GitHub.

Mengatasi Masalah 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 menyesuaikan tag viewport saja biasanya tidak dapat memperbaikinya. Jalankan periksaan-periksaan ini secara berurutan.

Pastikan tag meta 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/): letakkan tag meta viewport di pages/_app.tsxdan bukan _document.tsx (Next.js mungkin tidak mengaplikasikan tag dari cara yang Anda harapkan untuk perilaku viewport). _document.tsx Atur zona aman iOS dari wrapper root saja.

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

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 zona 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-capacitordi shell tunggal tersebut. pt-safe pb-safe px-safe Atur __CAPGO_KEEP_0__ iOS

Set Capacitor iOS `contentInset` to `never` Pertama

Dalam capacitor.config.ts, lebih baik menggunakan inset asli yang dinonaktifkan dan biarkan CSS (atau Navigasi Asli) mengontrol area yang aman: contentInsetMode: 'css'Menggabungkan __CAPGO_KEEP_0__’s automatic content inset dengan 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 benar-benar mengalami overflows

Penyebab biasanya adalah elemen yang menggunakan

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

Dengan Tailwind, gantilah

[...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, replace w-screen dengan w-full ketika memungkinkan. Banyak masalah overflow horizontal berasal dari 100vw / w-screen, padding area yang aman yang diulang, atau kontainer dengan 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 penggunaan muatan yang ceroboh 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 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.

Apa yang telah Anda capai:

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

Langkah-langkah selanjutnya:

Tetapkan Capgo untuk pembaruan melalui udara tanpa pengiriman aplikasi ke toko aplikasi
Tambahkan plugin native lain 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

Mulai proyek baru? Cek Membangun Aplikasi Mobile Next.js dari Awal untuk panduan langkah demi langkah.

Sumber Daya

Dokumentasi Next.js
@capgo/capacitor-native-navigation — Tab Bar Liquid Glass dan Chrome Navigasi Asli
Capacitor 8 Dokumentasi
@capgo/capacitor-transitions — 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 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 Build Natively untuk alur kerja produk di Capgo Build Natively.

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