Dalam tutorial ini, kita akan memulai dengan aplikasi React baru dan kemudian beralih ke pengembangan mobile native menggunakan __CAPGO_KEEP_0__. Anda juga dapat menambahkan __CAPGO_KEEP_1__ Navigasi dan Transisi Native untuk merasakan pengalaman mobile native, serta menggunakan tailwind-__CAPGO_KEEP_2__ untuk area-area yang aman. __CAPGO_KEEP_0__ memungkinkan Anda untuk dengan mudah mengubah aplikasi web React menjadi aplikasi mobile native tanpa perubahan signifikan atau belajar kemampuan baru seperti React Native. app and transition to native mobile development using Capacitor. You can also add Capgo Native Navigation and Transitions for a native mobile feel, and use tailwind-capacitor for safe areas.
Tutorial ini akan mengajarkan Anda prosesnya, mulai dari aplikasi React baru dan kemudian mengintegrasikan Capacitor untuk beralih ke aplikasi mobile native. Anda juga dapat menggunakan __CAPGO_KEEP_1__ Navigasi, Transisi, dan tailwind-__CAPGO_KEEP_2__ untuk area-area yang aman.
Tentang __CAPGO_KEEP_0__
This tutorial will guide you through the process, starting with a new React app and then incorporating Capacitor to move into the realm of native mobile apps. You can also use Capgo Native Navigation, Transitions, and tailwind-capacitor for safe areas.
About Capacitor
Martin Donadieu
With Capacitor, Anda akan mendapatkan aplikasi mobile native yang fantastis tanpa setup yang rumit atau kurva belajar yang curam. Slim dan fungsi yang terstruktur API membuatnya mudah untuk diintegrasikan ke dalam proyek Anda. Percayalah, Anda akan terkejut dengan seberapa mudahnya mencapai aplikasi mobile native yang sepenuhnya berfungsi dengan Capacitor!
Mempersiapkan Aplikasi React
Sementara ada beberapa metode untuk memulai aplikasi React, mari kita pilih yang paling sederhana dalam tutorial ini yang menyediakan aplikasi React kosong:
npx create-react-app my-appDalam membuat aplikasi mobile native, kita membutuhkan export proyek kita. Oleh karena itu, mari kita tambahkan skrip yang sederhana ke dalam package.json yang dapat digunakan untuk membangun dan mengexport proyek React:
{
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
}
}Anda dapat menjalankan npm run build tanpa khawatir, dan Anda seharusnya dapat melihat folder baru di root proyek Anda.
Folder ini akan digunakan oleh Capacitor nanti, tetapi untuk saat ini, kita harus mengaturnya dengan benar.
Mengambahkan Capacitor ke Aplikasi React Anda
To package any web app into a native mobile container, we must follow a few initial steps, tetapi setelah itu sangatlah mudah seperti menjalankan satu perintah saja. sync Pertama-tama, kita dapat menginstal
__CAPGO_KEEP_0__ Capacitor CLI __CAPGO_KEEP_1__
sebagai dependensi pengembangan, dan kemudian mengaturnya dalam proyek kita. Selama pengaturan, Anda dapat menekan “enter” untuk menerima nilai default untuk nama dan ID aplikasi.
Finally, we can add the platforms, and Capacitor will create folders for each platform at the root of our project:
# 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 androidTerakhir, kita dapat menambahkan platform, dan __CAPGO_KEEP_0__ akan membuat folder untuk setiap platform di root proyek kita: Dengan titik ini, Anda seharusnya dapat melihat folder baru ios, dan android, dalam proyek React Anda.
Itu adalah proyek asli native!
Untuk mengakses proyek Android nanti, Anda harus menginstal Android Studio. Untuk iOS, Anda memerlukan Mac dan harus menginstal Xcode.
Selain itu, Anda harus menemukan file capacitor.config.ts di proyek Anda, yang berisi beberapa pengaturan dasar Capacitor yang digunakan selama sinkronisasi. Satu-satunya hal yang perlu Anda perhatikan adalah webDir, yang harus mengarah ke hasil perintah build Anda. Saat ini, itu tidak akurat.
Untuk memperbaiki hal ini, buka file capacitor.config.json file dan update webDir:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "out",
"bundledWebRuntime": false
}Anda dapat mencobanya dengan menjalankan perintah-perintah berikut:
npm run build
npx cap syncPerintah pertama npm run build hanya akan membangun proyek React Anda dan mengexport build statis.
Sementara perintah kedua npx cap sync akan sinkronkan semua web code ke tempat-tempat yang tepat di platform-platform native sehingga dapat ditampilkan dalam aplikasi.
Selain itu, perintah sinkronisasi mungkin juga memperbarui platform-platform native dan menginstal plugin-plugin, sehingga ketika Anda menginstal plugin baru Capacitor plugins waktunya menjalankan npx cap sync lagi.
Tidak menyadari, Anda sekarang sudah selesai, jadi mari kita lihat aplikasi di perangkat!
Buat dan Deploy aplikasi native
Untuk mengembangkan aplikasi iOS, Anda membutuhkan Xcode terinstal, dan untuk aplikasi Android, Anda membutuhkan Android Studio terinstal. Selain itu, jika Anda berencana untuk mendistribusikan aplikasi Anda di toko aplikasi, Anda perlu mendaftar ke Program Pengembang Apple untuk iOS dan Google Play Console untuk Android.
Jika Anda baru-baru ini mengembangkan aplikasi mobile native, Anda dapat menggunakan Capacitor CLI untuk dengan mudah membuka proyek-proyek native:
npx cap open ios
npx cap open androidSetelah Anda telah mengatur proyek-proyek native Anda, mengdeploy aplikasi ke perangkat yang terhubung sangat mudah. Di Android Studio, Anda hanya perlu menunggu sampai segalanya siap, dan Anda dapat mengdeploy aplikasi ke perangkat yang terhubung tanpa mengubah pengaturan apa pun. Contoh berikut ini:
Di Xcode, Anda perlu mengatur akun tanda tangan Anda untuk mengdeploy aplikasi ke perangkat nyata bukan hanya simulator. Jika Anda belum pernah melakukannya sebelumnya, Xcode akan mengarahkan Anda melalui prosesnya (tetapi lagi, Anda perlu terdaftar di Program Pengembang). Setelah itu, Anda hanya perlu menekan tombol play untuk menjalankan aplikasi di perangkat yang terhubung, yang dapat Anda pilih di bagian atas. Contoh berikut ini:
Selamat! Anda telah berhasil mengdeploy aplikasi web React Anda ke perangkat mobile. Contoh berikut ini:
Tapi tunggu dulu, ada cara yang lebih cepat untuk melakukannya selama pengembangan…
Capacitor Live Reload
Sekarang Anda mungkin sudah terbiasa dengan hot reload pada semua framework modern, dan kabar baiknya adalah Anda bisa memiliki fungsi yang sama pada perangkat seluler dengan sedikit usaha!
Aktifkan akses ke aplikasi Anda yang dihosting secara lokal dengan live reload pada jaringan Anda dengan memiliki aplikasi Capacitor memuat konten dari URL tertentu.
Langkah pertama adalah menentukan alamat IP lokal Anda. Jika Anda menggunakan Mac, Anda bisa menemukan informasi ini dengan menjalankan perintah berikut di terminal:
ipconfig getifaddr en0Pada Windows, jalankan :
ipconfigLalu cari alamat IPv4.
Kita dapat menginstruksikan Capacitor untuk memuat aplikasi secara langsung dari server dengan menambahkan entri lain ke dalam file kita. capacitor.config.ts file:
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'my-app',
webDir: 'out',
bundledWebRuntime: false,
server: {
url: 'http://192.168.x.xx:3000',
cleartext: true
}
};
export default config;Pastikan Anda menggunakan alamat IP dan port yang benarSaya telah menggunakan port React default dalam contoh ini.
Sekarang, kita dapat menerapkan perubahan-perubahan ini dengan menyalinnya ke proyek native kita:
npx cap copyPerintah ini mirip dengan copy , tetapi hanya syncmengcopy perubahan yang dibuat ke folder web dan konfigurasi, tanpa mengupdate proyek native. Anda dapat menyebarluaskan aplikasi Anda satu kali lagi melalui Android Studio atau Xcode. Setelah itu, jika Anda mengubah sesuatu di aplikasi React Anda,
file: __CAPGO_KEEP_0__ Aplikasi akan secara otomatis reload dan menampilkan perubahan!
Perlu diingat bahwa jika Anda menginstal plugin baru seperti kamera, masih memerlukan pembangunan ulang proyek native Anda. Ini karena file native telah berubah, dan tidak dapat dilakukan secara langsung.
Penting untuk diingat bahwa Anda harus menggunakan IP dan port yang benar dalam konfigurasi. Blok code di atas menampilkan port React default untuk keperluan demonstrasi.
Menggunakan Plugin Capacitor
Mari kita lihat bagaimana menggunakan plugin Capacitor dalam aksi, yang telah disebutkan beberapa kali sebelumnya. Untuk melakukan ini, kita dapat menginstal plugin yang cukup sederhana dengan menjalankan:
npm i @capacitor/shareTidak ada yang istimewa tentang plugin Share plugin, tetapi plugin ini tetap saja menampilkan dialog berbagi native! Untuk ini, kita hanya perlu mengimport paket dan memanggil share() fungsi dari aplikasi kita. Mari kita ubah src/App.js Untuk hal ini:
import React from 'react';
import { Share } from '@capacitor/share';
function App() {
const share = async () => {
await Share.share({
title: 'Open Youtube',
text: 'Check new video on youtube',
url: 'https://www.youtube.com',
dialogTitle: 'Share with friends'
});
};
return (
<div>
<h1>Welcome to React and Capacitor!</h1>
<p>
<h2>Cool channel</h2>
<button onClick={() => share()}>Share now!</button>
</p>
</div>
);
}
export default App;Seperti yang telah disebutkan sebelumnya, ketika menginstal plugin baru, kita perlu melakukan operasi sinkronisasi dan kemudian redeploy aplikasi ke perangkat kita. Untuk melakukan ini, jalankan perintah berikut:
npx cap syncSetelah menekan tombol, Anda dapat menyaksikan dialog berbagi native yang indah dalam aksi!
Selanjutnya, Anda dapat membuat aplikasi terasa lebih native pada iOS dan Android dengan Capgo navigasi dan transisi, dan memperbaiki masalah layout iOS yang umum yang menyebabkan overflow horizontal atau area aman yang dipotong.
UI native yang indah dengan Capgo Navigasi dan Transisi Native
Saya telah bekerja selama tahun-tahun dengan Ionic untuk membangun aplikasi lintas platform, tetapi mengintegrasikannya dengan React adalah hacky dan jarang berharga ketika Anda sudah memiliki Tailwind CSS.
Untuk merasakan mobile native dalam aplikasi React + Capacitor , gunakan plugin Capgo bukan kit UI web seperti Konsta UI:
- @capgo/capacitor-navigasi-native — navbar native, tab bar Liquid Glass pada iOS, dan gaya tab bar yang diboroskan pada Android. Router React Anda menjaga keadaan jalur; plugin ini menguasai chrome native.
- @capgo/capacitor-transisi — transisi halaman Ionic gaya dan swipe-back iOS di lapisan WebView, tanpa menerima UI Ionic.
Pasang kedua:
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 diboroskan):
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>;
}Bungkus halaman yang dilalui dalam cap-router-outlet, cap-page, dan cap-content, dan panggil setDirection('forward') atau setDirection('back') sebelum berpindah. Jangan duplikat kepala atau footer web ketika navigasi native menguasai permukaan tersebut.
Lihat panduan lengkap: Menggunakan @capgo/capacitor-navigasi-natif dan Menggunakan @capgo/capacitor-transisi.
Daerah aman dengan Tailwind
Untuk daerah aman perangkat di Tailwind CSS, gunakan @capgo/tailwind-capacitor (diterbitkan sebagai tailwind-capacitor pada npm). Ini menyediakan safe-areas fasilitas dan lain-lain Capacitor-ramah Tailwind plugin:
bun add -D tailwind-capacitorDalam src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Gunakan fasilitas seperti pt-safe, pb-safedan px-safe bukan dengan menyebarkan env(safe-area-inset-*) oleh tangan. Projek ini aktif dikembangkan — jika ada yang hilang untuk pengaturan React Anda, buka PR di GitHub.
Pengaturan Layout iOS (Viewport, Area Aman, dan Overflows Horizontal)
Jika konten terlihat dipotong, bergeser, atau dapat di-scroll secara horizontal di 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
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 nested yang berulang:
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);
}Tutup semua konten halaman di dalam .app-shell. Pengulangan padding aman area safe di header, modal, dan wrapper 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 di lapisan shell tersebut.
Atur Capacitor iOS contentInset ke never pertama
Dalam capacitor.config.ts, lebih baik mengaktifkan disabled inset native dan biarkan CSS (atau Native Navigation’s contentInsetMode: 'css') menguasai area aman:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};Menggabungkan konten otomatis Capacitor dengan CSS env(safe-area-inset-*) Penambahan padding CSS sering menyebabkan jarak ganda.
Cari elemen yang sebenarnya mengalami overflow
Penyebab biasanya adalah elemen yang menggunakan 100vw, Tailwind w-screen, lebar piksel tetap, atau lebar yang 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 ketika memungkinkan. Banyak masalah overflow horizontal berasal dari 100vw / w-screen, penambahan padding area aman yang duplikat, atau kontainer dengan lebar tetap — bukan dari tag meta viewport itu sendiri.
Kesimpulan
Capacitor adalah pilihan yang sangat baik untuk membangun aplikasi native berdasarkan proyek web yang sudah ada, menawarkan cara sederhana untuk berbagi code dan menjaga UI yang konsisten.
Dan dengan penambahan dari Capgo, bahkan lebih mudah untuk menambahkan pembaruan langsung ke aplikasi Anda, sehingga pengguna Anda selalu memiliki akses ke fitur dan perbaikan bug terbaru.
Jika Anda ingin belajar cara menambahkan Capgo ke aplikasi React Anda, lihatlah artikel selanjutnya:
Teruslah dari Membangun Aplikasi Mobile dengan React dan Capacitor
Jika Anda menggunakan Membangun Aplikasi Mobile dengan React dan Capacitor untuk merencanakan otomatisasi CI/CD, hubungkanlah dengan Capgo CI/CD untuk alur kerja produk di Capgo CI/CD, Capgo Build Native untuk alur produk dalam Capgo Pembangunan Asli, Capgo Integrasi untuk alur produk dalam Capgo Integrasi, Integrasi CI/CD untuk detail implementasi dalam Integrasi CI/CD, dan GitHub Integrasi Aksi untuk detail implementasi dalam GitHub Integrasi Aksi.
