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 ditingkatkan dan 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 Anda akan pelajari:

Konfigurasi aplikasi Next.js Anda untuk eksport statis
Add Capacitor 8 with essential native plugins
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, 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 sisi server dan membagi 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+ terpasang
Suatu aplikasi Next.js 15+ Xcode
(untuk pengembangan iOS, macOS hanya) Android Studio
(untuk pengembangan Android) Pengaturan Aplikasi Next.js untuk Mobile

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

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-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 eksport 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 di root proyek Anda. Folder ini berisi semua file statis yang __CAPGO_KEEP_0__ akan bundel ke dalam aplikasi native Anda.

bun run build

Buka file 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 Capacitor yang 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 kejadian siklus aplikasi (depan/belakang, URL)
@capacitor/keyboard: Mengontrol perilaku keyboard di mobile
@capacitor/splash-screen: Mengelola layar splash native
@capacitor/preferencesSimpan data 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;

Instal 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 context: Halaman/area: Situs web pemasaran Capgo. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman trust.astro. Kunci pesan `dan` (Dan).

To build the Android project, you need __CAPGO_KEEP_0__ Studio AndroidFor iOS, you need a Mac with __CAPGO_KEEP_1__ Xcode.

Build and sync your project:

bun run mobile

This runs your custom script that builds the Next.js project and syncs the static files with the native platforms.

Building and Deploying Native Apps

To build and deploy your native mobile app, follow these steps: To develop iOS apps, you need to have __CAPGO_KEEP_1__ installed, and for Android apps, you need to have __CAPGO_KEEP_0__ installed. Selain itu, jika Anda ingin mendistribusikan aplikasi Anda di toko aplikasi, Anda perlu mendaftar ke Apple Developer Program untuk iOS dan Google Play Console untuk Android. __CAPGO_KEEP_1__ __CAPGO_KEEP_0__

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

Jalankan aplikasi di perangkat Anda menggunakan Android Studio atau Xcode. pages/index.js Sekarang, setiap kali Anda membuat perubahan pada aplikasi Next.js, aplikasi mobile akan secara otomatis reload untuk menampilkan perubahan tersebut.

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

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

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

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 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 Capgo plugin alih-alih UI web-only seperti Konsta UI:

@capgo/capacitor-navigasi-native --- navbar native, tab bar kaca Liquid Glass di iOS, dan gaya tab bar yang terhalang di Android. Router Next.js Anda menjaga keadaan jalur; plugin ini menguasai chrome native.
@capgo/capacitor-transisi --- Transisi halaman Ionic gaya dan iOS swipe-back di lapisan WebView, tanpa menerima UI Ionic.

Instal kedua:

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 kaca Liquid (iOS menggunakan rendering sistem; Android menggunakan latar belakang WebView yang terhalang):

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 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 router.push() atau router.back()Jangan duplikat header atau footer web ketika navigasi asli menguasai permukaan tersebut.

Lihat panduan lengkap: Menggunakan @capgo/capacitor-navigasi-asli dan Menggunakan @capgo/capacitor-transisi.

Area-aman dengan Tailwind

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

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

Router Aplikasi

eksport (app/eksport viewport menggunakan 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 ke pages/_app.tsx, bukan _document.tsx (Next.js mungkin tidak menerapkan tag dari cara Anda mengharapkan untuk perilaku viewport). _document.tsx Menangani area aman iOS dari wrapper root saja

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

Terapkan padding area aman di

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

Dipasang padding area aman yang sama 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-capacitoratau Anda dapat mengekspresikan padding yang sama dengan utilitas seperti pt-safe pb-safe px-safe di dalam shell tunggal itu.

Set Capacitor iOS `contentInset` ke `never` context: Halaman/Areas: Halaman produk live update. Peran: Label UI pendek atau item navigasi. Kunci pesan `live_update_dynamic_label_to` (Label Dinamis Live Update To).

pertama capacitor.config.tsDi contentInsetMode: 'css', lebih baik menggunakan inset asli native dan biarkan CSS (atau Native Navigation’s)

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-*) Menggabungkan __CAPGO_KEEP_0__’s automatic content inset dengan CSS

padding adalah penyebab umum dari jarak ganda.

Cari elemen yang sebenarnya mengalami overflownya adalah elemen yang menggunakan 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-screenduplikasi padding area aman, 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 penggunaan lazy loading untuk komponen dan halaman untuk meningkatkan kinerja muat awal.
Gunakan rendering server-side (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.

Apakah yang Anda capai:

Konfigurasi Next.js untuk ekspor statis
Tambahkan Capacitor 8 dengan plugin yang penting
Bangun dan terapkan ke simulator iOS dan Android
Aktifkan reload hidup untuk pengembangan
Perbaiki masalah layout iOS yang umum (viewport, area aman, overflow)
Tambahkan UI 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 Building a Next.js Mobile App from Scratch untuk panduan langkah demi langkah.

Sumber Daya

Next.js Documentation
@capgo/capacitor-native-navigation – Baja Kaca tab bar dan peramban 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 yang dapat Capgo lakukan untuk membantu Anda membuat 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 __CAPGO_KEEP_0__ 8

Keep going from Convert Your Next.js App to iOS & Android with Capacitor 8

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

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