This tutorial will walk you through crafting a mobile application using React and Capacitor. By the end, you’ll know how to morph a React.js web app into a native mobile application with Capacitor, and add a native feel with Capgo Native Navigation and Transitions.
Capacitor enables the easy transformation of your React.js web app into a native mobile application, requiring no substantial alterations or learning of new strategies such as React Native.
Prosesnya melibatkan beberapa langkah sederhana, dan sebelum Anda menyadari, aplikasi React.js Anda akan menjadi aplikasi seluler yang berfungsi sepenuhnya. Jadi, tetaplah bersama kami dalam perjalanan ini.
Capacitor Overview
CapacitorJS adalah perubahan besar. Ia dapat menyatu dengan proyek web apa pun dan menggabungkan aplikasi Anda ke dalam tampilan web native sambil menghasilkan proyek Xcode dan Android Studio native. Selain itu, melalui plugin-nya, Anda dapat mengakses fitur perangkat native seperti kamera melalui jembatan JS.
Capacitor offers a straightforward way to create a native mobile application without any hassle or steep learning curve. Its simple API and streamlined functionality make it easy to incorporate into your project.
Menyiapkan Aplikasi React.js
Mari kita lakukan metode yang paling sederhana untuk memulai aplikasi React. Kami akan menggunakan manajer paket npm untuk membuat aplikasi React baru:
npx create-react-app my-appUntuk mengubah proyek kami menjadi aplikasi mobile native, sebuah export dari aplikasi kami diperlukan.
Kami akan kembali ke hal ini dalam beberapa saat. Terlebih dahulu, mari kita pahami cara mengintegrasikan Capacitor ke dalam aplikasi React kami.
Mengintegrasikan Capacitor ke dalam Aplikasi React.js
Langkah awal pengaturan mungkin sedikit rinci, tetapi setelah itu, memperbarui wrapper aplikasi native Anda menjadi seolah-olah menjalankan sync perintah.
Pertama, kami akan menginstal Capacitor CLI sebagai dependensi pengembangan dan mengaturnya dalam proyek kami. Selama pengaturan, menerima nilai default untuk nama dan ID paket dengan menekan “enter.”
Kemudian, kami akan menginstal paket inti dan paket yang relevan untuk platform iOS dan Android.
Terakhir, kita akan menambahkan platform, dan Capacitor akan membuat folder untuk setiap platform di root project 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 androidDan iOS dan Android sekarang sudah ada direktori di project React.js kita.
Untuk mengakses project Android nanti, instal Studio Android. Untuk iOS, Anda memerlukan Mac dan harus menginstal Xcode.
. Selanjutnya, update webDir di dalam capacitor.config.json seperti yang ditunjukkan di bawah:
{
"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 syncPerintah npm run build akan membangun proyek React.js Anda, sementara npx cap sync Akan menyinkronkan web code di tempat yang tepat di platform native sehingga dapat dieksekusi di aplikasi.
Sekarang, dengan sedikit keberuntungan dan tidak ada kesalahan, aplikasi React.js Anda seharusnya sudah siap untuk diluncurkan di perangkat!
Membangun dan Mengembangkan Aplikasi Native
Membangun aplikasi iOS memerlukan Xcode, dan aplikasi Android memerlukan Studio AndroidJika Anda berencana untuk mendistribusikan aplikasi Anda di toko aplikasi, Anda harus mendaftar ke Program Pengembang Apple untuk iOS dan Console Google Play untuk Android.
Capacitor CLI memudahkan proses membuka proyek native berikut:
npx cap open ios
npx cap open androidSetelah proyek native Anda terinstal, mengirimkan aplikasi Anda ke perangkat terhubung adalah proses yang sederhana.
Untuk Studio Android, tunggu sampai segalanya dimuat dan kemudian kirimkan aplikasi Anda ke perangkat terhubung.
Untuk Xcode, buatlah akun tanda tangan Anda untuk mengirimkan aplikasi Anda ke perangkat nyata bukan hanya simulator. Setelah itu, cukup tekan play untuk menjalankan aplikasi di perangkat terhubung Anda, yang dapat dipilih di atas.
Jika semuanya berjalan lancar, Anda akan telah mengubah aplikasi web React.js Anda menjadi aplikasi mobile native!
Capacitor Reload Hidup
Framework pengembangan modern biasanya datang dengan reload panas, dan beruntungnya, Anda dapat memiliki hal yang sama dengan Capacitor tetapi di perangkat mobile Anda!
Anda dapat membuat aplikasi yang dihosting secara lokal dapat diakses dengan reload hidup di jaringan Anda dengan memiliki aplikasi Capacitor memuat konten dari URL tertentu.
Pertama, tentukan alamat IP lokal Anda. Di Mac, Anda dapat melakukannya dengan menjalankan ipconfig getifaddr en0 di terminal. Di Windows, jalankan ipconfig dan cari alamat IPv4.
Setelah itu, instruksi Capacitor untuk memuat aplikasi secara langsung dari server dengan menambahkan parameter lain ke file: capacitor.config.ts file:
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;untuk menerapkan perubahan-perubahan ini ke proyek native kita. npx cap copy Aplikasikan perubahan-perubahan ini ke proyek native kami.
Hati-hati bahwa jika plugin baru diinstal, seperti kamera, maka diperlukan pembangunan ulang proyek native Anda. Hal ini karena file native akan berubah dan tidak dapat diperbarui secara real-time.
Do keep in mind that if new plugins are installed, such as the camera, it necessitates a rebuild of your native project. This is because the native files will have changed and cannot be updated on the fly.
Mari kita lihat cara menggunakan plugin Capacitor secara singkat. Mari kita instal plugin sederhana, yaitu
Mari kita lihat cara menggunakan plugin Capacitor secara cepat. Mari kita instal plugin sederhana, yaitu , yang mempromosikan dialog berbagi native:Mengaktifkan dialog berbagi asli:
npm i @capacitor/shareUntuk menggunakan fitur ini, import paket dan panggil fungsi yang terkait share() fungsi dari aplikasi kami. Pertimbangkan 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 untuk menyinkronkan kembali proyek React kita menggunakan. npx cap sync.
Selanjutnya, Anda dapat membuat aplikasi terasa lebih native di iOS dan Android dengan navigasi dan transisi Capgo dan memperbaiki masalah layout iOS yang umum menyebabkan overflow horizontal atau area aman yang dipotong.
Antarmuka Native yang Terasa dengan Capgo Navigasi dan Transisi Native
Saya telah bekerja selama bertahun-tahun dengan Ionic untuk membangun aplikasi cross-platform, tetapi mengintegrasikannya dengan React adalah hacky dan jarang berharga ketika Anda sudah memiliki Tailwind CSS.
Untuk merasakan mobile native di aplikasi React + Capacitor, gunakan plugin Capgo daripada antarmuka UI web seperti Konsta UI:
- @capgo/capacitor-navigasi native — navbar native, Liquid Glass tab bar di iOS, dan gaya tab bar yang berbayang di Android. Router React Anda menjaga keadaan rute; plugin ini menguasai chrome native.
- @capgo/capacitor-transisi — transisi halaman Ionic-style dan gesekan balik iOS di layer WebView, tanpa menerima UI Ionic.
Instal keduanya:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncKonfigurasi navigasi native dengan mode CSS inset agar konten web menghormati bar-bar native:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Tampilkan tab bar Liquid Glass (iOS menggunakan rendering yang dimiliki sistem; Android menggunakan latar belakang WebView yang berbayang):
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 shell aplikasi 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>;
}Wrap halaman yang dilayani oleh cap-router-outlet, cap-pagedan cap-contentdan panggil setDirection('forward') atau setDirection('back') Jangan duplikasi header atau footer web ketika navigasi native menguasai permukaan tersebut.
Lihat panduan lengkap: Menggunakan @capgo/capacitor-navigasi native dan Menggunakan @capgo/capacitor-transisi.
Area yang aman dengan Tailwind
Untuk area yang aman perangkat di Tailwind CSS, gunakan @capgo/tailwind-capacitor (diterbitkan sebagai) tailwind-capacitor di npm). Ini menyediakan safe-areas utilitas dan plugin-plugin lainnya yang bersifat Tailwind yang Capacitor-friendly
bun add -D tailwind-capacitorIn src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Gunakan utilitas seperti pt-safe, pb-safedan px-safe bukan dengan menaburkannya secara manual. env(safe-area-inset-*) oleh tangan. Projek ini aktif dikembangkan — jika ada sesuatu yang hilang untuk pengaturan React Anda, buka PR di GitHub.
Pengaturan Layout iOS (Viewport, Area Aman, dan Horizontal Overflow)
Jika konten terlihat dipotong, bergeser, atau dapat di-scroll secara horizontal di iOS, menambahkan lebih banyak overflow-x: hidden atau mengatur tag viewport saja biasanya tidak dapat memperbaikinya. Lakukan pengecekan-pengecekan ini secara berurutan.
Pastikan tag meta viewport diterapkan dengan benar
Tambahkan tag meta viewport di index.html di dalam <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Pengaturan Area Aman iOS dari satu wrapper root saja
Buatlah shell aplikasi tunggal dan aplikasikan padding area aman di sana — bukan di komponen-komponen yang terikat:
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);
}Seluruh konten halaman harus di dalam .app-shell. Pengulangan padding area aman di header, modal, dan pengemasan layout sering membuat UI terlihat dipotong atau terlalu besar.
Dengan @capgo/tailwind-capacitor, Anda dapat mengungkapkan padding yang sama dengan utilitas seperti pt-safe pb-safe px-safe pada shell tunggal tersebut.
Setel Capacitor iOS contentInset ke never first
pertama capacitor.config.tsgunakan native inset disabled dan biarkan CSS (atau Native Navigation) contentInsetMode: 'css'Mengontrol area aman:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'build',
ios: {
contentInset: 'never',
},
};Menggabungkan Capacitor’s konten otomatis dengan CSS env(safe-area-inset-*) Mengatur padding dengan CSS adalah penyebab umum dari jarak ganda.
Temukan elemen yang mengalir melebihi
Penyebab biasanya adalah elemen yang menggunakan 100vw, Tailwind w-screenlebar piksel tetap, atau besar min-width.
Dalam 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 banyak masalah overflows horizontal berasal dari 100vw / w-screen, padding area aman yang digandakan, atau kontainer dengan lebar tetap — bukan dari tag meta viewport itu sendiri.
Kesimpulan
Capacitor menawarkan cara yang mudah untuk membangun aplikasi native berdasarkan proyek web yang sudah ada, menyediakan cara yang sederhana untuk berbagi code dan memiliki UI yang konsisten.
Terima kasih pada teknologi seperti Capacitor, membangun aplikasi mobile dari aplikasi web React.js telah menjadi lebih mudah. Tingkatkan kemampuan pengembangan web Anda dengan menciptakan aplikasi mobile native yang impresif. Selamat berkode!
Untuk informasi lebih lanjut tentang cara mempercepat proses pengembangan aplikasi Anda. Daftarlah untuk akun gratis sekarang juga.
Teruslah dari Membangun Aplikasi Mobile dengan React.js dan Capacitor
Jika Anda menggunakan Membangun Aplikasi Mobile dengan React.js dan Capacitor untuk merencanakan perilaku media dan antarmuka native, hubungkannya dengan Menggunakan @capgo/capacitor-live-activities untuk kemampuan native di Menggunakan @capgo/capacitor-live-activities, @capgo/capacitor-aktivitas-berlangsung-hidup untuk detail implementasi di @capgo/capacitor-aktifitas-hidup, Menggunakan @capgo/capacitor-player-video untuk kemampuan asli di Menggunakan @capgo/capacitor-player-video, @capgo/capacitor-player-video untuk detail implementasi di @capgo/capacitor-player-video, dan Menggunakan @capgo/capacitor-navigasi-asli untuk kemampuan asli di Menggunakan @capgo/capacitor-navigasi-asli.
