Buat Aplikasi Seluler Next.js dari Awal dengan Capacitor 8

Pendahuluan

Ingin membangun aplikasi mobile dengan Next.js dari dasar? Panduan ini akan mengajak Anda melalui proses membuat proyek Next.js 15 baru yang sudah terkonfigurasi untuk mobile dari hari pertama, lalu mengemasnya sebagai aplikasi mobile asli iOS dan Android menggunakan Capacitor 8.

Setelah menyelesaikan 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:

Proyek 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 di sini: Ubah Aplikasi Next.js Anda ke Mobile sebaliknya.

Prasyarat

Pastikan Anda telah menginstal hal-hal ini:

Node.js 18+ (periksa dengan node --version)
Bun pengelola paket (curl -fsSL https://bun.sh/install | bash)
Xcode (hanya 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, pilihlah opsi-opsi ini:

TypeScript: Ya (direkomendasikan)
ESLint: Ya
Tailwind CSS: Ya (direkomendasikan untuk gaya seluler)
src/ directory: Ya
App Router: Ya (direkomendasikan)
Import alias: Default (@/*)

Navigasikan 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 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 out direktori dengan file-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 diperlukan oleh aplikasi mobile sebagian besar:

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 kibor
@capacitor/splash-screen — Mengontrol layar splash native
@capacitor/status-bar — Atur status bar perangkat
@capacitor/preferensi — 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 Anda (notasi domain terbalik)

Hal ini menciptakan 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

Buat proyek native:

bunx cap add ios
bunx cap add android

Ini menciptakan ios dan android direktori yang berisi proyek native.

Langkah 7: Bangun dan Jalankan

Bangun proyek Anda dan sinkron dengan platform native:

bun run mobile

Buka di Simulator iOS:

bun run mobile:ios

Atau Emulator Android:

bun run mobile:android

Di Xcode (iOS):

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

Di Android Studio:

Tunggu Gradle selesai sinkronisasi
Pilih emulator dari dropdown perangkat
Klik tombol Jalankan 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.

Temukan alamat IP lokal Anda:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

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;

Mulai server dev dan salin konfigurasi ke native:

bun run dev &
NODE_ENV=development bunx cap copy

Rebuild di Xcode/Android Studio

Sekarang edit pada Next.js code akan reload panas di perangkat.

Langkah 9: Buat Layar Mobile Pertama

Mari kita buat layar home sederhana yang ramah perangkat 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 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 seharusnya 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

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

Pengaturan Dasar

Ikon Aplikasi: Ganti ikon default di ios/App/App/Assets.xcassets dan android/app/src/main/res
Layar Splash: Atur di proyek asli atau gunakan @capacitor/splash-screen __CAPGO_KEEP_0__
Deep Link: Tentukan skema URL untuk aplikasi Anda

Tambah Fitur Lain

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

Perbaikan UI

Pertimbangkan menambahkan Konsta UI untuk komponen iOS/Android yang terlihat asli:

bun add konsta

Pembaruan Melalui Jaringan

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

bunx @capgo/cli init

Pengaturan

Pemecahan Masalah Pembangunan gagal dengan “Tidak Dapat Menemukan Modul” bun install Jalankan

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

Android: “SDK location not found” Buat android/local.properties dengan sdk.dir=/path/to/android/sdk

Perubahan tidak muncul di perangkat Pastikan Anda menjalankan bun run mobile setelah membuat perubahan. Untuk live reload, verifikasi alamat IP yang benar dan server dev sedang berjalan.

Sumber Daya

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

Membangun Aplikasi Mobile Next.js dari Awal dengan Capacitor 8