리액트와 Capacitor를 사용하여 모바일 앱을 빌드하는 방법

이 튜토리얼에서, 우리는 새로운 리액트 앱을 시작하고 Capacitor를 사용하여 네이티브 모바일 개발로 전환할 것입니다. 또한 Capgo 네이티브 네비게이션 및 전환을 추가하여 네이티브 모바일 느낌을 제공하고 tailwind-capacitor를 사용하여 안전한 영역을 사용할 수 있습니다.

Capacitor는 리액트 웹 애플리케이션을 네이티브 모바일 앱으로 쉽게 변환할 수 있는 기능을 제공합니다. 이는 네이티브 모바일 앱을 개발하는 데 필요한 수정이나 새로운 기술을 배우지 않고도 쉽게 변환할 수 있습니다.

이러한 프로세스를 따라가면, 대부분의 리액트 애플리케이션은 몇 가지 단순한 단계만으로 모바일 앱으로 변환할 수 있습니다.

이 튜토리얼에서는 새로운 리액트 앱을 시작하고 Capacitor를 사용하여 네이티브 모바일 앱으로 전환하는 과정을 안내합니다. 또한 Capgo 네이티브 네비게이션, 전환 및 tailwind-capacitor를 사용하여 안전한 영역을 사용할 수 있습니다.

Capacitor에 대해 알아보세요

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

Capacitor를 사용하면 복잡한 설정이나陡峭한 학습 곡선 없이도 훌륭한 네이티브 모바일 앱을 얻을 수 있습니다. API의 가벼운 크기와 streamlined 기능은 프로젝트에 쉽게 통합할 수 있습니다. 믿을 수 없을 정도로 쉽게 네이티브 앱을 만들 수 있습니다. Capacitor!

React 앱을 준비하세요.

이 튜토리얼에서 가장 단순한 방법으로 React 애플리케이션을 시작하는 방법에 대해 설명합니다.

npx create-react-app my-app

native 모바일 앱을 만들기 위해서는 프로젝트의 export package.json에 단순한 스크립트를 포함하여 프로젝트를 빌드하고 export할 수 있도록 해야합니다. 이제는 걱정없이 을 실행할 수 있습니다. 프로젝트의 루트 폴더에 새로운 폴더가 생성되어야 합니다.

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

이 폴더는 나중에 __CAPGO_KEEP_0__에 의해 사용될 것입니다. 하지만 지금은 올바르게 설정해야 합니다. npm run build __CAPGO_KEEP_0__를 React 앱에 추가하세요.

이 폴더는 나중에 Capacitor에 의해 사용될 것입니다. 그러나 현재는 올바르게 설정해야 합니다.

Adding Capacitor to Your React App

__CAPGO_KEEP_0__를 설정하세요. sync 명령어.

첫째로, 우리는 Capacitor CLI 를 개발 의존성으로 설치하고 프로젝트 내에서 설정할 수 있습니다. 설정 중에 이름과 번들 ID의 기본값을 수락하려면

다음으로, 우리는 iOS 및 Android 플랫폼에 관련된 패키지를 설치해야 합니다.

마지막으로 플랫폼을 추가할 수 있습니다. 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 and ios 와

android

안드로이드 프로젝트에 나중에 접근하기 위해서는 안드로이드 스튜디오를 설치해야 합니다. Xcode.

Xcode capacitor.config.ts Capacitor.config.ts webDir__CAPGO_KEEP_0__

설정이 포함되어 있습니다. capacitor.config.json 를 주의하십시오. 이는 빌드 명령어의 결과를 가리켜야 합니다. 현재는 정확하지 않습니다. 웹 디렉토리:

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

다음 명령어를 실행하여 시도해 보세요:

npm run build
npx cap sync

첫 번째 명령어 npm run build 만들어진 리액트 프로젝트를 단순히 빌드하고 정적 빌드를 내보냅니다.

두 번째 명령어 npx cap sync 웹 code을 원하는 위치에同步시켜 앱에서 표시할 수 있도록 합니다.

또한 Sync 명령어는 네이티브 플랫폼을 업데이트하고 플러그인을 설치할 수 있으므로 새로운 __CAPGO_KEEP_0__ 플러그인을 설치하면 Capacitor plugins 다시 실행하세요. npx cap sync again.

Build and Deploy 네이티브 앱

웹 디렉토리

iOS 앱을 개발하려면 Xcode Android 앱을 개발하려면 안드로이드 스튜디오 앱을 스토어에 배포하려면 iOS는 Apple Developer Program, Android는 Google Play Console에 가입해야 합니다.

native 모바일 개발에 새로운 사람이라면 Capacitor CLI을 사용하여 쉽게 iOS와 Android의 native 프로젝트를 열 수 있습니다.

npx cap open ios
npx cap open android

native 프로젝트를 설정한 후 앱을 연결된 기기에서 배포하는 것은 쉽습니다. Android Studio에서는 설정을 변경하지 않고도 기기를 연결한 후 앱을 배포할 수 있습니다. 예를 들어:

Xcode에서는 실제 기기에서 앱을 배포하려면 서명 계정을 설정해야 합니다. 이 과정을 처음하는 경우 Xcode는 개발자 프로그램에 가입한 경우에만 안내해줍니다. 그 후에 단지 플레이 버튼을 클릭하여 연결된 기기에서 앱을 실행할 수 있습니다. 예를 들어:

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

하지만 개발 중에 이 작업을 더 빠르게 하려면...

Capacitor 리로드

이제 대부분의 프레임워크에서 핫 리로드를 사용해 보셨을 것입니다. 좋은 소식은 이 기능을 모바일 기기에서도 사용할 수 있다는 것입니다. 모바일 기기에 최소한의 노력으로!

로컬로 호스팅된 애플리케이션에 대한 접근을 활성화하고 네트워크 내에서 Capacitor 앱이 특정 URL에서 콘텐츠를 로드하도록 하세요.

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

ipconfig getifaddr en0

윈도우즈에서 :

ipconfig

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

Capacitor가 서버에서 앱을 직접 로드하도록 지시하려면, 우리의 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 포트를 사용했습니다.이제 이러한 변경 사항을 우리의 네이티브 프로젝트로 복사하여 적용할 수 있습니다:

명령어는

npx cap copy

The copy Android Studio 또는 Xcode를 통해 앱을 다시 배포할 수 있습니다. 그 후에, React 앱에서 변경 사항이 생기면 앱은 자동으로 다시 로드됩니다. sync명령어는 와 유사하지만, 웹 폴더와 설정에만 변경 사항을 복사하고 네이티브 프로젝트를 업데이트하지 않습니다. 앱을 다시 배포하고, React 앱에서 변경 사항이 생기면 앱은 자동으로 다시 로드됩니다.

명령어는 앱은 자동으로 다시 로드됩니다. 그리고 변경 사항을 보여줍니다!

주의해야 할 점이 있습니다. 새로운 플러그인인 카메라를 설치한다면, 여전히 네이티브 프로젝트를 다시 빌드해야 합니다. 이는 네이티브 파일이 변경되었기 때문입니다. 즉, 이 작업은 실시간으로 수행할 수 없습니다.

주의해야 할 점은, 올바른 IP와 포트를 구성 파일에 사용해야 한다는 것입니다. 위의 code 블록은 데모를 위해 기본 React 포트를 보여주고 있습니다.

Capacitor 플러그인 사용

이번에는 Capacitor 플러그인을 실제로 사용하는 방법에 대해 살펴보겠습니다. 이에 대해 몇 번 언급했지만, 간단한 플러그인을 설치하여 실행할 수 있습니다.

npm i @capacitor/share

이 플러그인은 특별한 기능이 없지만, 네이티브 공유 대화 상자를 열어줍니다. 이에 대해 더 자세히 살펴보겠습니다. 공유 플러그인이 플러그인은 간단하지만, 네이티브 공유 대화 상자를 열어줍니다. share() function 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;

이전 항목에서 언급한 바와 같이, 새로운 플러그인을 설치할 때는 sync 작업을 수행하고 앱을 다시 장치에 배포해야 합니다. 이 작업을 수행하려면 다음 명령어를 실행하세요.

npx cap sync

버튼을 클릭한 후, 아름다운 네이티브 공유 대화창을 사용할 수 있습니다!

다음으로, iOS 및 Android에서 앱이 더 네이티브하게 느껴지도록 Capgo 네비게이션 및 전환을 사용하고, 수평 스크롤이나 안전 영역이 잘려나가는 문제를 해결할 수 있습니다.

네이티브 느낌의 UI를 위해 Capgo 네이티브 네비게이션 및 전환을 사용하세요.

저는 여러 해 동안 Ionic을 사용하여 크로스 플랫폼 애플리케이션을 개발했지만, React와 통합하는 것은 복잡하고 거의 가치가 없으며 이미 Tailwind CSS를 사용하고 있다면 React + __CAPGO_KEEP_0__ 앱에서 네이티브 모바일 느낌을 얻으려면 __CAPGO_KEEP_1__ 플러그인을 사용하세요. Ionic — 네이티브 네비게이션 바, iOS에서 Liquid Glass 탭 바 스타일, Android에서 흐린 탭 바 스타일. React 라우터는 라우트 상태를 유지하고 플러그인은 네이티브 창을 관리합니다. I’ve worked for years with.

For a native mobile feel in a React + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:

• @capgo/capacitor-native-네비게이션 Tailwind CSS
• @capgo/capacitor-transition — iOS와 Android에서 WebView layer에서 Ionic-style 페이지 전환 및 iOS edge swipe-back을 사용할 수 있습니다. Ionic UI를 채택하지 않습니다.

설치 BOTH:

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

리퀴드 글라스 탭 바를 렌더링합니다 (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페이지를 wrap하는 cap-content또는 setDirection('forward') 또는 setDirection('back') 또는

또는 Capacitor를 사용하여 @capgo/capacitor-네이티브 네비게이션 사용 and Capacitor를 사용하여 @capgo/capacitor-전환.

Tailwind에서 안전한 영역

Tailwind CSS에서 장치 안전 영역을 사용하려면 @capgo/tailwind-capacitor (__CAPGO_KEEP_0__에서 발행) tailwind-capacitor npm가 제공하는 기능과 다른 npm-친화적인 Tailwind 플러그인 safe-areas utility 및 다른 Capacitor-친화 Tailwind 플러그인

bun add -D tailwind-capacitor

In src/index.css:

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

, pt-safe, pb-safe그리고 px-safe 대신 뿌리치지 env(safe-area-inset-*) 수동으로. 이 프로젝트는 활발하게 개발 중 — React 설정에 필요한 것이 빠져 있는 경우, GitHub에 PR을 열어.

iOS 레이아웃 문제 해결 (뷰포트, 안전 영역, 가로 스크롤)

iOS에서 콘텐츠가 잘려나거나-shifted 또는 가로 스크롤 가능한 경우, 뷰포트 태그만 추가하거나 조정하는 것만으로 해결되지 않습니다. 이러한 체크를 순서대로 진행하세요. overflow-x: hidden 뷰포트 메타 태그가 올바르게 적용되었는지 확인하세요

뷰포트 메타 태그를 추가하세요

내부 index.html inside <head>:

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

싱글 앱 셸을 생성하고 안전 영역 패딩을 적용하세요 — 여러 개의 중첩된 컴포넌트에서만 적용하지 마세요:

모든 페이지 콘텐츠를 내부에 wrap하세요

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

iOS 레이아웃 문제 해결 (뷰포트, 안전 영역, 가로 스크롤) .app-shell. 중복된 안전 영역 패딩이 헤더, 모달, 레이아웃 wrapper에 적용되어 UI가 잘린 것처럼 보이거나 너무 크게 보일 수 있습니다.

With @capgo/tailwind-capacitor, pt-safe pb-safe px-safe 이러한 패딩을 단일 셸에 적용하여 동일한 패딩 효과를 얻을 수 있습니다.

Set Capacitor iOS contentInset 을 never 첫

In capacitor.config.ts, contentInsetMode: 'css'native inset을 비활성화하고 CSS (또는 Native Navigation의

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-*) padding은 일반적인 두 줄 간격의 원인입니다.

padding은 더블 스페이싱의 일반적인 원인입니다.

실제로 부여되는 요소를 찾으세요. 100vw일반적으로 원인은 요소가 사용하는 w-screenTailwind min-width.

, 고정 픽셀 너비, 또는 큰

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

사파리 웹 인스펙터에서 실행하세요: w-screen Tailwind의 경우 w-full 대신 100vw / w-screen가능한 경우. 많은 수평 방출 문제는

Conclusion

Capacitor is an excellent option for building native applications based on an existing web project, offering a simple way to share code and maintain a consistent UI.

And __CAPGO_KEEP_0__ Capgo__CAPGO_KEEP_0__

Capgo

Capacitor

__CAPGO_KEEP_0__ Capacitor __CAPGO_KEEP_0__ Capgo Capgo Capgo Capgo Capgo 통합 Capgo 제품 워크플로우를 위한 통합 CI/CD 통합 CI/CD 통합 구현 세부 사항 GitHub 액션 통합 GitHub 액션 통합 구현 세부 사항