Building Mobile Apps with React and Capacitor

Kita akan memulai dengan membuat aplikasi 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 mengubah aplikasi web React Anda menjadi aplikasi mobile native tanpa perlu melakukan modifikasi signifikan atau belajar keterampilan baru seperti React Native.

Untuk membuat aplikasi React menjadi aplikasi mobile hanya memerlukan beberapa langkah sederhana.

Dengan tutorial ini, Anda akan dibimbing melalui prosesnya, mulai dari 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 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 diperbarui 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-app

Untuk membuat 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 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, tetapi setelah itu, cukup sederhana seperti menjalankan perintah tunggal. sync Pertama-tama, kita dapat menginstal

Capacitor dan SDK Capacitor CLI Selanjutnya, kita perlu menginstal paket inti dan paket relevan untuk platform iOS dan Android.

Terakhir, kita dapat menambahkan platform, dan Capgo akan membuat folder untuk setiap platform di root proyek kita:

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

__CAPGO_KEEP_0__ iOS dan Anda Folder-Folder di Projek React Anda.

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 yang berisi beberapa pengaturan dasar Capacitor yang digunakan selama sinkronisasi. Yang perlu Anda perhatikan hanyalah webDir, yang harus mengarah ke hasil perintah build Anda. Saat ini, itu tidak akurat.

To memperbaiki hal ini, buka file capacitor.config.json 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 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 dari platform native sehingga dapat ditampilkan dalam aplikasi.

Selain itu, perintah sinkronisasi mungkin memperbarui 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 mendaftar ke Program Pengembang Apple untuk iOS dan Google Play Console untuk Android.

Jika Anda baru mengenal pengembangan aplikasi mobile natif, Anda dapat menggunakan Capacitor CLI untuk dengan mudah membuka proyek-proyek natif:

npx cap open ios
npx cap open android

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

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 mengantarkan Anda melalui proses tersebut (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 contoh:

Selamat! Anda telah berhasil mengirimkan aplikasi web React Anda ke perangkat mobile. Berikut contoh:

Tapi tunggu dulu, ada cara yang lebih cepat untuk melakukannya selama pengembangan…

Capacitor Live Reload

Dengan demikian, Anda sekarang dapat memiliki fungsi hot reload seperti pada 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 Anda 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 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

Langkah ini mirip dengan copy Langkah ini synctetapi hanya menggandakan perubahan yang dibuat ke 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 di aplikasi React Anda, aplikasi akan secara otomatis reload dan menampilkan perubahan!

Pertahankanlah di dalam pikiran Anda 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.

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

Menggunakan Capacitor Plugins

Tinjauan ini akan menunjukkan 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 berbagi, tetapi itu tetap membuka dialog berbagi native! share() Untuk itu, kita hanya perlu mengimport paket dan memanggil fungsi dari aplikasi kita. Mari kita ubah src/App.js

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;

menjadi ini:

npx cap sync

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:

react-Capgo-share

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.

Antarmuka UI yang terasa asli dengan __CAPGO_KEEP_0__ Navigasi dan Transisi Asli 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 sentuhan mobile asli dalam aplikasi React + Capacitor , gunakan plugin Capgo alih-alih kit UI web seperti Konsta UI:

• @capgo/capacitor-native-navigation — navbar native, Liquid Glass tab bar pada iOS, dan gaya tab bar yang diboroskan pada Android. Pengaturan rute React Anda tetap; plugin ini menguasai chrome native.
• @capgo/capacitor-transitions — transisi halaman Ionik dan swipe balik iOS pada 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 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>;
}

Terapkan halaman yang dilutekan dalam cap-router-outlet, cap-pageMenggunakan @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-navigasi native cap-contentMenggunakan @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transisi setDirection('forward') Menggunakan @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transisi yang aman dengan Tailwind setDirection('back') Menggunakan @__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__

Menggunakan @__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ (diterbitkan sebagai Menggunakan @capgo/capacitor-transisi Menggunakan @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transisi Menggunakan @capgo/capacitor-transisi.

Menggunakan @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transisi

Menggunakan @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transisi Menggunakan @capgo/capacitor-transisi Menggunakan @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transisi dan tailwind-capacitor di npm). Ini menyediakan safe-areas fasilitas dan plugin lainnya yang Capacitor-ramah:

bun add -D tailwind-capacitor

Pada 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 cukup untuk memperbaikinya. Lakukan periksaan-periksaan ini secara berurutan. overflow-x: hidden Pastikan tag meta viewport diterapkan dengan benar

pagePath

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

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

Menangani zona aman iOS dari wrapper root saja

Buatlah shell aplikasi tunggal dan aplikasikan padding zona 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);
}

Wrap semua konten halaman di .app-shell. Menggunakan padding zona 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 itu.

Set Capacitor iOS contentInset ke never pertama

Di capacitor.config.ts, lebih baik menggunakan inset native yang dinonaktifkan dan biarkan CSS (atau Navigasi Native) mengatur area yang aman: contentInsetMode: 'css'Menggabungkan __CAPGO_KEEP_0__’s automatic content inset dengan padding CSS adalah penyebab umum dari jarak ganda.

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

Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) Biasanya, penyebabnya adalah elemen yang menggunakan

, Tailwind

, lebar piksel yang tetap, atau besar 100vwDi Safari Web Inspector, jalankan: w-screenDengan Tailwind, gantikan min-width.

create-react-mobile-apps-dengan-capacitor

[...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,
  }));

create-react-mobile-apps-dengan-capacitor w-screen dengan w-full ketika memungkinkan. Banyak masalah keluaran horizontal datang dari 100vw / w-screen, padding area aman yang digandakan, 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.

Dan dengan penambahan Capgocontext

If you would like to learn how to add Capgo to your React app, take a look at the next article:

Jika Anda ingin belajar cara menambahkan Capacitor ke aplikasi React Anda, lihatlah artikel berikutnya:

Teruskan dari Membangun Aplikasi Mobile dengan React dan __CAPGO_KEEP_0__ 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.