Buat Aplikasi Seluler Next.js dari Awal dengan Capacitor 8

Pendahuluan

Mau membuat aplikasi mobile dengan Next.js dari dasar? Panduan ini akan mengajarkan Anda cara membuat aplikasi Next.js 15 baru yang sudah terkonfigurasi untuk mobile sejak awal, lalu mengemasnya sebagai aplikasi native 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 mempublikasikan 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 penting
Aplikasi iOS dan Android asli
Konfigurasi pengembangan reload langsung

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

Persyaratan

Pastikan Anda telah menginstal hal-hal ini:

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

TypeScript: Ya (direkomendasikan)
ESLint: Ya
Tailwind CSS: Ya (direkomendasikan untuk gaya mobile)
src/ __CAPGO_KEEP_0__: 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 statis 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 — Menyediakan routing yang tepat di WebView Native

Langkah 3: Menambahkan 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 bangunan:

bun run build

Anda harus melihat sebuah out direktori 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 yang kebanyakan aplikasi mobile butuhkan:

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

Apa yang dilakukan plugin ini:

@capacitor/aplikasi — Acara siklus aplikasi (depan/belakang, tautan dalam)
@capacitor/keyboard — Mengontrol perilaku keyboard
@capacitor/layar-splash — Pengendalian layar splash native
@capacitor/status-bar — Mengatur baris 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)

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

Generate proyek asli:

bunx cap add ios
bunx cap add android

Ini menciptakan ios dan android direktori yang berisi proyek asli.

Langkah 7: Bangun dan Jalankan

Buat proyek Anda dan sinkronkan 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 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. 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 Anda akan memuat ulang secara otomatis di perangkat.

Langkah 9: Buat Layar Mobile Pertama

Mari kita buat 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 notch, indikator home, 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

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

Pengaturan Dasar

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

Tambahkan Fitur Lain

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

Peningkatan UI

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

bun add konsta

Pembaruan Melalui Jaringan

Tetapkan Capgo untuk memasang pembaruan tanpa resubmisi aplikasi toko:

bunx @capgo/cli init

Pengaturan Masalah

Pembangunan gagal dengan “Tidak Dapat Menemukan Modul” Jalankan bun install dan coba lagi.

iOS: “Tidak Dapat Menemukan Identitas Tanda Tangan” Buka Xcode, pergi ke Signing & Capabilities, dan pilih tim pengembangan Anda.

Android: “SDK lokasi tidak ditemukan” 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 pengembangan berjalan.

Sumber Daya

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

Buat Aplikasi Mobile Next.js dari Awal dengan Capacitor 8