Bangun Aplikasi Mobile Next.js dari Awal dengan Capacitor 8

Pendahuluan

Apakah Anda ingin membangun aplikasi mobile dengan Next.js dari dasar? Panduan ini akan membawa Anda melalui proses membuat proyek Next.js 15 baru yang sudah dikonfigurasi untuk mobile dari hari pertama, kemudian mengemasnya sebagai aplikasi mobile native iOS dan Android menggunakan Capacitor 8.

Dengan akhir tutorial ini, Anda akan memiliki aplikasi mobile yang berjalan di simulator yang dapat Anda lanjutkan mengembangkan dan akhirnya publikasikan ke App Store dan Google Play.

Waktu yang dibutuhkan: ~30 menit

Apa yang akan dibangun:

• Aplikasi Next.js 15 baru dengan App Router
• Konfigurasi ekspor statis untuk mobile
• Capacitor 8 dengan plugin yang penting
• Aplikasi iOS dan Android native
• Pengaturan pengembangan live reload

Sudah memiliki aplikasi Next.js? Cek Ubah Aplikasi Next.js Anda ke Mobile sebaliknya.

Prasyarat

Pastikan Anda telah menginstal hal-hal berikut:

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

Langkah 1: Buat Projek Next.js Baru

Mulai dengan membuat projek Next.js 15 yang segar:

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

Ketika diminta, pilih opsi-opsi berikut:

• Bahasa TypeScript: Ya (direkomendasikan)
• ESLint: Ya
• Tailwind CSS: Ya (direkomendasikan untuk gaya seluler)
• src/ direktori: Ya
• App Router: Ya (direkomendasikan)
• Alias import: Default (@/*)

Arahkan ke proyek Anda:

cd my-mobile-app

Langkah 2: Konfigurasi Next.js untuk Ekspor Statik

Capacitor memerlukan file HTML/JS/CSS statis. Konfigurasi Next.js untuk ekspor 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 Nativ

Langkah 3: Tambahkan Skrip Mobile

Update Anda package.json dengan 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"
  }
}

Tes bangun:

bun run build

Anda harus melihat sebuah out directory dengan file statis Anda.

Langkah 4: Pasang Capacitor 8

Pasang paket-paket inti Capacitor:

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

Pasang plugin-plugin yang paling penting bagi aplikasi mobile:

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

Apa yang dilakukan plugin ini:

• @capacitor/app – Acara kehidupan aplikasi (dalam latar depan/belakang, tautan dalam)
• @capacitor/keyboard – Mengontrol perilaku keyboard
• @capacitor/splash-screen – Mengontrol layar splash native
• @capacitor/status-bar — Atur status bar perangkat
• @capacitor/preference — Penyimpanan nilai kunci (seperti localStorage tetapi asli)

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 tampilan aplikasi Anda
• com.example.mymobileapp dengan ID aplikasi (notasi domain terbalik)

Ini menciptakan capacitor.config.ts. Perbarui 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

Instal paket platform:

bun add @capacitor/ios @capacitor/android

Membuat proyek native:

bunx cap add ios
bunx cap add android

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

membuat direktori yang berisi proyek native.

Langkah 7: Bangun dan Jalankan

bun run mobile

Membangun proyek Anda dan sinkron dengan platform native:

bun run mobile:ios

Buka di Simulator iOS:

bun run mobile:android

Atau Emulator Android:

1. Pada Xcode (iOS):
2. Pilih simulator dari dropdown perangkat Cmd + R

Klik tombol Play atau tekan

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

Langkah 8: Atur Ulang Reload Hidup

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

1. Cari alamat IP lokal Anda:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

2. Buat konfigurasi pengembangan Capacitor. 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;

3. Mulai server pengembangan dan salin konfigurasi ke native:

bun run dev &
NODE_ENV=development bunx cap copy

4. Rebuild di Xcode/Android Studio

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

Langkah 9: Buat Layar Mobile Pertama Anda

Marilah kita buat layar mobile yang sederhana dan ramah pengguna. 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 notch, indikator rumah, dan bar status. 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-Langkah Selanjutnya

Area: Halaman Pembangun Capgo / produk halaman bangun natively di awan. Peran: Label UI singkat atau item navigasi. Pesan kunci `native_build_builder_credit_next` (Kredit Pembangun Bangun Natively Next).

Anda telah memiliki aplikasi mobile Next.js yang berfungsi. Berikut adalah langkah-langkah yang perlu dilakukan:

• Pengaturan Dasar Ikon Aplikasi: ios/App/App/Assets.xcassets Ganti ikon default di android/app/src/main/res
• dan (Anda dapat melihat di halaman trust.astro kami). Pesan kunci `and` (Dan). Opsi pengaturan di proyek native atau gunakan @capacitor/splash-screen konfigurasi
• Deep Link: Konfigurasi skema URL untuk aplikasi Anda

Tambahkan Fitur Lebih Banyak

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

UI dan transisi native

Gunakan plugin Capgo alih-alih Konsta UI untuk merasakan pengalaman mobile native:

• @capgo/capacitor-native-navigation – Bar Pintu Kaca Liquid dan navbar native
• @capgo/capacitor-transisi – transisi halaman yang terasa asli

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

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

bun add -D tailwind-capacitor

Lihat Menggunakan @capgo/capacitor-navigasi native, Menggunakan @capgo/capacitor-transisi, dan repo tailwind-capacitor untuk pengaturan Next.js yang spesifik.

Pengaturan Layout iOS (Viewport, Daerah Aman, dan Overflows Horizontal)

Jika konten tampak dipotong, bergeser, atau dapat di-scroll ke kiri 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 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.

Tangani area aman iOS dari wrapper root saja

Buat shell aplikasi tunggal dan aplikasikan padding area aman di sana — bukan di komponen-komponen nested yang berbeda:

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

Tutup semua konten halaman di dalam .app-shellJangan duplikasi padding area aman di header, modal, dan wrapper layout untuk menghindari tampilan UI yang terpotong atau terlalu besar.

Dengan @capgo/tailwind-capacitor, Anda dapat mengekspresikan padding yang sama dengan utilitas seperti pt-safe pb-safe px-safe pada shell tunggal tersebut.

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

pertama capacitor.config.tsDalam 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-*) Pengaturan padding sering menyebabkan jarak ganda.

Cari elemen yang sebenarnya mengalami overflows.

Penyebab biasanya adalah elemen yang menggunakan 100vw, Tailwind w-screen, lebar piksel tetap, atau lebar yang sangat besar 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,
  }));

Dengan Tailwind, ganti w-screen dengan w-full ketika memungkinkan. Banyak masalah overflow horizontal berasal dari 100vw / w-screen, pengaturan padding area aman yang duplikat, atau kontainer dengan lebar tetap — bukan dari tag meta viewport itu sendiri.

Pembaruan Perangkat Jarak Jauh

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

bunx @capgo/cli init

Troubleshooting

Gagal membangun dengan "Cannot find module" Jalankan bun install dan coba lagi.

iOS: "Tidak dapat menemukan identitas tanda tangan" Buka Xcode, pergi ke Signing & Capabilities, dan pilih tim pengembangan Anda.

Andoid: "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, verifikasi alamat IP yang benar dan server pengembang sedang berjalan.

Sumber Daya

• Capacitor 8 Dokumentasi
• Dokumentasi Next.js 15
• Capgo - Live Updates
• @capgo/capacitor-native-navigation
• @capgo/capacitor-transisi
• @capgo/tailwind-capacitor

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

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

Jika Anda menggunakan Build a Next.js Mobile App from Scratch with Capacitor 8 untuk merencanakan otomatisasi CI/CD, hubungkannya dengan Capgo CI/CD for the product workflow in Capgo CI/CD, Capgo Native Builds for the product workflow in Capgo Native Builds, Capgo Integrations for the product workflow in Capgo Integrations, Integrasi untuk integrasi CI/CD di Capgo Builder / produk native cloud build, dan Aksi Integrasi GitHub untuk detail implementasi di Aksi Integrasi GitHub.