Membangun Aplikasi Mobile Next.js dari Awal dengan Capacitor 8

Pendahuluan

Apakah Anda ingin membangun aplikasi seluler dengan Next.js dari dasar? Panduan ini akan membantu Anda membuat proyek Next.js 15 baru yang sudah terkonfigurasi untuk seluler dari awal, kemudian mengemasnya sebagai aplikasi native iOS dan Android menggunakan __CAPGO_KEEP_0__ Capacitor 8.

Oleh akhir tutorial ini, Anda akan memiliki aplikasi seluler yang berjalan 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 dengan plugin yang penting
Aplikasi iOS dan Android asli
Pengaturan pengembangan reload langsung

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

Prasyarat

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 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/ direktori: Ya
App Router: Ya (direktori rekomendasi)
Import alias: Default (@/*)

Lihat proyek Anda di:

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 — Pastikan routing yang tepat di WebView asli

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

Uji coba bangun:

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/app — Acara kehidupan aplikasi (depan/belakang, tautan dalam)
@capacitor/keyboard — Mengontrol perilaku keyboard
@capacitor/splash-screen — Mengontrol layar splash native
@capacitor/status-bar — Mengatur tampilan status perangkat
@capacitor/preferences — 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" bersama dengan nama layar aplikasi Anda
com.example.mymobileapp bersama 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 Nativ

Pasang paket platform:

bun add @capacitor/ios @capacitor/android

Menghasilkan proyek-proyek natif:

bunx cap add ios
bunx cap add android

ini menciptakan 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-proyek natif.

Langkah 7: Bangun dan Jalankan Aplikasi Anda

bun run mobile

Terbuka di Simulator iOS:

bun run mobile:ios

Atau Emulator Android:

bun run mobile:android

Dalam Xcode (iOS):

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

Dalam Studio Android:

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

Mari kita buat layar home 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.

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 sekarang memiliki aplikasi mobile Next.js yang berfungsi. Berikut langkah-langkah selanjutnya:

Pengaturan Dasar

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

Tambahkan Fitur Lainnya

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

Antarmuka dan Transisi Asli

Pakai plugin Capgo alih-alih Konsta UI untuk merasakan perangkat seluler asli:

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

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 Memakai @capgo/capacitor-native-navigation, Memakai @capgo/capacitor-transisi, dan repo tailwind-capacitor untuk pengaturan khusus Next.js.

Pengaturan 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 menyesuaikan tag viewport sendiri biasanya tidak dapat memperbaikinya. Lakukan periksaan-periksaan ini secara berurutan.

Pastikan tag meta viewport diterapkan dengan benar

App Router (app/export dari viewport Pengaturan app/layout.tsx:

import type { Viewport } from 'next';

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

Rute Halaman (pages/Masukkan tag meta viewport di pages/_app.tsx, bukan _document.tsx.

Gunakan area aman iOS dari wrapper root saja

Buatlah shell aplikasi tunggal dan berikan padding area aman di sana — bukan di komponen nested yang banyak:

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 area aman di .app-shellJangan menambahkan padding area aman di header, modal, dan wrapper layout karena hal ini 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.

Set Capacitor iOS `contentInset` ke `never` pertama

Di capacitor.config.ts, lebih baik menggunakan inset disabled asli dan biarkan CSS (atau Native Navigation’s) contentInsetMode: 'css') mengelola area yang aman:

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'out',
  ios: {
    contentInset: 'never',
  },
};

Menggabungkan Capacitor’s automatic content inset dengan padding CSS adalah penyebab umum dari jarak ganda. env(safe-area-inset-*) Temukan elemen yang benar-benar mengalir keluar

Biasanya, pelaku adalah elemen yang menggunakan

, Tailwind 100vw, lebar piksel tetap, atau besar w-screenInspektor Web Safari, jalankan: min-width.

In Safari Web Inspector, run:

[...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,
  }));

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

Pembaruan Melalui Jaringan

Konfigurasi Capgo Pengaturan

bunx @capgo/cli init

Pemecahan Masalah

Ketika Build gagal dengan "Cannot find module" bun install Jalankan

iOS: “Tidak ditemukan 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 pengembangan berjalan.

Sumber Daya

Siap untuk mengirimkan aplikasi Anda? Pelajari bagaimana Capgo dapat membantu Anda mengirimkan pembaruan lebih cepat — daftar gratis sekarang 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, hubungkan dengan Capgo CI/CD untuk alur kerja produk di Capgo CI/CD, Capgo Pembangunan Nadi Asli untuk alur kerja produk di Capgo Pembangunan Nadi Asli 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 Integrasi Aksi

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