Building Mobile Apps with React and Capacitor

Mari kita mulai dengan proyek baru React 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 memungkinkan Anda untuk dengan mudah mengonversi aplikasi web React Anda menjadi aplikasi mobile native tanpa perubahan signifikan atau belajar keterampilan baru seperti React Native.

Melalui beberapa langkah sederhana, sebagian besar aplikasi React 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 proyek web apa pun, dan itu akan menggabungkan 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.

Dengan Capacitor, Anda mendapatkan aplikasi mobile native yang fantastis tanpa setup yang rumit atau kurva belajar yang curam. API dan fungsi yang diperbarui membuatnya mudah untuk diintegrasikan ke proyek Anda. Percayalah, Anda akan terkejut dengan seberapa mudahnya mencapai aplikasi native yang sepenuhnya berfungsi dengan Capacitor!

Mengatur Aplikasi React Anda

Sementara ada beberapa metode untuk memulai aplikasi React, mari kita pilih metode yang paling sederhana dalam tutorial ini yang menyediakan aplikasi React kosong:

npx create-react-app my-app

Untuk menciptakan aplikasi mobile native, kita membutuhkan ekspor 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"
  }
}

Kamu sekarang dapat menjalankan npm run build tanpa harus khawatir, dan kamu seharusnya dapat melihat folder baru di root proyek kamu.

This folder will be used by Capacitor later on, but for now, we must set it up correctly.

Adding Capacitor to Your React App

Untuk mengemas aplikasi web menjadi kontainer mobile native, kita harus mengikuti beberapa langkah awal, tapi setelah itu, itu seolah-olah hanya perlu menjalankan satu sync perintah.

Pertama-tama, kita dapat menginstal Capacitor CLI sebagai dependensi pengembangan, dan kemudian mengaturnya dalam proyek kita. Selama pengaturan, kamu dapat menekan “enter” untuk menerima nilai default untuk nama dan ID bundle.

Kemudian, kita perlu menginstal paket inti dan paket relevan untuk platform iOS dan Android.

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 android

Pada titik ini, kamu seharusnya dapat melihat folder baru iOS dan Anda Folder di proyek React Anda.

Proyek asli native!

Untuk mengakses proyek Android nanti, Anda harus menginstal Android Studio. Untuk iOS, Anda membutuhkan Mac dan harus menginstal Xcode.

Selain itu, Anda harus menemukan file capacitor.config.ts 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 dan perbarui 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 sync

Perintah pertama npm run build akan hanya membangun proyek React Anda dan mengexport build statis.

Sementara perintah kedua npx cap sync akan sinkronisasi semua web code ke tempat-tempat yang tepat di platform-platform native sehingga dapat ditampilkan di aplikasi.

Selain itu, perintah sinkronisasi mungkin memperbarui platform-platform native dan menginstal plugin, sehingga ketika Anda menginstal plugin baru Capacitor plugin-plugin sekarang saatnya menjalankan npx cap sync lagi.

Tidak menyadari, Anda sekarang sudah selesai, jadi mari kita lihat aplikasi di perangkat!

Bangun dan Rilis Aplikasi Nativ

Untuk mengembangkan aplikasi iOS, Anda memerlukan Xcode terinstal, dan untuk aplikasi Android, Anda memerlukan Android Studio terinstal. Selain itu, jika Anda berencana untuk mendistribusikan aplikasi Anda di toko aplikasi, Anda perlu bergabung dalam Program Pengembang Apple 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-proyek native berikut:

npx cap open ios
npx cap open android

Saat Anda telah mengatur proyek-proyek native Anda, mengirimkan aplikasi Anda ke perangkat terhubung sangat mudah. Di Android Studio, Anda hanya perlu menunggu sampai segalanya siap, dan Anda dapat mengirimkan aplikasi Anda ke perangkat terhubung tanpa perlu mengubah pengaturan apa pun. Berikut adalah contoh:

Pada Xcode, Anda perlu mengatur akun tanda tangan Anda untuk mengunduh aplikasi ke perangkat nyata bukan hanya simulator. Jika Anda belum pernah melakukannya sebelumnya, Xcode akan membantu Anda melalui prosesnya (tetapi lagi, Anda perlu terdaftar dalam Program Pengembang). Setelah itu, Anda hanya perlu menekan tombol play untuk menjalankan aplikasi pada perangkat yang terhubung, yang dapat Anda pilih di bagian atas. Berikut adalah contoh:

Selamat! Anda telah berhasil mengunduh 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

Dengan kemampuan live reload yang sudah biasa Anda gunakan dengan semua framework modern, kabar baiknya adalah Anda dapat memiliki kemampuan yang sama pada perangkat mobile dengan usaha yang minimal!

Aktifkan akses ke aplikasi Anda yang dihosting secara lokal dengan live reload pada jaringan Anda oleh memiliki 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 en0

On Windows, jalankan :

ipconfig

Lalu cari alamat IPv4.

Kita dapat menginstruksikan Capacitor untuk memuat aplikasi secara langsung dari server dengan menambahkan entri lain ke dalam 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 copy

__CAPGO_KEEP_0__ adalah singkatan dari Capacitor, jadi saya tidak akan menggantinya dengan nama lain. copy Dengan cara ini, kita dapat mengakses aplikasi di perangkat mobile tanpa perlu mengunduhnya dari toko aplikasi. synctetapi hanya menggandakan perubahan yang dibuat ke folder web dan pengaturan, tanpa memperbarui proyek native.

Sekarang Anda dapat mengunggah aplikasi satu kali lagi melalui Android Studio atau Xcode. Setelah itu, jika Anda mengubah sesuatu di aplikasi React Anda, aplikasi akan secara otomatis reload dan menampilkan perubahan!

Pertimbangkan 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 langsung.

Pertimbangkan bahwa Anda harus menggunakan IP dan port yang benar dalam pengaturan. Blok code di atas menampilkan port React default untuk keperluan demonstrasi.

Menggunakan Capacitor Plugins

Tinjau 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/share

Tidak ada yang istimewa tentang Plugin berbagiTapi itu tetap membuka dialog berbagi native! share() Kita hanya perlu mengimport paket dan memanggil 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;

Seperti yang 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:

npx cap sync

Setelah 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 menyebabkan overflow horizontal atau area aman yang dipotong.

UI yang terasa native dengan Capgo Native Navigation dan Transisi

Saya telah bekerja selama bertahun-tahun dengan Ionic untuk membangun aplikasi lintas platform, tetapi mengintegrasikannya dengan React adalah sulit dan jarang berharga ketika Anda sudah memiliki Tailwind CSS.

Untuk merasakan sentuhan mobile asli dalam aplikasi React + Capacitor, gunakan plugin Capgo daripada kit 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 jalur React Anda tetap menjaga keadaan jalur; plugin ini menguasai chrome native.
• @capgo/capacitor-transitions — transisi halaman Ionik dan gesekan balik iOS di layer WebView, tanpa menerima UI Ionik.

Install kedua-duanya:

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

Konfigurasi 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 dalam 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 dilalui dengan cap-router-outlet, cap-pagedan, dan cap-contentdan panggil setDirection('forward') atau setDirection('back') Sebelum Anda melanjutkan. Jangan duplikat header atau footer web ketika navigasi native menguasai permukaan-permukaan tersebut.

Lihat panduan lengkap: Menggunakan @capgo/capacitor-navigasi-native dan Menggunakan @capgo/capacitor-transisi.

Area-aman dengan Tailwind

Untuk area-aman perangkat di Tailwind CSS, gunakan @capgo/tailwind-capacitor (diterbitkan sebagai tailwind-capacitor di npm). Ini menyediakan safe-areas fasilitas dan plugin lainnya yang Capacitor-friendly Tailwind:

bun add -D tailwind-capacitor

In src/index.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

Pakai fasilitas seperti pt-safe, pb-safe, dan px-safe daripada menambahkannya secara manual. Projek ini aktif dikembangkan — jika ada yang hilang untuk pengaturan React Anda, env(safe-area-inset-*) buka PR di __CAPGO_KEEP_0__ open a PR on GitHub.

Jika konten terlihat dipotong, bergeser, atau dapat di-scroll secara horizontal di iOS, menambahkan lebih banyak

atau mengatur tag viewport saja biasanya tidak dapat memperbaikinya. Lakukan periksaan-periksaan ini secara berurutan. overflow-x: hidden Pastikan tag meta viewport telah diterapkan dengan benar

protectedTokens

Tambahkan tag meta viewport di index.html di dalam <head>:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

Menangani area aman iOS dari wrapper root saja

Buatlah shell aplikasi tunggal dan aplikasikan padding area aman di sana — bukan di komponen nested beberapa kali:

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);
}

Terapkan padding area aman di .app-shell. Menggunakan padding area aman yang sama di beberapa header, modal, dan wrapper layout sering membuat UI terlihat dipotong atau terlalu besar.

Dengan @capgo/tailwind-capacitorkamu bisa mengekspresikan padding yang sama dengan utilitas seperti pt-safe pb-safe px-safe di shell tunggal tersebut.

Set Capacitor iOS contentInset ke never pertama

In capacitor.config.ts, lebih baik menggunakan inset native yang dinonaktifkan dan biarkan CSS (atau Native Navigation’s) contentInsetMode: 'css') mengontrol area yang aman:

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'dist',
  ios: {
    contentInset: 'never',
  },
};

Menggabungkan Capacitor’s konten otomatis inset dengan CSS env(safe-area-inset-*) padding adalah penyebab umum dari jarak ganda.

Temukan elemen yang benar-benar mengalir ke luar

Penyebab biasanya adalah elemen yang menggunakan 100vw, Tailwind w-screen, lebar piksel yang tetap, atau 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, gantikan w-screen bersama w-full ketika memungkinkan. Banyak masalah overflow 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 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 Capgocontext

Jika Anda ingin mengetahui 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, hubungkannya dengan Capgo Otomatisasi CI/CD untuk alur kerja produk di Capgo Otomatisasi CI/CD, Capgo Pembangunan Nativ untuk alur kerja produk di Capgo Pembangunan Nativ, Capgo Integrasi for the product workflow in Capgo Integrations, untuk alur kerja produk di __CAPGO_KEEP_0__ Integrasi, Integrasi CI/CD GitHub Actions Integration for the implementation detail in GitHub Actions Integration.