Tutorial ini akan memandu Anda membuat aplikasi mobile menggunakan React dan Capacitor. Di akhir, Anda akan tahu cara mengubah web app React.js menjadi aplikasi mobile native dengan Capacitor, serta memberi kesan native dengan Capgo Native Navigation dan Transitions.
Capacitor memungkinkan transformasi web app React.js Anda menjadi aplikasi mobile native dengan mudah, tanpa perlu perubahan besar atau mempelajari strategi baru seperti React Native.
Prosesnya hanya butuh beberapa langkah sederhana, dan tanpa terasa app React.js Anda sudah menjadi aplikasi mobile yang berfungsi penuh. Jadi, ikuti terus karena kami akan memandu Anda sepanjang perjalanan ini.
Overview Capacitor
CapacitorJS adalah game-changer. Ia bisa terintegrasi secara seamless dengan proyek web apa pun dan membungkus app Anda ke dalam native webview sekaligus membuat proyek native Xcode dan Android Studio. Selain itu, lewat plugin-nya, Anda bisa mengakses fitur native perangkat seperti kamera via JS bridge.
Capacitor menawarkan cara praktis untuk membuat aplikasi mobile native tanpa ribet atau kurva pembelajaran yang curam. API yang simpel dan fungsionalitasnya yang efisien membuatnya mudah diintegrasikan ke dalam proyek Anda.
Setup Aplikasi React.js Anda
Mari pakai metode termudah untuk memulai aplikasi React. Kita akan menggunakan package manager npm untuk membuat app React baru:
npx create-react-app my-appUntuk mengubah proyek kita menjadi app mobile native, sebuah ekspor dari app kita diperlukan.
Kita akan kembali ke bagian ini sebentar lagi. Pertama, mari pahami cara mengintegrasikan Capacitor ke dalam app React kita.
Integrasi Capacitor ke dalam App React.js Anda
Langkah setup awal mungkin agak detail, tapi setelah itu, memperbarui native app wrapper Anda akan semudah menjalankan sebuah sync perintah.
Pertama, kita akan menginstal Capacitor CLI sebagai dev dependency dan menyiapkannya di dalam proyek. Saat setup, terima nilai default untuk name dan bundle ID dengan menekan "enter".
Selanjutnya, kita akan menginstal package inti dan package terkait untuk platform iOS dan Android.
Terakhir, kita akan menambahkan platform, dan Capacitor akan membuat folder untuk setiap platform di root proyek kita:
# Install the Capacitor CLI locally
npm install -D @capacitor/cli
# Initialize Capacitor in your React project
npx cap init
# Install the required packages
npm install @capacitor/core @capacitor/ios @capacitor/android
# Add the native platforms
npx cap add ios
npx cap add androidPanduan iOS dan Android direktori sekarang sudah ada di proyek React.js Anda.
Untuk mengakses proyek Android nanti, instal Android Studio. Untuk iOS, Anda memerlukan Mac dan sebaiknya menginstal Xcode.
Selanjutnya, perbarui webDir di file capacitor.config.json seperti di bawah ini:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "build",
"bundledWebRuntime": false
}Jalankan perintah build dan sinkronkan proyek Anda dengan Capacitor:
npm run build
npx cap syncPanduan npm run build command akan mem-build proyek React.js Anda, sementara npx cap sync akan menyelaraskan web code ke posisi yang tepat pada platform native agar bisa dijalankan di dalam aplikasi.
Sekarang, dengan sedikit keberuntungan dan tanpa error, aplikasi React.js Anda seharusnya sudah siap diluncurkan ke perangkat!
Build dan Deploy Native Apps Anda
Pengembangan aplikasi iOS memerlukan Xcode, dan aplikasi Android butuh Android Studio. Jika Anda berencana mendistribusikan aplikasi Anda di app store, Anda harus mendaftar di Apple Developer Program untuk iOS dan Google Play Console untuk Android.
Capacitor CLI mempermudah proses membuka kedua proyek native:
npx cap open ios
npx cap open androidSetelah proyek Native Build Anda siap, proses deploy aplikasi ke perangkat yang terhubung akan menjadi sangat mudah.
Untuk Android Studio, tunggu hingga semuanya selesai dimuat lalu deploy aplikasi Anda ke perangkat yang terhubung.
Untuk Xcode, atur signing account Anda untuk men-deploy aplikasi ke perangkat fisik, bukan sekadar simulator. Setelah itu, cukup tekan play untuk menjalankan aplikasi di perangkat yang terhubung, yang bisa Anda pilih di bagian atas.
Jika semua berjalan lancar, Anda telah berhasil mengubah aplikasi web React.js menjadi aplikasi mobile native!
Live Reload Capacitor
Framework pengembangan modern biasanya sudah punya hot reload, dan untungnya, Anda bisa mendapatkan hal yang sama dengan Capacitor tapi di perangkat mobile Anda!
Anda bisa mengakses aplikasi yang di-host secara lokal dengan live reload di jaringan Anda dengan membuat aplikasi Capacitor memuat konten dari URL tertentu.
Pertama, tentukan alamat IP lokal Anda. Di Mac, Anda bisa melakukannya dengan menjalankan ipconfig getifaddr en0 di terminal. Di Windows, jalankan ipconfig lalu cari alamat IPv4-nya.
Setelah itu, instruksikan Capacitor untuk memuat app langsung dari server dengan menambahkan parameter lain ke capacitor.config.ts file Anda:
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'my-app',
webDir: 'build',
bundledWebRuntime: false,
server: {
url: 'http://192.168.x.xx:3000',
cleartext: true
}
};
export default config;Pastikan IP dan port yang dipakai benar. Jalankan npx cap copy untuk menerapkan perubahan ini ke project native kita.
Setelah Anda deploy app sekali lagi lewat Android Studio atau Xcode, setiap perubahan di React app Anda akan otomatis di-reload dan langsung tampil di app!
Perlu diingat, jika ada plugin baru yang di-install, seperti kamera, native project harus di-rebuild. Ini karena file native-nya berubah dan tidak bisa di-update on the fly.
Menggunakan Plugin Capacitor
Mari kita lihat sekilas cara menggunakan plugin Capacitor. Mari kita instal satu yang sederhana, yaitu plugin Share, yang memunculkan dialog share bawaan:
npm i @capacitor/shareUntuk menggunakannya, import package tersebut dan panggil share() fungsinya dari aplikasi kita. Perhatikan App.js:
import { Share } from '@capacitor/share';
function ShareButton() {
const share = async () => {
await Share.share({
title: 'React App',
text: 'Visit this React App',
url: 'http://localhost:3000',
dialogTitle: 'Share with...'
});
};
return (
<button onClick={share}>
Share
</button>
);
}
export default ShareButton;Setelah menginstal plugin baru, jangan lupa sync lagi proyek React Anda menggunakan npx cap sync.
Selanjutnya, Anda bisa membuat aplikasi terasa lebih native di iOS dan Android dengan navigasi dan transisi Capgo, serta memperbaiki masalah layout iOS yang umum menyebabkan horizontal overflow atau safe area terpotong.
UI yang terasa native dengan Native Navigation dan Transitions dari Capgo
Saya sudah bertahun-tahun bekerja dengan Ionic untuk membangun aplikasi cross-platform, tapi mengintegrasikannya dengan React itu ribet dan jarang sepadan kalau Anda sudah punya Tailwind CSS.
Untuk nuansa mobile native di aplikasi React + Capacitor, gunakan plugin Capgo alih-alih UI kit khusus web seperti Konsta UI:
- @capgo/capacitor-native-navigation — navbar native, Liquid Glass tab bar di iOS, dan gaya tab bar blur di Android. React router Anda menjaga state route; plugin yang mengelola native chrome.
- @capgo/capacitor-transitions — transisi halaman ala Ionic dan fitur iOS edge swipe-back di layer WebView, tanpa harus memakai Ionic UI.
Install keduanya:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncKonfigurasi navigasi native dengan mode inset CSS agar konten web menyesuaikan dengan bar native:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Render Liquid Glass tab bar (iOS menggunakan rendering dari sistem; Android menggunakan backdrop WebView yang blur):
await NativeNavigation.setTabbar({
selectedId: 'home',
labelVisibilityMode: 'labeled',
icons: true,
colors: { dynamic: true },
tabs: [
{ id: 'home', title: 'Home', icon: { svg: '...' } },
{ id: 'settings', title: 'Settings', icon: { svg: '...' } },
],
});
await NativeNavigation.addListener('tabSelect', ({ id }) => {
navigate(`/${id}`);
});Tambahkan transisi halaman native di app shell Anda:
import { useEffect, useRef } from 'react';
import { useNavigate } from 'react-router-dom';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';
initTransitions({ platform: 'auto' });
export function AppShell() {
const navigate = useNavigate();
const outletRef = useRef<HTMLElement>(null);
useEffect(() => {
if (outletRef.current) {
setupRouterOutlet(outletRef.current, { platform: 'auto', swipeGesture: 'auto' });
}
}, []);
const openSettings = () => {
setDirection('forward');
navigate('/settings');
};
return <cap-router-outlet ref={outletRef}>{/* routes */}</cap-router-outlet>;
}Bungkus halaman yang di-route dengan cap-router-outlet, cap-page, dan cap-content, dan panggil setDirection('forward') atau setDirection('back') sebelum navigasi. Jangan duplikasi header atau footer web kalau navigasi native sudah menangani area tersebut.
Lihat panduan lengkapnya: Menggunakan @capgo/capacitor-native-navigation dan Menggunakan @capgo/capacitor-transitions.
Safe areas dengan Tailwind
Untuk safe area perangkat di Tailwind CSS, gunakan @capgo/tailwind-capacitor (diterbitkan sebagai tailwind-capacitor pada npm). Ini menyediakan safe-areas utilitas dan plugin Tailwind lain yang kompatibel dengan Capacitor:
bun add -D tailwind-capacitorDi src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Gunakan utilitas seperti pt-safe, pb-safe, dan px-safe daripada menyisipkan env(safe-area-inset-*) secara manual. Proyek ini dikembangkan secara aktif — jika ada yang kurang untuk setup React Anda, buka PR di GitHub.
Memperbaiki Masalah Layout iOS (Viewport, Safe Area, dan Horizontal Overflow)
Jika konten terlihat terpotong, bergeser, atau bisa di-scroll secara horizontal di iOS, menambahkan lebih banyak overflow-x: hidden atau hanya mengutak-atik tag viewport saja biasanya tidak memperbaikinya. Lakukan pemeriksaan ini secara berurutan.
Pastikan meta tag viewport diterapkan dengan benar
Tambahkan viewport meta tag di index.html di dalam <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Tangani iOS safe area hanya dari satu root wrapper
Buat satu app shell dan terapkan safe area padding di sana — bukan di beberapa komponen bersarang:
html,
body,
#root {
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);
}Bungkus seluruh konten halaman di dalam .app-shell. Padding safe-area yang dobel di header, modal, dan wrapper layout sering membuat UI terlihat terpotong atau terlalu besar.
Dengan @capgo/tailwind-capacitor, Anda bisa menggunakan padding yang sama dengan utility seperti pt-safe pb-safe px-safe pada satu shell tersebut.
Atur Capacitor iOS contentInset ke never dulu
Di capacitor.config.ts, lebih baik nonaktifkan native inset dan biarkan CSS (atau Native Navigation’s contentInsetMode: 'css') mengatur safe area:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'build',
ios: {
contentInset: 'never',
},
};Mencampur automatic content inset dari Capacitor dengan CSS env(safe-area-inset-*) padding sering kali menjadi penyebab spasi ganda.
Temukan elemen yang benar-benar overflow
Penyebab umumnya adalah elemen yang menggunakan 100vw, Tailwind w-screen, lebar pixel tetap, atau ukuran yang besar min-width.
Di Safari Web Inspector, jalankan:
[...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 Tailwind, ganti w-screen dengan w-full jika memungkinkan. Banyak masalah overflow horizontal berasal dari 100vw / w-screen, duplikasi safe-area padding, atau container berukuran tetap — bukan dari viewport meta tag itu sendiri.
Kesimpulan
Capacitor menawarkan cara yang mulus untuk membangun aplikasi native dari proyek web yang sudah ada, memberikan cara sederhana untuk berbagi code dan menjaga UI tetap konsisten.
Berkat teknologi seperti Capacitor, membangun aplikasi mobile dari aplikasi web React.js kini jauh lebih mudah. Tingkatkan skill web development Anda ke level berikutnya dengan membuat aplikasi mobile native yang mengesankan. Selamat coding!
Untuk info lebih lanjut tentang cara mempercepat proses pengembangan aplikasi Anda, daftar akun gratis sekarang hari ini.
Lanjutkan dari Membangun Aplikasi Mobile dengan Pure React.js dan Capacitor
Jika Anda menggunakan Membangun Aplikasi Mobile dengan Pure React.js dan Capacitor untuk merencanakan perilaku media dan antarmuka native, hubungkan dengan Menggunakan @capgo/capacitor-live-activities untuk kemampuan native di Menggunakan @capgo/capacitor-live-activities, @capgo/capacitor-live-activities untuk detail implementasi di @capgo/capacitor-live-activities, Menggunakan @capgo/capacitor-video-player untuk kapabilitas native saat menggunakan @capgo/capacitor-video-player, @capgo/capacitor-video-player untuk detail implementasi di @capgo/capacitor-video-player, dan Menggunakan @capgo/capacitor-native-navigation untuk kapabilitas native saat menggunakan @capgo/capacitor-native-navigation.
