Dalam tutorial ini, kita akan memulai dengan aplikasi React baru dan beralih ke pengembangan mobile native menggunakan __CAPGO_KEEP_0__. Anda juga dapat menambahkan __CAPGO_KEEP_1__ navigasi native dan transisi untuk merasa seperti aplikasi mobile asli, serta menggunakan tailwind-__CAPGO_KEEP_2__ untuk area yang aman. __CAPGO_KEEP_0__ memungkinkan Anda untuk dengan mudah mengonversi aplikasi web React Anda menjadi aplikasi mobile native tanpa perubahan signifikan atau belajar keterampilan 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.
Capacitor allows you to easily convert your React web application into a native mobile app without significant modifications or learning a new skill like React Native.
Dengan hanya beberapa langkah sederhana, aplikasi React sebagian besar dapat diubah menjadi aplikasi mobile.
Tutorial ini akan mengantarkan Anda melalui prosesnya, mulai dari aplikasi React baru dan kemudian mengintegrasikan Capacitor untuk memasuki ranah aplikasi mobile native. Anda juga dapat menggunakan Capgo Native Navigation, Transisi, dan tailwind-capacitor untuk area aman.
Tentang Capacitor
CapacitorJS adalah perubahan besar! Anda dapat dengan mudah mengintegrasikannya ke dalam proyek web apa pun, dan itu akan menggabungkan aplikasi Anda ke dalam view web native, menghasilkan proyek Xcode dan Android Studio native untuk Anda. Selain itu, plugin-nya memberikan akses ke fitur perangkat native seperti kamera melalui jembatan JS.
Dengan Capacitor, Anda mendapatkan aplikasi mobile native yang fantastis tanpa setup yang rumit atau kurva belajar yang curam. API dan fungsi yang diintegrasikan secara berkelanjutan membuatnya mudah untuk diintegrasikan ke dalam proyek Anda. Percayalah, Anda akan terkejut dengan seberapa mudahnya mencapai aplikasi native yang sepenuhnya berfungsi dengan Capacitor!
Mengatur Aplikasi React
Sementara ada berbagai metode untuk memulai aplikasi React, mari kita pilih yang paling sederhana dalam tutorial ini yang menyediakan aplikasi React kosong:
npx create-react-app my-appUntuk menciptakan aplikasi mobile native, kita memerlukan 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"
}
}Sekarang 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.
Menambahkan Capacitor ke Aplikasi React Anda
Untuk mengemas aplikasi web menjadi kontainer mobile native, kita harus mengikuti beberapa langkah awal, tetapi setelah itu, hanya perlu menjalankan satu sync perintah.
Pertama-tama, kita dapat menginstal Capacitor CLI sebagai dependensi pengembangan, dan kemudian mengaturnya dalam proyek kita. Selama pengaturan, Anda dapat menekan “enter” untuk menerima nilai default untuk nama dan ID paket.
Kemudian, kita perlu menginstal paket inti dan paket relevan untuk platform iOS dan Android.
Akhirnya, kita dapat 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 androidPada titik ini, Anda seharusnya dapat melihat folder baru iOS dan Android folder-folder di proyek React Anda.
Itu adalah proyek native asli!
Untuk mengakses proyek Android nanti, Anda harus menginstal Android Studio. Untuk iOS, Anda memerlukan Mac dan harus menginstal Xcode.
Selain itu, Anda harus menemukan sebuah capacitor.config.ts berkas di proyek Anda, yang berisi beberapa pengaturan dasar Capacitor yang digunakan selama sinkronisasi. Satu-satunya hal yang perlu Anda perhatikan adalah direktoriWeb, yang harus mengarah ke hasil perintah pembangunan Anda. Saat ini, itu tidak akurat.
Untuk memperbaiki hal ini, buka capacitor.config.json file dan perbarui direktoriWeb:
{
"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 hasil pembangunan statis.
Sementara perintah kedua npx cap sync akan sinkronkan semua web code ke tempat-tempat yang tepat di platform-platform native sehingga dapat ditampilkan di aplikasi.
Selain itu, perintah sinkronisasi mungkin juga memperbarui platform-platform native dan menginstal plugin, sehingga ketika Anda menginstal plugin baru Capacitor plugin-plugin Sekarang saatnya menjalankan npx cap sync lagi.
Tanpa menyadari, Anda sekarang sudah selesai, jadi mari lihat aplikasi di perangkat!
Buat dan Deploy aplikasi native
Untuk mengembangkan aplikasi iOS, Anda memerlukan Xcode terpasang, dan untuk aplikasi Android, Anda memerlukan Android Studio terpasang. 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.
If you’re new to native mobile development, you can use the Capacitor CLI to easily open both native projects:
npx cap open ios
npx cap open android__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ untuk dengan mudah membuka proyek-proyek native:
Untuk menjalankan aplikasi di Xcode, Anda perlu mengatur akun tanda tangan Anda untuk mengirimkan aplikasi ke perangkat nyata bukan hanya simulator. Jika Anda belum pernah melakukannya sebelumnya, Xcode akan memandu Anda melalui proses tersebut (tetapi lagi, Anda perlu terdaftar dalam Program Pengembang). Setelah itu, Anda hanya perlu menekan tombol play untuk menjalankan aplikasi di perangkat yang terhubung, yang dapat Anda pilih di bagian atas. Berikut adalah contoh:
Selamat! Anda telah berhasil mengirimkan aplikasi web React Anda ke perangkat mobile. Berikut adalah contoh:
Tapi tunggu dulu, ada cara yang lebih cepat untuk melakukannya selama pengembangan…
Capacitor Live Reload
Sampai saat ini, Anda mungkin sudah terbiasa dengan memiliki hot reload dengan semua framework modern, dan kabar baiknya adalah bahwa Anda dapat memiliki fungsi yang sama pada perangkat mobile dengan upaya yang minimal!
Aktifkan akses ke aplikasi yang dihosting secara lokal dengan live reload pada jaringan Anda melalui aplikasi Capacitor memuat konten dari URL tertentu.
Langkah pertama adalah menentukan alamat IP lokal Anda. Jika Anda menggunakan Mac, Anda dapat menemukannya 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 file: capacitor.config.ts Pastikan untuk menggunakan
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;alamat IP dan port yang benar Saya telah menggunakan port React default dalam contoh ini.Sekarang, kita dapat menerapkan perubahan ini dengan menyalinnya ke proyek native kita:
Perintah ini mirip dengan
npx cap copyPerintah ini mirip dengan copy __CAPGO_KEEP_0__ synctetapi hanya menggandakan perubahan yang dibuat pada folder web dan konfigurasi, tanpa memperbarui proyek native.
Anda dapat menyebarluaskan aplikasi satu kali lagi melalui Android Studio atau Xcode. Setelah itu, jika Anda mengubah sesuatu pada aplikasi React, aplikasi akan secara otomatis reload dan menampilkan perubahan!
Pertahankanlah bahwa jika Anda menginstal plugin baru seperti kamera, masih memerlukan pembangunan ulang proyek native. Ini karena file native telah berubah, dan tidak dapat dilakukan secara instan.
Pertimbangkanlah bahwa Anda harus menggunakan IP dan port yang benar dalam konfigurasi. Blok code di atas menunjukkan port React default untuk keperluan demonstrasi.
Menggunakan Capacitor Plugin
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 Bagikan pluginTapi itu tetap membuka dialog bagikan asli! Untuk hal ini, kita hanya perlu mengimport paket dan memanggil fungsi dari aplikasi kita. Mari kita ubah share() src/App.js menjadi ini: Seperti yang telah disebutkan sebelumnya, ketika menginstal plugin baru, kita perlu melakukan operasi sinkronisasi dan kemudian meng-redeploy aplikasi ke perangkat kita. Untuk melakukan ini, jalankan perintah berikut:
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;Setelah menekan tombol, Anda dapat menyaksikan dialog bagikan asli yang indah!
npx cap syncreact-__CAPGO_KEEP_0__-bagikan
UI yang terasa asli dengan Capgo Navigasi dan Transisi Asli
Native-feeling UI with Capgo Native Navigation and Transitions
Ionik Bagikan plugin To membuat aplikasi lintas platform, tetapi mengintegrasikannya dengan React adalah sulit dan jarang berharga ketika Anda sudah memiliki Tailwind CSS.
Untuk merasa mobile asli dalam aplikasi React + Capacitor , gunakan Capgo plugin alih-alih UI web seperti Konsta UI:
- @capgo/capacitor-native-navigation — navbar native, Liquid Glass tab bar di iOS, dan gaya tab bar yang diboroskan di Android. Pengaturan rute React Anda tetap; plugin menguasai chrome native.
- @capgo/capacitor-transitions — transisi halaman Ionic dan swipe balik iOS di layer WebView, tanpa menerapkan UI Ionic.
Install kedua:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncKonfigurasi navigasi native dengan mode CSS inset sehingga 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:
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>;
}Terapkan transisi halaman native di halaman yang diatur oleh rute Anda: cap-router-outlet, cap-page, dan cap-content, dan panggil setDirection('forward') atau setDirection('back') sebelum berpindah. Jangan duplikat header atau footer web ketika navigasi asli menguasai permukaan tersebut.
Lihat panduan lengkap: Menggunakan @capgo/capacitor-navigasi-asli dan Menggunakan @capgo/capacitor-transisi.
Wilayah aman dengan Tailwind
Untuk wilayah perangkat aman di Tailwind CSS, gunakan @capgo/tailwind-capacitor (diterbitkan sebagai tailwind-capacitor pada npm). Ini menyediakan safe-areas fasilitas dan plugin lainnya yang Capacitor-ramah Tailwind:
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-safe, dan px-safe sebagai ganti dari menambahkannya env(safe-area-inset-*) langsung dengan tangan. Projek ini aktif dikembangkan — jika ada yang hilang untuk pengaturan React Anda, buka PR di GitHub.
Mengatasi Masalah Layout iOS (Viewport, Area Aman, dan Horizontal Overflow)
Jika konten terlihat dipotong, bergeser, atau dapat di-scroll secara horizontal pada iOS, menambahkan lebih overflow-x: hidden atau menyesuaikan 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" />Menangani zona aman iOS dari satu wrapper root saja
Buatlah sebuah shell aplikasi tunggal dan aplikasikan padding zona aman di sana — bukan di komponen nested yang banyak:
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);
}Selimuti semua konten halaman di .app-shell. Penggunaan padding zona aman yang berulang 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 shell tunggal tersebut.
Atur Capacitor iOS contentInset ke never Pertama
Dalam capacitor.config.tsprefer native inset disabled dan biarkan CSS (atau Native Navigation's) contentInsetMode: 'css'miliki area yang aman:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};Menggabungkan Capacitor’s automatic content inset dengan CSS env(safe-area-inset-*) padding adalah penyebab umum dari jarak ganda.
Temukan elemen yang sebenarnya mengalami overflows
Biasanya, penyebabnya adalah elemen yang menggunakan 100vwTailwind 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, gantilah w-screen dengan w-full ketika memungkinkan. Banyak masalah overflow horizontal berasal dari 100vw / w-screen, padding area yang aman yang diulang, atau kontainer dengan lebar tetap — bukan dari tag meta viewport itu sendiri.
Kesimpulan
Capacitor adalah pilihan yang sangat baik untuk membuat 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 hidup ke aplikasi Anda, sehingga pengguna Anda selalu memiliki akses ke fitur dan perbaikan bug yang terkini.
Jika Anda ingin belajar cara menambahkan Capgo ke aplikasi React Anda, lihatlah artikel berikutnya:
Teruslah dari Membangun Aplikasi Mobile dengan React dan Capacitor
Jika Anda menggunakan Membangun Aplikasi Mobile dengan React dan Capacitor untuk merencanakan otomatisasi CI/CD, hubungkannya dengan Capgo Otomatisasi CI/CD untuk alur kerja produk di Capgo Otomatisasi CI/CD, Capgo Pembangunan Natively untuk alur kerja produk di Capgo Pembangunan Natively, 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.
