Buat Aplikasi Mobile Next.js dari Awal dengan Capacitor 8

Pendahuluan

Ingin membuat 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 awal, lalu mengemasnya sebagai aplikasi mobile 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 publikasikan ke App Store dan Google Play.

Waktu yang dibutuhkan: ~30 menit

Apa yang akan dibangun:

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

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

Persyaratan

Pastikan Anda telah menginstal:

• 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, pilih opsi-opsi berikut:

• 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 Ekspor Statik

Capacitor memerlukan file-file HTML/JS/CSS statis. Konfigurasi Next.js untuk ekspor 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 — Menjamin routing yang tepat di WebView native

Langkah 3: Tambahkan Skrip Mobile

Perbarui dengan skrip pengembangan mobile: package.json Uji bangun:

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

bun run build

directory dengan file-file statis Anda. out Langkah 4: Pasang __CAPGO_KEEP_0__ 8

Capacitor requires static HTML/JS/CSS files. Configure Next.js for static export by updating

Pasang paket-paket inti Capacitor:

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

Pasang plugin-plugin yang paling umum digunakan oleh aplikasi mobile:

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

Apa yang dilakukan plugin-plugin ini:

• @capacitor/app — Acara siklus aplikasi (dalam latar belakang/atas, tautan dalam)
• @capacitor/keyboard — Mengontrol perilaku keyboard
• @capacitor/splash-screen — Mengontrol layar splash native
• @capacitor/status-bar — Mengatur tampilan bar status perangkat
• @capacitor/preferences — 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.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

Pasang paket platform:

bun add @capacitor/ios @capacitor/android

Membuat proyek native:

bunx cap add ios
bunx cap add android

Hal ini menciptakan ios dan direktori yang mengandung proyek native. android Langkah 7: Bangun dan Jalankan

Bangun proyek Anda dan sinkron dengan platform native:

Buka di Simulator iOS:

bun run mobile

Atau Emulator Android:

bun run mobile:ios

Di Xcode (iOS):

bun run mobile:android

Pilih simulator dari dropdown perangkat

1. Klik tombol Play atau tekan
2. Di Android Studio: Cmd + R

Tunggu Gradle untuk selesai sinkron

1. Pilih emulator dari dropdown perangkat
2. Tunggu beberapa saat
3. Klik tombol Run atau tekan Shift + F10

Langkah 8: Atur Ulang Live Reload

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

1. Cari alamat IP lokal Anda:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

2. 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;

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

Langkah 9: Buat Layar Mobile Pertama Anda

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 status bar. Tambahkan pengaturan area aman dengan Tailwind.

Update 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 Anda lakukan:

Pengaturan Dasar

• Ikon Aplikasi: Ganti ikon default di ios/App/App/Assets.xcassets dan android/app/src/main/res
• Layar Splash: Customize di proyek native atau gunakan @capacitor/splash-screen konfigurasi
• Deep Links: Konfigurasi Schemes URL untuk Aplikasi Anda

Tambahkan Fitur Lebih Banyak

• Kamera: bun add @capacitor/camera
• Lokasi: 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 Jarak Jauh Melalui Udara

Konfigurasi Capgo untuk memasukkan pembaruan tanpa pengajuan ulang ke toko aplikasi:

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: “Lokasi SDK 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 dev sedang berjalan.

Sumber Daya

• Capacitor 8 Dokumentasi
• Next.js 15 Dokumentasi
• Capgo - Live Updates
• Konsta UI - Komponen UI Mobile

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

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

Jika Anda menggunakan Buat 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 Nativ untuk alur kerja produk di Capgo Pembangunan Nativ, Capgo Integrasi untuk alur kerja produk di Capgo Integrasi, Integrasi CI/CD untuk detail implementasi di Integrasi CI/CD, dan GitHub Integrasi Aksi untuk detail implementasi di GitHub Aksi Integrasi.