Build a Next.js Mobile App from Scratch with Capacitor 8

Pendahuluan

Mau membuat aplikasi seluler dengan Next.js dari awal? Panduan ini akan mengajarkan Anda cara membuat proyek Next.js 15 baru yang sudah terkonfigurasi untuk seluler dari hari pertama, lalu mengemasnya sebagai aplikasi iOS dan Android asli menggunakan Capacitor 8.

Setelah menyelesaikan tutorial ini, Anda akan memiliki aplikasi seluler yang berjalan dengan baik di simulator yang dapat Anda lanjutkan mengembangkan dan akhirnya menerbitkan ke App Store dan Google Play.

Waktu yang dibutuhkan: ~30 menit

Apa yang akan dibangun:

Proyek Next.js 15 baru dengan App Router
Konfigurasi ekspor statis untuk seluler
Capacitor 8 with essential plugins
Aplikasi iOS dan Android asli
Pengaturan pengembangan live reload

Sudah memiliki aplikasi Next.js? Cek dibandingkan.

Prasyarat

Pastikan Anda telah menginstal hal-hal berikut:

Node.js 18+ (periksa dengan node --version)
Bun manajer paket (curl -fsSL https://bun.sh/install | bash)
Xcode (hanya untuk macOS, untuk pengembangan iOS)
Android Studio (untuk pengembangan Android)

Langkah 1: Buat Proyek Next.js Baru

Mulai dengan membuat proyek Next.js 15 yang segar:

bunx create-next-app@latest my-mobile-app

Ketika diminta, pilih opsi-opsi berikut:

TypeScript: Ya (direkomendasikan)
ESLint: Ya
Tailwind CSS: Ya (direkomendasikan untuk gaya mobile)
src/ direktori: Ya
Rute Aplikasi: Ya (direkomendasikan)
Import alias: Default (@/*)

Pergi ke proyek Anda:

cd my-mobile-app

Langkah 2: Konfigurasi Next.js untuk Export Statik

Capacitor memerlukan file HTML/JS/CSS statis. Konfigurasi Next.js untuk export statik dengan mengupdate next.config.ts:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
  // Ensure trailing slashes for proper routing in Capacitor
  trailingSlash: true,
};

export default nextConfig;

Mengapa pengaturan ini?

output: 'export' — Membuat HTML statis bukan memerlukan server Node.js
images: { unoptimized: true } — Menonaktifkan Optimasi Gambar Next.js (memerlukan server)
trailingSlash: true — Menjamin routing yang tepat di WebView Native

Langkah 3: Tambahkan Skrip Mobile

Perbarui dengan package.json skrip pengembangan mobile:

{
  "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"
  }
}

Test build:

bun run build

Anda harus melihat direktori dengan file statis Anda. out Langkah 4: Pasang __CAPGO_KEEP_0__ 8

Pasang paket-paket inti Capacitor:

Install the Capacitor core packages:

bun add @capacitor/core
bun add -D @capacitor/cli

Apa yang dilakukan plugin ini:

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

@__CAPGO_KEEP_0__/app

@capacitor/app @__CAPGO_KEEP_0__/keyboard
@capacitor/keyboard — Mengontrol perilaku keyboard
@capacitor/layar-splash — Kontrol layar splash native
@capacitor/status-bar — Gaya bar status perangkat
@capacitor/preferensi — Penyimpanan nilai kunci (seperti localStorage tetapi native)

Langkah 5: Inisialisasi Capacitor

Inisialisasi Capacitor dengan detail proyek Anda:

bunx cap init "My Mobile App" com.example.mymobileapp --web-dir out

Ganti:

"My Mobile App" dengan nama layar aplikasi Anda
com.example.mymobileapp dengan ID aplikasi Anda (notasi domain terbalik)

Membuat capacitor.config.tsPerbarui dengan konfigurasi plugin:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      splashFullScreen: true,
      splashImmersive: true,
    },
    Keyboard: {
      resize: 'body',
      resizeOnFullScreen: true,
    },
    StatusBar: {
      style: 'light',
    },
  },
};

export default config;

Langkah 6: Tambahkan Platform Asli

Pasang paket platform:

bun add @capacitor/ios @capacitor/android

Membuat proyek native:

bunx cap add ios
bunx cap add android

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

direktori yang berisi proyek native.

Langkah 7: Bangun dan Jalankan

bun run mobile

Bangun proyek Anda dan sinkron dengan platform native:

bun run mobile:ios

Buka di Simulator iOS:

bun run mobile:android

In Xcode (iOS):

Pilih simulator dari dropdown perangkat
Klik tombol Play atau tekan Cmd + R

In Android Studio:

Tunggu Gradle selesai sinkronisasi
Pilih emulator dari dropdown perangkat
Klik tombol Run atau tekan Shift + F10

Langkah 8: Atur Ulang Reload Hidup

Untuk pengembangan yang lebih cepat, aktifkan ulang reload hidup sehingga perubahan muncul secara instan di perangkat Anda.

Cari alamat IP lokal Anda:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

Buat konfigurasi pengembangan Capacitor Anda. Tambahkan ke capacitor.config.ts:

import type { CapacitorConfig } from '@capacitor/cli';

const devConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
  plugins: {
    // ... same plugin config
  },
};

const prodConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  plugins: {
    // ... same plugin config
  },
};

const config = process.env.NODE_ENV === 'development' ? devConfig : prodConfig;

export default config;

Mulai server pengembangan dan salin konfigurasi ke native:

bun run dev &
NODE_ENV=development bunx cap copy

Rebuild di Xcode/Android Studio

Sekarang perubahan pada Next.js code akan memuat ulang secara otomatis di perangkat.

Langkah 9: Buat Layar Mobile Pertama

Buatlah layar home sederhana yang ramah mobile. Perbarui src/app/page.tsx:

'use client';

import { useEffect, useState } from 'react';
import { App } from '@capacitor/app';
import { Keyboard } from '@capacitor/keyboard';

export default function Home() {
  const [appInfo, setAppInfo] = useState<{ name: string; version: string } | null>(null);

  useEffect(() => {
    // Get app info on mount
    App.getInfo().then(setAppInfo).catch(console.error);

    // Handle back button on Android
    const backHandler = App.addListener('backButton', ({ canGoBack }) => {
      if (!canGoBack) {
        App.exitApp();
      } else {
        window.history.back();
      }
    });

    // Hide keyboard when tapping outside inputs
    const keyboardHandler = Keyboard.addListener('keyboardWillShow', () => {
      document.body.classList.add('keyboard-open');
    });

    return () => {
      backHandler.then(h => h.remove());
      keyboardHandler.then(h => h.remove());
    };
  }, []);

  return (
    <main className="min-h-screen bg-linear-to-b from-blue-500 to-blue-700 flex flex-col items-center justify-center p-6 text-white">
      <h1 className="text-4xl font-bold mb-4">My Mobile App</h1>
      <p className="text-xl mb-8 text-center opacity-90">
        Built with Next.js 15 + Capacitor 8
      </p>

      {appInfo && (
        <div className="bg-white/20 rounded-lg p-4 backdrop-blur-sm">
          <p className="text-sm">
            {appInfo.name} v{appInfo.version}
          </p>
        </div>
      )}

      <div className="mt-12 space-y-4 w-full max-w-sm">
        <button className="w-full py-4 px-6 bg-white text-blue-600 rounded-xl font-semibold text-lg shadow-lg active:scale-95 transition-transform">
          Get Started
        </button>
        <button className="w-full py-4 px-6 bg-white/20 text-white rounded-xl font-semibold text-lg backdrop-blur-sm active:scale-95 transition-transform">
          Learn More
        </button>
      </div>
    </main>
  );
}

Langkah 10: Tambahkan Pengaturan Area Aman

Perangkat mobile memiliki notches, indikator home, dan status bar. Tambahkan pengaturan area aman dengan Tailwind.

Perbarui src/app/globals.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

:root {
  --sat: env(safe-area-inset-top);
  --sar: env(safe-area-inset-right);
  --sab: env(safe-area-inset-bottom);
  --sal: env(safe-area-inset-left);
}

body {
  padding-top: var(--sat);
  padding-right: var(--sar);
  padding-bottom: var(--sab);
  padding-left: var(--sal);
}

/* Prevent text selection on mobile */
* {
  -webkit-user-select: none;
  user-select: none;
  -webkit-tap-highlight-color: transparent;
}

/* Allow text selection in inputs */
input, textarea {
  -webkit-user-select: auto;
  user-select: auto;
}

/* Keyboard handling */
.keyboard-open {
  --sab: 0px;
}

Struktur Proyek

Proyek Anda sekarang harus terlihat seperti ini:

my-mobile-app/
├── android/              # Android native project
├── ios/                  # iOS native project
├── out/                  # Static build output
├── src/
│   ├── app/
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   └── ...
├── capacitor.config.ts   # Capacitor configuration
├── next.config.ts        # Next.js configuration
├── package.json
└── ...

Langkah Selanjutnya

Kamu telah memiliki aplikasi mobile Next.js yang berfungsi. Berikut adalah langkah-langkah yang harus kamu lakukan:

Pengaturan Dasar

Ikon Aplikasi: Ganti ikon bawaan di ios/App/App/Assets.xcassets dan android/app/src/main/res
Layar Splash: Customisasi di proyek native atau gunakan @capacitor/splash-screen konfigurasi
Tautan dalam Negeri: Konfigurasi skema URL untuk aplikasi Anda

Tambah Fitur Lain

Kamera: bun add @capacitor/camera
Geolokasi: bun add @capacitor/geolocation
Notifikasi Push: bun add @capacitor/push-notifications
Sistem File: bun add @capacitor/filesystem

Antarmuka Native dan Transisi

Pilih plugin Capgo alih-alih Konsta UI untuk merasakan aplikasi mobile yang native:

@capgo/capacitor-native-navigation — Tab bar Liquid Glass dan navbar native
@capgo/capacitor-transitions — Transisi halaman yang terasa native

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

Untuk daerah aman Tailwind, tambahkan @capgo/tailwind-capacitor:

bun add -D tailwind-capacitor

Lihat Menggunakan @capgo/capacitor-native-navigation, Menggunakan @capgo/capacitor-transitions, dan repo Tailwind-capacitor untuk pengaturan Next.js yang spesifik.

Mengatasi Masalah Layout iOS (Viewport, Area Aman, dan Overflows Horizontal)

Jika konten terlihat dipotong, bergeser, atau dapat di-scroll secara horizontal pada iOS, menambahkan lebih banyak overflow-x: hidden atau mengatur tag viewport saja biasanya tidak dapat memperbaikinya. Jalankan periksaan-periksaan ini secara berurutan.

Pastikan tag meta viewport telah diterapkan dengan benar

App Router (app/dari viewport Pages Router app/layout.tsx:

import type { Viewport } from 'next';

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

letakkan tag meta viewport di (pages/protectedTokens pages/_app.tsxtidak _document.tsx.

Gunakan zona aman iOS dari wrapper root saja

Buatlah shell aplikasi tunggal dan aplikasikan padding zona 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);
}

Terapkan padding zona aman di .app-shell. Penggunaan padding zona 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 tersebut.

Setelkan Capacitor iOS `contentInset` ke `never` context: Halaman/area: Halaman produk update langsung. Peran: Label UI singkat atau item navigasi. Kunci pesan `live_update_dynamic_label_to` (Live Update Dynamic Label To).

Dalam 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-screenDalam 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,
  }));

dengan w-screen dengan w-full ketika memungkinkan. Banyak masalah keluaran horizontal datang dari 100vw / w-screenpadding area yang aman yang di duplikat, atau kontainer dengan lebar tetap — bukan dari tag meta viewport itu sendiri.

Pembaruan Melalui Jaringan

Konfigurasi Capgo untuk memasukkan pembaruan tanpa harus mengirimkan aplikasi ke toko aplikasi lagi:

bunx @capgo/cli init

Penyelidikan Masalah

context: Halaman/area: Halaman bantuan / premium bantuan atau bagian bantuan di footer. Peran: Judul bagian atau halaman. Dilihat di: halaman support-policy.astro. Kunci pesan `support_policy_troubleshooting_title` (Judul Penyelidikan Masalah Kebijakan Bantuan). Pembangunan gagal dengan “Tidak Dapat Menemukan Modul” bun install Jalankan

dan coba lagi. iOS: “Tidak Dapat Menemukan Identitas Tanda Tangan”

Aplikasi Android: “Lokasi SDK tidak ditemukan” Buat android/local.properties Dengan sdk.dir=/path/to/android/sdk

Perubahan tidak muncul di perangkat Pastikan Anda telah menjalankan bun run mobile Setelah membuat perubahan. Untuk live reload, pastikan alamat IP benar dan server pengembang berjalan.

Sumber Daya

Siap untuk mengirimkan aplikasi Anda? Pelajari bagaimana Capgo dapat membantu Anda mengirimkan pembaruan lebih cepat — daftar untuk akun gratis hari ini.

Teruskan dari Membangun Aplikasi Mobile Next.js dari Awal dengan Capacitor 8

Jika Anda menggunakan Membangun Aplikasi Mobile Next.js dari Awal dengan Capacitor 8 untuk merencanakan otomatisasi CI/CD, hubungkannya dengan Capgo CI/CD untuk alur kerja produk di Capgo CI/CD, Capgo Pembangunan Asli untuk alur kerja produk di Capgo Pembangunan Asli, Integrasi Capgo untuk alur kerja produk di Capgo Integrasi Integrasi CI/CD untuk detail implementasi di Integrasi CI/CD, dan Integrasi Aksi GitHub untuk detail implementasi di Integrasi Aksi GitHub.

Membuat Aplikasi Mobile Next.js dari Awal dengan Capacitor 8