Dalam tutorial ini, kita akan memulai dengan sebuah Reakt Aplikasi dan beralih ke pengembangan mobile native menggunakan Capacitor. Anda juga dapat menambahkan Capgo Navigasi dan Transisi Native untuk merasa seperti pengembangan mobile native, dan menggunakan tailwind-capacitor untuk area yang aman.
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 beberapa langkah sederhana, sebagian besar aplikasi React dapat diubah menjadi aplikasi mobile.
Tutorial ini akan mengajarkan Anda cara membuat aplikasi mobile React dengan menggunakan Capacitor. Kami akan memulai dengan membuat aplikasi React baru dan kemudian mengintegrasikan Capacitor untuk memasuki dunia 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 membungkus aplikasi Anda ke dalam tampilan 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.
With Capacitor, you get a fantastic native mobile app without any complicated setup or steep learning curve. Its slim API and streamlined functionality make it a breeze to integrate into your project. Trust me, you’ll be amazed at how effortless it is to achieve a fully functional native app with Capacitor!
Persiapan 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-appUntuk membuat aplikasi mobile native, kita memerlukan ekspor projek kita. Oleh karena itu, mari kita tambahkan skrip yang sederhana ke dalam package.json yang dapat digunakan untuk membangun dan mengexport projek React:
{
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
}
}Kamu dapat menjalankan npm run build tanpa khawatir, dan kamu harus dapat melihat folder baru di root projek kamu.
Folder ini akan digunakan oleh Capacitor nanti, tapi sekarang kita harus mengaturnya dengan benar.
Menambahkan Capacitor ke Aplikasi React Anda
To package any web app into a native mobile container, we must follow a few initial steps, but afterward it’s as simple as executing a single sync perintah.
Pertama-tama, kita dapat menginstal Capacitor CLI as a development dependency, and then set it up within our project. During the setup, you can press “enter” to accept the default values for name and bundle ID.
Terakhir, kita dapat menambahkan platform, dan akan membuat folder untuk setiap platform di root proyek kita:
Akhirnya, kita bisa 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 androidSekarang Anda seharusnya dapat melihat perubahan dan and Android folder di proyek React Anda.
folder di proyek React kita.
To akses proyek Android nanti, Anda harus menginstal Studio Android. Untuk iOS, Anda memerlukan Mac dan harus menginstal Xcode.
Selain itu, Anda harus menemukan sebuah capacitor.config.ts file di proyek Anda, yang berisi beberapa pengaturan dasar Capacitor yang digunakan selama sinkronisasi. Yang perlu Anda perhatikan adalah webDir, yang harus mengarah ke hasil perintah build Anda. Saat ini, itu tidak akurat.
To memperbaiki hal ini, buka file capacitor.config.json file dan update direktori web:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "out",
"bundledWebRuntime": false
}Anda dapat mencobanya dengan menjalankan perintah-perintah berikut:
npm run build
npx cap sync Perintah 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 yang tepat di platform native sehingga dapat ditampilkan di aplikasi.
Selain itu, perintah sinkronisasi mungkin juga memperbarui platform-platform native dan menginstal plugin-plugin, sehingga ketika Anda menginstal plugin baru Capacitor plugin sudah siap untuk digunakan. npx cap sync again.
Sekarang Anda telah selesai tanpa menyadari, mari kita lihat aplikasi di perangkat!
Membangun dan Mengirimkan Aplikasi Nativ
Untuk mengembangkan aplikasi iOS, Anda membutuhkan Xcode terinstal, dan untuk aplikasi Android, Anda membutuhkan Studio Android terinstal. Selain itu, jika Anda berencana untuk mendistribusikan aplikasi Anda di toko aplikasi, Anda perlu mendaftar ke Apple Developer Program untuk iOS dan Google Play Console untuk Android.
Jika Anda baru dalam pengembangan mobile native, Anda dapat menggunakan Capacitor CLI untuk dengan mudah membuka proyek native berikut:
npx cap open ios
npx cap open androidSekarang Anda telah mengatur proyek native Anda, mengembangkan aplikasi ke perangkat yang terhubung sangat mudah. Di Android Studio, Anda hanya perlu menunggu sampai segalanya siap, dan Anda dapat mengembangkan aplikasi ke perangkat yang terhubung tanpa mengubah pengaturan apa pun. Contoh berikut:
Di Xcode, Anda perlu mengatur akun tanda tangan Anda untuk mengembangkan 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 atas. Contoh berikut:
Selamat! Anda telah berhasil mengembangkan aplikasi web React ke perangkat mobile. Contoh berikut:
Namun, tunggu dulu, ada cara yang lebih cepat untuk melakukannya selama pengembangan…
Capacitor Reload Hidup
Dengan kemajuan ini, Anda mungkin sudah terbiasa dengan reload panas dengan semua kerangka kerja modern, dan kabar baiknya adalah bahwa Anda dapat memiliki fungsi yang sama pada perangkat seluler dengan sedikit usaha!
Aktifkan akses ke aplikasi Anda yang dihosting secara lokal dengan reload hidup 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 dapat menemukan informasi ini dengan menjalankan perintah berikut di terminal:
ipconfig getifaddr en0Di Windows, jalankan :
ipconfigLalu cari alamat IPv4.
Kita dapat menginstruksikan Capacitor untuk memuat aplikasi secara langsung dari server dengan menambahkan entri lain ke konfigurasi kami 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 benar, saya telah menggunakan port React default dalam contoh ini.
Sekarang, kita dapat menerapkan perubahan-perubahan ini dengan menyalinnya ke proyek native kita:
npx cap copyThe copy perintah ini mirip dengan syncAnda dapat menyelesaikan pengembangan aplikasi Anda satu kali lagi melalui Android Studio atau Xcode. Setelah itu, jika Anda mengubah sesuatu di aplikasi React Anda, Salin perubahan yang dibuat ke folder web and configuration, without updating the native project.
Sekarang Anda dapat mengdeploy aplikasi Anda satu kali lagi melalui Android Studio atau Xcode. Setelah itu, jika Anda mengubah sesuatu di aplikasi React Anda, Aplikasi akan secara otomatis di-reload dan menampilkan perubahan!
Perlu diingat bahwa jika Anda menginstal plugin baru seperti kamera, masih memerlukan rebuild proyek native Anda. Ini karena file native telah berubah, dan tidak dapat dilakukan secara langsung.
Perlu diingat bahwa Anda harus menggunakan IP dan port yang benar dalam konfigurasi. Blok code di atas menunjukkan 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 Bagikan plugin, tetapi plugin ini tetap saja menampilkan dialog bagikan native! Untuk itu, kita hanya perlu mengimport paket dan memanggil share() fungsi dari aplikasi kita. Mari kita ubah src/App.js menjadi 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;As 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 syncSaat menekan tombol, Anda dapat menyaksikan dialog berbagi native yang indah dalam aksi!
Selanjutnya, Anda dapat membuat aplikasi merasa lebih native pada iOS dan Android dengan Capgo navigasi dan transisi, dan memperbaiki masalah layout iOS yang umum menyebabkan overflow horizontal atau area aman yang dipotong.
Antarmuka native yang indah dengan Capgo Native Navigation dan Transisi
Saya telah bekerja selama bertahun-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 yang lebih baik daripada 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 tetap memiliki status jalur; plugin memiliki chrome native.
- @capgo/capacitor-transisi — Transisi halaman seperti Ionic dan swipe-back di lapisan WebView tanpa mengadopsi antarmuka 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 kaca cair (iOS menggunakan rendering milik sistem; Android menggunakan latar belakang WebView yang diburamkan):
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>;
}Wrap halaman yang diarahkan dengan cap-router-outlet, cap-pagedan cap-contentdan panggil setDirection('forward') atau setDirection('back') Jangan duplikasi header atau footer web ketika navigasi native mengendalikan permukaan-permukaan tersebut.
Lihat panduan lengkap: Menggunakan @capgo/capacitor-navigasi native dan Menggunakan @capgo/capacitor-transisi.
Wilayah aman dengan Tailwind
Untuk wilayah aman perangkat di Tailwind CSS, gunakan @capgo/tailwind-capacitor (diterbitkan sebagai) tailwind-capacitor Dalam npm). Ini menyediakan safe-areas Menyediakan utilitas dan plugin-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";Menggunakan utilitas seperti pt-safe, pb-safe, dan px-safe alihkan dari menyebarkan env(safe-area-inset-*) secara manual. 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 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
Buatkan shell aplikasi tunggal dan aplikasikan padding area aman di sana — bukan di komponen-komponen nested yang berbeda:
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-shellJangan duplikasi padding area aman di header, modal, dan wrapper tata letak untuk menghindari tampilan UI yang terpotong atau terlalu besar.
Dengan @capgo/tailwind-capacitor, Anda dapat mengekspresikan padding yang sama dengan utilitas seperti pt-safe pb-safe px-safe di shell tunggal tersebut.
Setel Capacitor iOS contentInset ke never first
pertama capacitor.config.tsgunakan native inset disabled dan biarkan CSS (atau Native Navigation's) contentInsetMode: 'css'Mengontrol area aman:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};Menggabungkan Capacitor’s konten otomatis dengan inset CSS env(safe-area-inset-*) Jarak padding adalah penyebab umum dari penambahan spasi ganda.
Cari elemen yang sebenarnya mengalami overflows.
Penyebab biasanya adalah elemen yang menggunakan 100vw, Tailwind w-screen, lebar piksel tetap, atau lebar yang besar min-width.
In 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 bila memungkinkan. Banyak masalah overflows horizontal berasal dari 100vw / w-screen, padding area yang aman duplikat, atau kontainer 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.
And dengan penambahan CapgoDengan demikian, bahkan lebih mudah untuk menambahkan pembaruan live ke aplikasi Anda, sehingga pengguna Anda selalu memiliki akses ke fitur-fitur terbaru dan perbaikan bug.
Jika Anda ingin belajar cara menambahkan Capgo ke aplikasi React Anda, lihatlah artikel berikutnya:
Teruskan 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 Natively untuk alur kerja produk di Capgo Build Natively, Integrasi Capgo untuk alur kerja produk di Capgo Integrasi Integrasi CI/CD untuk detail implementasi di Integrasi CI/CD, dan Integrasi Aksi GitHub untuk detail implementasi di Integrasi Aksi GitHub.
