React와 Capacitor을 사용하여 모바일 앱을 빌드하는 방법

이 강의에서, 우리는 새로운 React 앱을 시작하고 __CAPGO_KEEP_0__을 사용하여 네이티브 모바일 개발로 전환할 것입니다. 또한 __CAPGO_KEEP_1__ Native Navigation 및 Transitions를 추가하여 네이티브 모바일 느낌을 제공하고 tailwind-__CAPGO_KEEP_2__를 사용하여 안전한 영역을 사용할 수 있습니다. __CAPGO_KEEP_0__은 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

React 애플리케이션을 몇 가지 단순한 단계만으로 모바일 앱으로 변환할 수 있습니다.

This tutorial은 React 앱을 새로 만들고 Capacitor를 사용하여 네이티브 모바일 앱으로 이동하는 과정을 안내합니다. 또한 Capgo Native Navigation, Transitions, 및 tailwind-capacitor를 사용하여 안전한 영역을 사용할 수 있습니다.

Capacitor에 대해

CapacitorJS는 게임 체이너입니다! 웹 프로젝트에 쉽게 통합할 수 있으며, 네이티브 웹뷰로 애플리케이션을 wrapping하고, 네이티브 Xcode 및 Android Studio 프로젝트를 생성합니다. 또한 플러그인은 JS 브리지를 통해 카메라와 같은 네이티브 장치 기능에 접근할 수 있습니다.

Capacitor를 사용하면 복잡한 설정이나 기울임꼴의 학습 곡선이 없이도 훌륭한 네이티브 모바일 앱을 얻을 수 있습니다. API와 streamlined 기능이 얇고, 프로젝트에 통합하는 것이 쉬워서, Capacitor를 사용하여 완전히 기능하는 네이티브 앱을 달성하는 것이 놀랍게 쉬워집니다.

React 앱을 준비합니다.

React 애플리케이션을 시작하는 다양한 방법이 있지만, 이 튜토리얼에서는 가장 단순한 방법을 사용하여 빈 React 애플리케이션을 제공합니다.

npx create-react-app my-app

네이티브 모바일 앱을 만들기 위해 프로젝트를 export해야 합니다. 따라서 package.json에 단순한 스크립트를 포함하여 React 프로젝트를 빌드하고 export할 수 있도록 하겠습니다. export package.json 프로젝트를 export하기 위해 export

{
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  }
}

이제 걱정 없이 실행할 수 있습니다. 프로젝트의 루트 폴더에서 새로운 폴더를 찾을 수 있습니다. npm run build 이 폴더는 나중에 __CAPGO_KEEP_0__에 의해 사용될 것입니다. 그러나 현재는 올바르게 설정해야 합니다.

Capacitor를 React 앱에 추가하는 방법

Adding Capacitor to Your React App

첫째로, __CAPGO_KEEP_0__ __CAPGO_KEEP_1__을 개발 의존성으로 설치하고 프로젝트 내에서 설정할 수 있습니다. 설정 중에는 이름과 번들 ID에 대한 기본값을 수락하려면 '엔터'를 누를 수 있습니다. sync 다음으로, iOS 및 Android 플랫폼에 대한 관련 패키지를 설치해야 합니다.

마지막으로, 플랫폼을 추가하고 __CAPGO_KEEP_0__는 프로젝트의 루트 폴더에 각 플랫폼에 대한 폴더를 생성합니다: Capacitor CLI __CAPGO_KEEP_0__는 __CAPGO_KEEP_1__를 사용하여

__CAPGO_KEEP_0__를

Capacitor를

# 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 및 Android 프로젝트 폴더

실제 네이티브 프로젝트!

Android 프로젝트에 접근하기 위해서는 Android Studio를 설치해야 합니다. iOS는 Mac에서 사용할 수 있으며 Xcode를 설치해야 합니다.프로젝트에서 __CAPGO_KEEP_0__.config.ts 파일을 찾으세요. 이 파일에는 프로젝트 동기화 시 사용되는 기본 __CAPGO_KEEP_0__ 설정이 포함되어 있습니다..

__CAPGO_KEEP_0__ capacitor Capacitor 웹 디렉토리, 현재 명령어 결과가 정확하지 않습니다.

이 문제를 해결하려면 다음을 열어보세요. capacitor.config.json 파일을 열어보세요. 웹 디렉토리:

{
  "appId": "com.example.app",
  "appName": "my-app",
  "webDir": "out",
  "bundledWebRuntime": false
}

You can try it out by executing the following commands:

npm run build
npx cap sync

첫 번째 명령어는 npm run build React 프로젝트를 빌드하고 정적 빌드를 내보냅니다.

두 번째 명령어는 npx cap sync 웹 code을 모든 네이티브 플랫폼의 올바른 위치에同步합니다.

그리고 앱에서 표시되도록합니다. Capacitor 플러그인 실행할 시간입니다. npx cap sync 다시.

실제로 이제 완료되었습니다. 이제 기기에서 앱을 확인해 보세요!

자연스럽게 네이티브 앱을 빌드하고 배포하세요.

iOS 앱을 개발하려면 Xcode가 설치되어야 하며, Android 앱을 개발하려면 Android Studio가 설치되어야 합니다. 또한 앱 스토어에서 앱을 배포하려면 iOS에서는 Apple Developer Program에, Android에서는 Google Play Console에 가입해야 합니다. 네이티브 모바일 개발에 새로운 사람이라면 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__을 사용하여 쉽게 두 개의 네이티브 프로젝트를 열 수 있습니다: 네이티브 프로젝트를 설정한 후 기기에서 앱을 배포하는 것은 쉽습니다. Android Studio에서 모든 것이 준비될 때까지 기다리면 기기에서 앱을 배포할 수 있습니다. 설정을 변경하지 않고도. 예를 들어:

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__

Xcode에서 앱을 실제 기기 대신 시뮬레이터에 배포하려면 서명 계정을 설정해야 합니다. 이 과정을 처음으로 수행한 적이 없다면 Xcode는 프로세스를 안내해 줄 것입니다 (하지만 다시 한 번, 개발자 프로그램에 등록되어 있어야 합니다). 그 후에, 연결된 기기를 선택할 수 있는 상단에서 단순히 플레이 버튼을 클릭하여 앱을 실행할 수 있습니다. 예를 들어:

축하합니다! React 웹 앱을 성공적으로 모바일 기기에서 배포했습니다. 예를 들어:

하지만, 개발 중에 이 과정을 더 빠르게 수행할 수 있는 방법도 있습니다.

Capacitor Live Reload

이제 대부분의 프레임워크에서 사용할 수 있는热 재로드에 익숙해졌을 것입니다. 좋은 소식은, 이 기능을 모바일 기기에서도 사용할 수 있다는 것입니다. 모바일 기기에서 최소한의 노력으로도 동일한 기능을 사용할 수 있습니다!

로컬 호스트 애플리케이션에 대한 접근 권한을 활성화하여 네트워크에서 Live Reload를 사용할 수 있습니다. __CAPGO_KEEP_0__ Capacitor 앱이 특정 URL에서 콘텐츠를 로드하는 것을 허용합니다.

첫 번째 단계는 로컬 IP 주소를 찾는 것입니다. 맥을 사용하는 경우 터미널에서 다음 명령어를 실행하여 이를 찾을 수 있습니다.

ipconfig getifaddr en0

윈도우즈에서 실행하세요:

ipconfig

그런 다음 IPv4 주소를 찾으세요.

Capacitor을 사용하여 앱을 서버에서 직접 로드하도록 지시하려면, native 프로젝트의 파일에 추가 항목을 추가해야 합니다. capacitor.config.ts 파일을 사용하십시오.

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;

정확한 IP 주소와 포트를 사용하십시오. 이 예에서는 기본 React 포트를 사용했습니다. 이 변경 사항을 적용하려면 native 프로젝트에 복사하여 적용하십시오.명령어는

명령어는

npx cap copy

명령어는 copy 명령어는 sync하지만 웹 폴더의 변경 사항만 웹 폴더의 변경 사항과 설정을 복사합니다. 자연 프로젝트를 업데이트하지 않고.

Android Studio 또는 Xcode를 통해 앱을 한 번 더 배포할 수 있습니다. 그 후에, React 앱에 변경 사항이 생기면 자동으로 앱이 다시 로드되고 변경 사항이 표시됩니다. 주의하십시오.

새로운 플러그인인 카메라를 설치하면 여전히 자연 프로젝트를 다시 빌드해야 합니다. 이는 네이티브 파일이 변경되었기 때문입니다. 이 작업은 즉시 수행할 수 없습니다. 정확한 IP와 포트를 사용하여 설정해야 합니다. 위의 __CAPGO_KEEP_0__ 블록은 데모를 위해 기본 React 포트를 보여줍니다.

code 플러그인 사용

이전에도 몇 번 언급한 Capacitor 플러그인을 사용하는 방법에 대해 살펴보겠습니다. 이를 수행하려면 다음과 같은 간단한 플러그인을 설치할 수 있습니다.

Let’s take a look at how to use a Capacitor plugin in action, which we’ve mentioned a few times before. To do this, we can install a fairly simple plugin by running:

npm i @capacitor/share

__CAPGO_KEEP_0__ 공유 플러그인하지만, 그래도 native share dialog를 열어준다! 이 경우, 우리는 package를 import하고 app에서 function을 호출하기만 하면 된다. Let’s src/App.js를 이렇듯 바꿔보자: share() 앞서 언급했듯이 새로운 플러그인을 설치할 때, sync operation을 수행하고 앱을 다시 장치에 배포해야 한다. 이를 위해 다음 명령어를 실행하라: 버튼을 클릭한 후, 아름다운 native share dialog를 경험할 수 있을 것이다! react-__CAPGO_KEEP_0__-share

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;

다음으로, iOS와 Android에서 앱이 더 자연스럽게 느껴지도록 __CAPGO_KEEP_0__ 네비게이션과 전환을 사용하고, iOS에서 발생하는 수평 스크롤이나 안전 영역이 잘려나가는 문제를 해결할 수 있다.

npx cap sync

native-feeling UI with __CAPGO_KEEP_0__ Native Navigation and Transitions

Next, you can make the app feel more native on iOS and Android with Capgo navigation and transitions, and fix common iOS layout issues that cause horizontal overflow or cropped safe areas.

Native-feeling UI with Capgo Native Navigation and Transitions

I’ve worked for years with Ionic 다양한 플랫폼 앱을 만들기 위해 React와 통합하는 것은 불편하고 이미 가지고 있는 경우에 자주 사용되지 않습니다. Tailwind CSS.

React + Capacitor 앱에서 원시 모바일 경험을 얻으려면 Capgo 플러그인 대신 웹 전용 UI 키트인 Konsta UI를 사용하는 것이 좋습니다.

• @capgo/capacitor-native-navigation — 원시 네비게이션 바, iOS에서 Liquid Glass 탭 바, Android에서 흐린 탭 바 스타일을 사용합니다. React 라우터는 경로 상태를 유지하고 플러그인은 원시 창을 관리합니다.
• @capgo/capacitor-transitions — Ionic-style 페이지 전환과 iOS의 WebView layer에서 Edge swipe-back를 사용합니다. Ionic UI를 채택하지 않습니다.

두 가지 모두 설치하세요.

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

원시 네비게이션을 CSS inset 모드와 함께 구성하여 웹 콘텐츠가 원시 바를 존중하세요.

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

Liquid Glass 탭 바를 렌더링하세요 (iOS는 시스템 소유 렌더링을 사용하고 Android는 흐린 WebView 배경을 사용합니다).

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

원시 페이지 전환을 앱 셸에 추가하세요.

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하세요. cap-router-outlet, cap-page그리고 cap-content그리고 호출 setDirection('forward') 또는 setDirection('back') Capacitor live-update 대안 비교 페이지에서 HTML 텍스트 조각입니다. 역할: 장기 마케팅 또는 법률 문단. 본문 키 `alternatives_cta_questions` (대안 CTA 질문). | Appflow 비교 / 이주 마케팅 복사본. 역할: 장기 마케팅 또는 법률 문단. 본문 키 `appflow_cta_questions` (Appflow CTA 질문). | Capawesome 비교 페이지에서 HTML 텍스트 조각입니다. 역할: 장기 마케팅 또는 법률 문단. 본문 키 `capwesome_cta_questions` (Capwesome CTA 질문). | 컨설팅 서비스 페이지에서 HTML 텍스트 조각입니다. 역할: 섹션 서브 타이틀 또는 태그 라인. 본문 키 `consulting_faq_subtitle` (컨설팅 FAQ 서브 타이틀). | Appflow 비교 / 이주 마케팅 복사본. 역할: 짧은 UI 레이블 또는 네비게이션 아이템. 본문 키 `appflow_plugins_or` (Appflow 플러그인 또는).

이전으로 이동하기 전에. Using @capgo/capacitor-native-navigation Using @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation Using @capgo/capacitor-transitions.

Using @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions

안전 영역에 Tailwind @capgo/tailwind-capacitor @__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ (publiched as tailwind-capacitor on npm). It provides safe-areas utilities and other Capacitor-friendly Tailwind plugins:

bun add -D tailwind-capacitor

In src/index.css:

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

viewport, safe area, horizontal overflow과 같은 iOS 레이아웃 문제를 해결하는 데 도움이 되는 유용한 도구를 사용하세요. pt-safe, pb-safe, px-safe 대신에 __CAPGO_KEEP_0__에서 제공하는 도구를 사용하세요. env(safe-area-inset-*) iOS에서 콘텐츠가 잘려나거나-shifted되거나 가로 스크롤이 가능하다면, viewport 태그를 수정하거나 추가하는 것만으로는 문제를 해결할 수 없습니다. 이러한 체크를 순서대로 진행하세요. open a PR on GitHub.

__CAPGO_KEEP_0__에서 PR을 열어보세요.

viewport meta 태그가 올바르게 적용되어 있는지 확인하세요. overflow-x: hidden viewport meta 태그가 올바르게 적용되어 있는지 확인하세요.

viewport meta 태그가 올바르게 적용되어 있는지 확인하세요.

뷰포트 메타 태그를 추가하세요. index.html 내부 <head>:

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

iOS 안전 영역을 한 번에 루트 wrapper에서 처리하세요.

단일 앱 셸을 생성하고 안전 영역 패딩을 거기에 적용하세요 — 여러 중첩된 컴포넌트에 적용하지 마세요:

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

모든 페이지 콘텐츠를 내부에 감싸세요. .app-shell헤더, 모달, 레이아웃 wrapper에 중복된 안전 영역 패딩이 있으면 UI가 잘려나거나 너무 크게 보입니다.

그리고 @capgo/tailwind-capacitor와 함께, 같은 패딩을 표현할 수 있는 유틸리티를 사용할 수 있습니다. pt-safe pb-safe px-safe 단일 셸에

Set Capacitor iOS contentInset 를 설정하세요. never 첫 번째

In capacitor.config.ts, native inset을 사용하고 CSS (또는 Native Navigation의) contentInsetMode: 'css')가 safe area를 관리하도록 해주세요.

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

Capacitor의 자동 콘텐츠 inset과 CSS padding을 혼합하는 것은 일반적인 double spacing의 원인입니다. env(safe-area-inset-*) 실제로 오버플로우하는 요소를 찾으세요.

일반적으로 원인은 요소가

, Tailwind 100vw, 고정 픽셀 너비를 사용하거나 w-screen, 큰 min-width.

Safari Web Inspector에서 실행하세요:

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

Tailwind를 사용하여 w-screen Capacitor를 사용하여 React 모바일 앱을 만들기 w-full 가능한 경우에만 사용합니다. 많은 수평 방향으로의 오버플로우 문제는 100vw / w-screenviewport meta 태그 자체에서 오는 것이 아니라, 중복된 safe-area 패딩 또는 고정 너비 컨테이너에서 오는 것입니다.

결론

Capgo는 기존 웹 프로젝트에 기반한 네이티브 앱을 빌드하는 데 Capacitor가 훌륭한 옵션입니다. code를 공유하고 일관된 UI를 유지하는 간단한 방법을 제공합니다.

Capgo의 추가로, Capgo앱에 최신 기능과 버그 수정을 제공하기 위해 실시간 업데이트를 추가하는 것이 thậm chí 더 쉬워졌습니다.

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

Capacitor를 사용하여 React 모바일 앱을 만들기 Building Mobile Apps with React and Capacitor CI/CD를 자동화하기 위해 연결하세요. Capgo CI/CD 제품 워크플로우에서 Capgo CI/CD를 사용하세요. Capgo 네이티브 빌드 제품 워크플로우에서 Capgo 네이티브 빌드를 사용하세요. Capgo 통합 제품 워크플로우에서 Capgo 통합을 사용하세요. CI/CD 통합 제품 워크플로우에서 CI/CD 통합을 사용하세요. CI/CD 통합 구현 세부 사항에서 GitHub 액션 통합을 사용하세요. GitHub 액션 통합