Membangun Aplikasi Mobile dengan React dan Capacitor

Mengapa ini tutorial, kita akan memulai dengan 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 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.

Capacitor memungkinkan Anda untuk dengan mudah mengubah aplikasi web React menjadi aplikasi mobile native tanpa perubahan signifikan atau belajar kemampuan baru seperti React Native.

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

Mengenai Capacitor

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!

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

Selama 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-app

Mengingat untuk membuat aplikasi mobile native, kita memerlukan eksport projek kita. Oleh karena itu, mari kita tambahkan skrip yang sederhana dalam file package.json yang dapat digunakan untuk membangun dan mengexport aplikasi 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 projek Anda.

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

Adding Capacitor to Your React App

Mengambahkan sync ke Aplikasi React Anda

Terlebih dahulu, 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.

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

Terakhir, 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 android

Pada titik ini, Anda seharusnya dapat melihat folder baru ios dan context Page/area: Situs web pemasaran Capgo. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman trust.astro. Kunci pesan `dan` (And).

android

folder di proyek React Anda. Studio Android. 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 webDircontext: direktori web

, yang harus mengarah ke hasil perintah build Anda. Saat ini, itu tidak akurat. capacitor.config.json __CAPGO_KEEP_0__.config.json dan update pengaturan untuk:

{
  "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 sinkronisasi semua web code ke tempat-tempat yang tepat dari platform native sehingga dapat ditampilkan dalam aplikasi.

Selain itu, perintah sinkronisasi mungkin juga memperbarui platform native dan menginstal plugin, sehingga ketika Anda menginstal plugin baru Capacitor plugins waktunya untuk menjalankan npx cap sync lagi.

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

Membangun dan Mengirimkan Aplikasi Native

Untuk mengembangkan aplikasi iOS, Anda membutuhkan Xcode terpasang, dan untuk aplikasi Android, Anda membutuhkan untuk memiliki Android Studio terpasang. Selain itu, jika Anda berencana untuk mendistribusikan aplikasi Anda di toko aplikasi, Anda membutuhkan untuk bergabung dalam Program Pengembang Apple untuk iOS dan Console Google Play 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 android

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

android-studio-run

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

xcode-run

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

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

Capacitor Reload Hidup

Dengan demikian, Anda mungkin sudah terbiasa dengan memiliki reload panas dengan semua kerangka kerja modern, dan kabar baiknya adalah bahwa Anda dapat memiliki fungsi yang sama Pada perangkat mobile dengan sedikit usaha!

Nonaktifkan 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 hal ini dengan menjalankan perintah berikut di terminal:

ipconfig getifaddr en0

Pada Windows, jalankan :

ipconfig

Lalu cari alamat IPv4.

Kita dapat menginstruksikan Capacitor untuk memuat aplikasi secara langsung dari server dengan menambahkan entri lain ke file kami: capacitor.config.ts __CAPGO_KEEP_0__ Reload Hidup

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 copy

Perintah ini mirip dengan copy , tetapi hanya akan syncmenyalin perubahan yang dibuat ke folder web dan konfigurasi, tanpa mengupdate proyek native. Anda dapat menyelesaikan pengembangan aplikasi Anda 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! Perintah ini mirip dengan , tetapi hanya akan menyalin perubahan yang dibuat ke folder web dan konfigurasi, tanpa mengupdate proyek native.

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 instan.

Penting untuk diingat bahwa Anda harus menggunakan IP dan port yang benar dalam konfigurasi Anda. 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/share

Tidak ada yang istimewa tentang plugin Share, tetapi plugin ini tetap saja membawa dialog berbagi native! Untuk ini, kita hanya perlu mengimport paket dan memanggil share() fungsi dari aplikasi kita. Mari kita ubah src/App.js ke 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;

Asasnya, 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

After menekan tombol, Anda dapat menyaksikan dialog berbagi asli yang indah dalam aksi!

Selanjutnya, Anda dapat membuat aplikasi terasa lebih asli di iOS dan Android dengan Capgo navigasi dan transisi, dan memperbaiki masalah tata letak iOS yang umum menyebabkan overflow horizontal atau area aman yang dipotong.

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 yang asli di aplikasi React + Capacitor, gunakan plugin Capgo bukan kit UI web saja seperti Konsta UI:

@capgo/capacitor-native-navigation — navbar asli, Liquid Glass tab bar di iOS, dan gaya tab bar yang diblur di Android. Router React Anda tetap menjaga status jalur; plugin ini menguasai chrome asli.
@capgo/capacitor-transitions — Transisi halaman Ionic-style dan swipe-back iOS di layer WebView, tanpa menerapkan UI Ionic.

Install kedua:

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 kaca Liquid (iOS menggunakan rendering milik 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>;
}

Wrap halaman yang diarahkan dengan cap-router-outlet, cap-pagedan cap-contentdan panggil setDirection('forward') atau setDirection('back') Sebelum menavigasi. Jangan duplikasi header atau footer web ketika navigasi native menguasai permukaan tersebut.

Lihat panduan lengkap: Menggunakan @capgo/capacitor-native-navigation And Gunakan @capgo/capacitor-transisi.

Area yang aman dengan Tailwind

Untuk area yang aman pada perangkat dengan Tailwind CSS, gunakan @capgo/tailwind-capacitor Publikasi sebagai tailwind-capacitor pada npm. safe-areas Menawarkan utilitas dan plugin-plugin Tailwind yang Capacitor-ramah:

bun add -D tailwind-capacitor

Dalam src/index.css:

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

Gunakan utilitas seperti pt-safe, pb-safe, dan px-safe sebaliknya dari menyebarkan env(safe-area-inset-*) oleh tangan. 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 pada iOS, menambahkan lebih banyak 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 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 dalam .app-shellPengaturan padding area aman yang berulang di header, modal, dan wrapper layout sering membuat UI terlihat dipotong 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 itu.

Set Capacitor iOS `contentInset` ke `never` pertama

Dalam capacitor.config.ts, lebih baik menggunakan inset asli dan biarkan CSS (atau Native Navigation’s) contentInsetMode: 'css') mengelola area 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 overflow

Penyebab biasanya adalah elemen yang menggunakan 100vw, Tailwind w-screen, lebar piksel tetap, atau lebar yang sangat 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 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 CapgoMengapa lebih mudah lagi untuk menambahkan pembaruan hidup ke aplikasi Anda, sehingga pengguna Anda selalu memiliki akses ke fitur dan perbaikan bug terbaru.

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

Keep going from Building Mobile Apps with React and Capacitor

Jika Anda menggunakan Building Mobile Apps with React and Capacitor untuk merencanakan otomatisasi CI/CD, hubungkannya dengan Capgo CI/CD for the product workflow in Capgo CI/CD, Capgo Native Builds for the product workflow in Capgo Native Builds, Capgo Integrations untuk alur kerja produk di Integrasi Capgo Integrasi CI/CD untuk detail implementasi di Integrasi CI/CD, dan Aksi Integrasi GitHub untuk detail implementasi di Aksi Integrasi GitHub

Building Mobile Apps with React and Capacitor