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 cara mengubahnya menjadi aplikasi mobile native iOS dan Android menggunakan Capacitor 8 — versi terbaru dengan kinerja yang lebih baik dan fitur-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 di simulator iOS dan Android
Aktifkan reload hidup untuk pengembangan yang lebih cepat
Pecahkan 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.

Benefits of Using Next.js and Capacitor

Code Reusability: Next.js enables you to write reusable components and share code between your web and mobile apps, saving development time and effort.
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 splitting kode, 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.
: Capacitor 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 Capacitor, 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+ terinstal
Aplikasi Next.js yang sudah ada Xcode (untuk pengembangan iOS, hanya tersedia di 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.

Mengonfigurasi Aplikasi Next.js Anda untuk Mobile

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

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;

Konfigurasi ini menginformasikan Next.js untuk menghasilkan file HTML statis, dan output: 'export' menghindari Next.js optimasi gambar yang memerlukan server. images: { unoptimized: true } Penting:

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 sebuah

bun run build

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

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-plugin Capacitor yang umum digunakan:

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

Mengapa plugin-plugin ini penting:

@capacitor/app: Mengelola kejadian siklus aplikasi (depan/belakang, URL)
@capacitor/keyboard: Mengontrol perilaku keyboard di mobile
@capacitor/splash-screen: Mengelola layar splash native
@capacitor/preferencesSimpan 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 dengan konfigurasi yang tepat: capacitor.config.ts Pasang platform native:

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;

Tambahkan folder platform native:

bun add @capacitor/ios @capacitor/android

__CAPGO_KEEP_0__ akan membuat

bunx cap add ios
bunx cap add android

Capacitor will create ios context: Halaman/area: Situs web pemasaran Capgo. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman trust.astro. Kunci pesan `dan` (And). android folder di root proyek Anda yang berisi proyek native.

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

Membangun dan sinkronkan proyek Anda:

bun run mobile

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

Membangun dan Mengirimkan Aplikasi Native

Untuk membangun dan mengirimkan aplikasi mobile native, ikuti langkah-langkah berikut: Untuk mengembangkan aplikasi iOS, Anda membutuhkan Xcode terinstal, dan untuk aplikasi Android, Anda membutuhkan Android Studio terinstal. Selain itu, jika Anda berencana untuk mendistribusikan aplikasi Anda di toko aplikasi, Anda membutuhkan mendaftar ke Apple Developer Program untuk iOS dan Google Play Console untuk Android.

Mulai aplikasi 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

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 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 ke perangkat mobile.

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

Capacitor Reload Hidup

Pada tahap pengembangan, Anda dapat memanfaatkan reload hidup 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 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 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 tersebut.

Note: If you install new plugins or make changes to native files, you’ll need to rebuild the native project since live reloading only applies to web code changes.

Menggunakan Plugin Capacitor

Plugin Capacitor 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

Perintah ini menyalin folder web dan perubahan konfigurasi ke proyek native tanpa memperbarui proyek seluruhnya. pages/index.js Rebuild dan jalankan aplikasi di perangkat Anda menggunakan Android Studio atau Xcode.

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

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

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

Bangun ulang dan jalankan aplikasi di perangkat Anda.

Sekarang, ketika Anda mengklik tombol “Bagikan sekarang!”, dialog berbagi native akan muncul, memungkinkan Anda untuk berbagi 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 multi-platform, tetapi mengintegrasikannya dengan Next.js adalah hacky dan jarang berharga ketika Anda sudah memiliki Tailwind CSS 4.

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

@capgo/capacitor-native-navigation — navbar native, tab bar Liquid Glass pada iOS, dan gaya tab bar yang berbayang pada Android. Router Next.js Anda menjaga keadaan jalur; plugin ini menguasai chrome native.
@capgo/capacitor-transisi — Transisi halaman Ionic gaya dan iOS swipe-back tepi pada layer 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 sistem; Android menggunakan latar belakang WebView yang berbayang):

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-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. Simpan istilah produk/brand dan istilah developer 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. Simpan istilah produk/brand dan istilah developer 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. Simpan istilah produk/brand dan istilah developer Capgo secara tepat. Kunci pesan `capwesome_cta_questions` (Pertanyaan Tindakan Capwesome). | Fragment teks HTML dari string UI Capgo yang lebih panjang (kunci induk `consulting_faq_subtitle`). Halaman/area: Halaman layanan konsultasi. Peran: Judul atau tagline bagian. Dilihat di: halaman layanan-konsultasi.astro. Simpan istilah produk/brand dan istilah developer Capgo secara tepat. Kunci pesan `consulting_faq_subtitle` (Judul FAQ 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()Tidak duplikasi header atau footer web ketika navigasi native menguasai permukaan tersebut.

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

Daerah aman dengan Tailwind

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

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. Jalankan periksaan-periksaan ini secara berurutan. overflow-x: hidden Pastikan tag meta viewport diterapkan dengan benar

Router Aplikasi

: export (app/export 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 mengaplikasikan tag-tag dari _document.tsx cara Anda mengharapkan untuk perilaku viewport).

Tangani area aman iOS dari wrapper root saja

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

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 semua konten halaman di dalam .app-shellPengulangan padding area aman 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` context

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

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 muatan santai untuk komponen dan halaman untuk meningkatkan kinerja muatan awal.
Gunakan rendering server-side (SSR) dengan Next.js untuk meningkatkan kecepatan penggunaan 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 mobile native iOS dan Android menggunakan Capacitor 8. Kodebase web Anda sekarang dapat 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 tata letak iOS yang umum (viewport, area aman, overflow)
Menggunakan antarmuka 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

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

Sumber Daya

Dokumentasi Next.js
@capgo/capacitor-navigasi native – 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

Apa itu Capgo dan bagaimana cara membangun aplikasi yang lebih baik dengan lebih cepat menggunakan Capgo? Daftar diri untuk akun gratis hari ini. Teruskan dari Mengubah Aplikasi Next.js Anda ke iOS & Android dengan __CAPGO_KEEP_0__ 8

Jika Anda menggunakan Capacitor

__CAPGO_KEEP_0__ Ubah Aplikasi Next.js Anda ke iOS & Android dengan Capacitor 8 untuk merencanakan kerja 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, Tambahkan atau Perbarui Plugin untuk detail implementasi di Tambahkan atau Perbarui 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