Buat Aplikasi Seluler Next.js dari Awal dengan Capacitor 8

Indonesia: Bahasa

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

Dengan menyelesaikan tutorial ini, Anda akan memiliki sebuah aplikasi seluler yang berjalan dengan baik di simulator yang dapat Anda lanjutkan untuk dikembangkan dan akhirnya dipublikasikan di App Store dan Google Play.

Waktu yang dibutuhkan: ~30 menit

Apa yang akan dibangun:

Sebuah 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 dengan live reload

Sudah memiliki aplikasi Next.js? Periksa Konversi 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

Saat diminta, pilih opsi-opsi berikut:

TypeScript: Ya (direkomendasikan)
ESLint: Ya
Tailwind CSS: Ya (direkomendasikan untuk gaya mobile)
src/ directory: Ya
Router Aplikasi: Iya (direkomendasikan)
Import alias: Bawaan (@/*)

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 Nativ

Langkah 3: Tambahkan Skrip Mobile

Perbarui aplikasi 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 bangunan:

bun run build

Anda seharusnya melihat sebuah direktori dengan file statis Anda. out Langkah 4: Pasang __CAPGO_KEEP_0__ 8

Pasang paket-paket inti Capacitor:

Install the Capacitor core packages:

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

Apa yang plugin-plugin ini lakukan:

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

@__CAPGO_KEEP_0__/app

@capacitor/app @__CAPGO_KEEP_0__/keyboard
@capacitor/keyboard — Mengontrol perilaku keyboard
@capacitor/splash-screen — Kontrol layar splash native
@capacitor/status-bar — Gaya bar 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" dengan nama layar aplikasi Anda
com.example.mymobileapp dengan ID aplikasi Anda (notasi domain terbalik)

Membuat ini 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 asli:

bunx cap add ios
bunx cap add android

Membuat ini ios dan android direktori yang berisi proyek asli.

Langkah 7: Bangun dan Jalankan

Bangun proyek Anda dan sinkronkan dengan platform asli:

bun run mobile

Buka di Simulator iOS:

bun run mobile:ios

Atau Emulator Android:

bun run mobile:android

Dalam Xcode (iOS):

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

Dalam 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 reload hidup sehingga perubahan muncul secara instan di perangkat Anda.

Temukan alamat IP lokal Anda:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

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;

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 Seluler Pertama Anda

Mari kita buat layar seluler sederhana yang 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 seluler memiliki notches, indikator rumah, dan bilah status. Tambahkan pengaturan area aman dengan Tailwind. Perbarui

Struktur Proyek 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;
}

Proyek Anda sekarang harus terlihat seperti ini:

Langkah Selanjutnya

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

Anda telah memiliki aplikasi seluler Next.js yang berfungsi. Berikut adalah langkah-langkah selanjutnya:

Konfigurasi Dasar

Konfigurasi dasar telah selesai. Sekarang Anda dapat melanjutkan ke langkah-langkah selanjutnya.

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
Tautan dalam: Konfigurasi skema URL untuk aplikasi Anda

Tambah Fitur Lainnya

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

Antarmuka UI Asli dan transisi

Gunakan plugin Capgo daripada Konsta UI untuk merasakan perasaan mobile asli:

@capgo/capacitor-navigasi-native — Tab bar Liquid Glass dan navbar native
@capgo/capacitor-transisi — Transisi halaman yang merasa asli

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

Untuk area aman Tailwind, tambahkan @capgo/tailwind-capacitor:

bun add -D tailwind-capacitor

Lihat Menggunakan @capgo/capacitor-navigasi-native, Menggunakan @capgo/capacitor-transisidan repo tailwind-capacitor Setup untuk Next.js

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

Jika konten terlihat dipotong, bergeser, atau dapat di-scroll secara horizontal pada iOS, menambahkan lebih 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

Router Aplikasi (app/Pindahkan tag meta viewport ke viewport Router Halaman app/layout.tsx:

import type { Viewport } from 'next';

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

export (pages/dari pages/_app.tsxTidak termasuk _document.tsx.

Gunakan zona aman iOS dari satu wrapper root saja

Buatlah shell aplikasi tunggal dan aplikasikan padding zona 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 semua konten halaman di dalam .app-shell. Penggunaan padding zona aman yang berulang di header, modal, dan wrapper layout sering membuat tampilan UI terpotong atau terlalu besar.

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

Atur zona aman iOS Capacitor ke `contentInset` pertama `never` pertama

Pilih native inset disabled dan biarkan CSS (atau Native Navigation's capacitor.config.ts) mengontrol area yang aman: contentInsetMode: 'css'Menggabungkan __CAPGO_KEEP_0__’s automatic content inset dengan CSS

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-*) Cari elemen yang sebenarnya mengalami overflow

Penyebab biasanya adalah elemen yang menggunakan

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

Dengan Tailwind, gantilah

[...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 w-screen In w-full ketika memungkinkan. Banyak masalah overflow horizontal berasal dari 100vw / w-screen, padding area aman yang diulang, atau kontainer lebar tetap — bukan dari tag meta viewport itu sendiri.

Pembaruan Langsung Melalui Jaringan

Konfigurasi Capgo untuk memasukkan pembaruan tanpa perlu mengirimkan aplikasi ke toko aplikasi lagi:

bunx @capgo/cli init

Pengaturan Masalah

Pembaruan 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, pastikan alamat IP benar dan server pengembang berjalan.

Sumber Daya

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

Buat Aplikasi Mobile Next.js dari Awal dengan Capacitor 8