Skip to main content
Capgo 로고
강의

Building Mobile Apps with Pure React.js and Capacitor

React.js 웹 애플리케이션을 Capacitor를 사용하여 모바일 앱으로 변환하고 Capgo Native Navigation, Transitions, iOS 레이아웃 최적화 방법을 추가하는 방법에 대한 안내서입니다.

마틴 도나디우

마틴 도나디우

콘텐츠 마케터
Building Mobile Apps with Pure React.js and Capacitor

이 튜토리얼에서는 React와 Capacitor를 사용하여 모바일 애플리케이션을 만드는 방법을 안내합니다. 튜토리얼을 마치면 React.js 웹 앱을 Capacitor와 함께 모바일 애플리케이션으로 변환하고 Capgo Native Navigation and Transitions를 추가할 수 있습니다.

Capacitor는 React.js 웹 앱을 모바일 애플리케이션으로 변환하는 것을 쉽게 만듭니다. React Native와 같은 새로운 전략을 배울 필요 없이, 기존의 React.js 앱을 모바일 앱으로 변환할 수 있습니다.

변환 프로세스는 단순한 몇 가지 단계로 구성되어 있습니다. 따라서, 이 과정에 함께 하시기 바랍니다.

Capacitor 개요

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

Capacitor은 네이티브 모바일 애플리케이션을 만들기 위한 단순한 방법을 제공합니다. API과 streamlined 기능으로 프로젝트에 쉽게 통합할 수 있습니다.

React.js 앱 설정

React 애플리케이션을 시작하는 가장 단순한 방법을 사용해 보겠습니다. npm 패키지 관리자를 사용하여 새로운 React 앱을 생성하겠습니다.

npx create-react-app my-app

프로젝트를 네이티브 모바일 앱으로 변환하려면 앱의 export 이것에 대해 나중에 다시 돌아가겠습니다. 먼저 __CAPGO_KEEP_0__을 React 앱에 통합하는 방법을 이해해 보겠습니다.

Capacitor을 React.js 앱에 통합하는 방법

Integrating Capacitor into Your React.js App

먼저 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__을 개발 의존성으로 설치하고 프로젝트 내에서 설정합니다. 설정 중 이름과 번들 ID에 대한 기본값을 수락하기 위해 “enter”를 누릅니다. sync __CAPGO_KEEP_0__은 __CAPGO_KEEP_1__을 개발 의존성으로 설치하고 프로젝트 내에서 설정합니다. 설정 중 이름과 번들 ID에 대한 기본값을 수락하기 위해 “enter”를 누릅니다.

First, we’ll install the Capacitor CLI as a development dependency and set it up within our project. During the setup, accept the default values for name and bundle ID by pressing “enter.”

다음으로, 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

The iOS 및 Android 디렉토리는 이제 React.js 프로젝트에 있습니다.

애플리케이션을 나중에 Android 프로젝트에 접근하기 위해 Android Studio를 설치하세요. iOS는 Mac에서 설치해야 하며 Xcode.

를 설치하세요. 다음으로, 웹 디렉토리 당신의 capacitor.config.json 파일에 아래와 같이 표시됩니다.

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

Run the build command and sync your project with Capacitor:

npm run build
npx cap sync

명령어를 실행하면 React.js 프로젝트를 빌드하고 __CAPGO_KEEP_0__을 네이티브 플랫폼의 정확한 위치에 동기화시킵니다. npm run build 이제, 조금의 운과 오류가 없다면, 당신의 React.js 앱은 기기에서 실행할 수 있는 앱으로 준비되어야 합니다! npx cap sync will align the web code in the accurate places of the native platforms so they can be executed in an app.

iOS 앱 개발을 위해서는

Xcode

Xcode Xcode그리고 안드로이드 앱이 필요합니다. 안드로이드 스튜디오앱을 스토어에 배포하려면 iOS는 Apple Developer Program에, 안드로이드는 Google Play Console에 등록해야 합니다.

Capacitor는 native 프로젝트를 열기 위한 Capacitor CLI를 제공합니다.

npx cap open ios
npx cap open android

native 프로젝트를 설정한 후 앱을 연결된 장치에 배포하는 것은 단순한 과정입니다.

안드로이드 스튜디오의 경우, 모든 것을 로드하고 나면 앱을 연결된 장치에 배포할 수 있습니다.

Xcode의 경우, 앱을 실제 장치에 배포하기 위해 서명 계정을 설정한 후, 단순히 플레이 버튼을 클릭하여 앱을 연결된 장치에서 실행할 수 있습니다.

모든 것이 잘 진행되면, React.js 웹 앱을 native 모바일 애플리케이션으로 변환할 수 있습니다!

Capacitor Live Reload

모던 개발 프레임워크는 일반적으로 핫 리로드를 제공하지만, Capacitor는 핫 리로드를 제공하는 Capacitor와 유사하게 모바일 장치에서!

로컬 호스트 애플리케이션을 네트워크에서 접근할 수 있도록 live reload를 사용하여 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: 'build',
  bundledWebRuntime: false,
  server: {
    url: 'http://192.168.x.xx:3000',
    cleartext: true
  }
};

export default config;

정확한 IP 주소와 포트를 사용하세요. 다음 명령어를 실행하여 변경 사항을 native 프로젝트에 적용하세요. npx cap copy 앱을 다시 한 번 Android Studio 또는 Xcode를 통해 배포하면 React 앱의 변경 사항이 자동으로 로드되고 앱에 표시됩니다!

새로운 플러그인을 설치한 경우, 카메라와 같은 경우 native 프로젝트를 다시 빌드해야 합니다. 이는 native 파일이 변경되었기 때문입니다. 변경 사항을 실시간으로 업데이트할 수 없습니다.

__CAPGO_KEEP_0__ 플러그인 사용

Capacitor 플러그인을 사용하는 방법에 대해 간단히 살펴보겠습니다. 간단한

Let’s take a quick look at how to use a Capacitor plugin. Let’s install a simple one, the __CAPGO_KEEP_0__native share dialog을 호출합니다:

npm i @capacitor/share

Capacitor 패키지를 import하고, 해당 함수를 앱에서 호출하세요. 앱의 __CAPGO_KEEP_0__을 고려하세요. share() App.js 새로운 플러그인을 설치한 후, React 프로젝트를 다시 sync하세요.:

import { Share } from '@capacitor/share';

function ShareButton() {
  const share = async () => {
    await Share.share({
      title: 'React App',
      text: 'Visit this React App',
      url: 'http://localhost:3000',
      dialogTitle: 'Share with...'
    });
  };

  return (
    <button onClick={share}>
      Share
    </button>
  );
}

export default ShareButton;

iOS와 Android에서 __CAPGO_KEEP_0__ 네비게이션과 전환을 사용하여 앱을 더 원시적으로 만들 수 있습니다. 또한, __CAPGO_KEEP_0__을 사용하여 iOS에서 발생하는 수평 스크롤이나 안전 영역이 잘려 나가는 문제를 해결할 수 있습니다. npx cap sync.

Capgo 네이티브 네비게이션과 전환을 사용하여 원시적인 UI를 만듭니다.

여러 해 동안 Ionic을 사용하여 크로스 플랫폼 앱을 개발해 왔습니다. 하지만, React와 통합하는 것은 번거롭고, 이미 Tailwind CSS를 사용하고 있다면 Capgo과 통합하는 것은 거의 의미가 없습니다.

React + __CAPGO_KEEP_0__ 앱에서 원시적인 모바일 경험을 원한다면, __CAPGO_KEEP_1__ 플러그인을 사용하세요. 웹 전용 UI 키트인 Konsta UI와 같은 것들을 사용하지 마세요. __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ __CAPGO_KEEP_0__.

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-navigation — 네이티브 네비게이션 바, iOS에서 Liquid Glass 탭 바, Android에서 흐린 탭 바 스타일. React 라우터는 경로 상태를 유지하고 플러그인은 네이티브 창을 소유합니다.
  • @capgo/capacitor-transitions — Ionic-style 페이지 전환 및 iOS 에지 스와이프-백(WebView layer)으로, 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>;
}

페이지를 wrapping하세요: cap-router-outlet, cap-page페이지를 wrapping하세요: cap-contentor setDirection('forward') 또는 setDirection('back') 이전으로 이동하기 전에. 웹 헤더나 푸터를 중복해서 사용하지 마세요. 네이티브 네비게이션에서 해당 영역을 소유하고 있기 때문입니다.

자세한 가이드를 참조하세요: Using @capgo/capacitor-native-navigation 그리고 Using @capgo/capacitor-transitions.

안전 영역에 Tailwind 사용하기

Tailwind CSS에서 디바이스 안전 영역을 사용하려면 Capacitor-capgo-tailwind-capacitor Tailwind CSS로 (Capacitor-__CAPGO_KEEP_0__) tailwind-capacitor Tailwind CSS로 (Capacitor-npm)가 제공합니다. safe-areas Capacitor-Capacitor-친화적인 Tailwind 플러그인:

bun add -D tailwind-capacitor

In src/index.css:

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

Use utilities such as pt-safe, pb-safe, and px-safe instead of sprinkling env(safe-area-inset-*) by hand. The project is actively developed — if something is missing for your React setup, open a PR on GitHub.

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

iOS에서 콘텐츠가 잘려나가거나-shifted되거나 가로 스크롤이 가능하다면, overflow-x: hidden 또는 뷰포트 태그를 조정하는 것만으로는 해결되지 않는다.

이러한 체크를 순서대로 진행하십시오.

뷰포트 메타 태그가 올바르게 적용되어 있는지 확인하십시오. index.html 뷰포트 메타 태그를 <head>:

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

내부에 추가하십시오.

React와 Capacitor를 사용하여 단일 앱 셸을 만들고 안전 영역 패딩을 거기에 적용하십시오 — 여러 중첩된 컴포넌트에서 아닙니다:

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가 잘려나거나 너무 크게 보입니다.

Capacitor의 @capgo/tailwind-capacitor를 사용하여, 단일 셸에서 동일한 패딩을 표현할 수 있습니다. pt-safe pb-safe px-safe CSS (또는 Native Navigation의)

Capacitor iOS contentInset 를 never 첫 번째로

In capacitor.config.ts에서, 원생된 내부 영역을 비활성화하고 Native Navigation의 contentInsetMode: 'css'사용자 안전 영역을 소유합니다:

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

Capacitor의 자동 콘텐츠 인셋과 CSS를 혼합하는 것은 일반적인 두 줄 간격의 원인입니다. env(safe-area-inset-*) 실제로 넘치는 요소를 찾으세요.

일반적으로 원인은 요소가 사용하는

Tailwind 100vw, 고정 픽셀 너비, 또는 큰 w-screen사파리 웹 인스펙터에서 실행하세요: min-width.

Tailwind의 경우

[...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 가능한 경우 w-full 를 사용하세요. 100vw / w-screen많은 수평적 오버플로 문제는 사용자 안전 영역의 중복된 패딩 또는 고정 너비 컨테이너에서 오는 것이 아니라 viewport meta 태그 자체에서 오는 것입니다.

결론

Capacitor은 기존 웹 프로젝트를 기반으로 하는 네이티브 앱을 빌드하는 데 있어 매끄러운 수단을 제공하며, code을 공유하고 일관된 UI를 제공하는 간단한 방법을 제공합니다.

React.js 웹 앱으로부터 모바일 애플리케이션을 빌드하는 데 필요한 기술로 인해, Capacitor을 사용하여 모바일 애플리케이션을 빌드하는 것이 절대적으로 쉬워졌습니다. 웹 개발 기술을 다음 단계로 끌어올리십시오. 훌륭한 네이티브 모바일 앱을 제작하십시오. Happy coding!

더 많은 정보를 얻으려면, __CAPGO_KEEP_0__에 무료 계정으로 가입하십시오. 오늘.

Building Mobile Apps with Pure React.js and Capacitor에서 계속 진행하십시오.

Building Mobile Apps with Pure React.js and __CAPGO_KEEP_0__을 사용하여 네이티브 미디어 및 인터페이스 동작을 계획하고 있습니다. Building Mobile Apps with Pure React.js and Capacitor을 Capacitor/__CAPGO_KEEP_1__-live-activities와 연결하십시오. Building Mobile Apps with Pure React.js and __CAPGO_KEEP_0__을 사용하여 네이티브 __CAPGO_KEEP_0__/__CAPGO_KEEP_1__-live-activities를 사용하십시오. capgo는 capacitor-live-activities를 사용하여 네이티브 capgo/capacitor-live-activities를 사용하십시오. capgo는 capacitor-live-activities를 사용하여 네이티브 capgo/capacitor-live-activities를 사용하십시오. @capgo/capacitor-live-activities Capgo @capgo/capacitor-live-activities 구현 세부 사항 Capgo @capgo/capacitor-video-player 사용 Capgo @capgo/capacitor-video-player의 원시 기능 Capgo @capgo/capacitor-video-player Capgo @capgo/capacitor-video-player 구현 세부 사항 및 Capgo @capgo/capacitor-native-navigation 사용 Capgo @capgo/capacitor-native-navigation의 원시 기능

Capacitor 앱에 대한 실시간 업데이트

When a web-layer bug is live, ship the fix through Capgo instead of waiting days for app store approval. Users get the update in the background while native changes stay in the normal review path.

웹层 버그가 활성화된 경우, 앱 스토어 승인 대기 없이 __CAPGO_KEEP_0__를 통해 수정을 배포하세요. 사용자는 배경에서 업데이트를 받으며 네이티브 변경 사항은 일반적인 검토 경로에 남아 있습니다.

역할: Capgo 마케팅 웹사이트. 역할: 지원 설명 문장 또는 메타 설명 문장. 본문에서: component GetStarted.astro. Capgo 제품/브랜드 및 개발자 용어를 정확하게 유지하세요. 메시지 키 `instant_updates_for_capacitor_apps_description` (Capacitor 앱에 대한 실시간 업데이트 설명).

마틴의 인간 지원

Capgo gives you the best insights you need to create a truly professional mobile app.

2-Way Communication in Capacitor Apps
개발 모바일 +1
2025년 4월 26일

Capacitor 앱에서 2-way 통신

OTA 업데이트 실수를 피하는 5가지 일반적인 방법
개발 보안 +1
2025년 4월 13일

OTA 업데이트 실수를 피하는 5가지 일반적인 방법

모바일 앱 라이브 업데이트에 대한 5가지 보안 권장 사항
개발 모바일 +1
2025년 1월 14일

모바일 앱 라이브 업데이트를 위한 5가지 보안最佳 관행

Capgo 블로그에서 모두 보기