[capacitor] 앱 패키징 시작하기

지난 글에서는 앱을 만드는 방법들을 살펴보고, 그 중에서 Capacitor을 통한 웹 패키징과 firebase를 사용한 FCM으로 웹 푸쉬 알림을 소개해드렸습니다. 이번 글에서는 React 기반 프로젝트를 실제 모바일 앱으로 패키징하는 방법에 대해 알아보려고 합니다. 웹 기술로 개발한 React 애플리케이션을 어떻게 iOS와 Android 앱으로 변환할 수 있는지, 그리고 Capacitor가 어떤 역할을 하는지 알아봅시다. 

 

Capacitor란?

Capacitor는 웹 기술로 만든 애플리케이션을 iOS와 Android 앱으로 패키징 할 수 있도록 도와주는 하이브리드 앱 런타임입니다. React, Vue, Angular와 같은 프론트엔드 프레임워크로 개발한 웹 애플리케이션을 기반으로, 별도의 대규모 수정 없이 모바일 앱으로 확장할 수 있도록 도와줍니다.

Capacitor by Ionic - Cross-platform apps with web technology

 

Capacitor는 내부적으로 WebView를 사용해 웹 애플리케이션을 실행하며, JS 코드에서 카메라, 파일 시스템, 푸시 알림과 같은 네이티브 기능에 접근할 수 있도록 브릿지를 제공합니다. 또한 iOS(Xcode)와 Android(Android Studio) 프로젝트가 그대로 노출되는 구조를 가지고 있어 필요한 경우 네이티브 코드를 직접 수정하거나 확장에도 용이합니다. 

 

패키지 설치 및 초기화

Capacitor를 사용하기 위해서 기존에 React 애플리케이션에 Capacitor 관련 패키지를 설치하고 초기화 과정을 거쳐야 합니다. 먼저 React 프로젝트 루트 디렉토리에서 Capacitor 핵심 패키지와 CLI를 설치해줍시다.

npm install @capacitor/core @capacitor/cli

기존 React 프로젝트에 Android와 iOS 초기화를 진행해도 되지만, 웹과 Android, iOS를 나눠주기 위해서 capacitor-aos, capacitor-ios 프로젝트를 새로 생성했습니다. 총 3개의 프로젝트에 각각 Capacitor를 설치하고, aos, ios에는 추가로 초기화를 진행합시다.

 

npx cap init

명령어를 실행하면 아래와 같은 순서들을 순서대로 입력하게 됩니다.

- App name: 앱 이름(스토어에 노출되는 이름)

- App ID: 앱 고유 식별자(예:  com.example.com으로 하셔도 상관 없지만, 추후 스토어 배포 시 존재하지 않는 식별자를 사용해야 하기 때문에 프로젝트 명을 넣어줍시다)

- Web directory: 빌드 결과물이 위치한 디렉토리(예: dist , build)

 

초기화 이후 아래와 같은 capacitor.config.ts를 확인할 수 있습니다. 

import type { CapacitorConfig } from "@capacitor/cli";

const config: CapacitorConfig = {
  appId: "com.gnaak.app",
  appName: "gnaak",
  webDir: "dist",
};

export default config;

 

플랫폼 추가

안드로이드

npm install @capacitor/android
npx cap add android

 

iOS

npm install @capacitor/ios
npx cap add ios --packagemanager CocoaPods

iOS에서는 SPM 대신에 pods를 사용합니다.

 

CocoaPods 설치가 되어 있지 않은 경우에는 터미널에서 아래와 같이 설치하시면 됩니다.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew --version
# Homebrew 5.0.7

brew install cocoapods
brew link --overwrite cocoapods
pod --version
# 1.16.2

 

설정 변경

import type { CapacitorConfig } from "@capacitor/cli";

const config: CapacitorConfig = {
  appId: "com.gnaak.app",
  appName: "gnaak",
  webDir: "dist",
  server: {
    url: "https://gnaak.co.kr/",       // 배포 이후 
    url: "http://172.24.208.1:3000",   // 로컬에서 사용
  },
};

export default config;

배포된 이후에는 배포된 서버의 url을, 로컬에서는 로컬 주소를 사용하시면 됩니다.(npm run build 이후 생성되는 dist만 사용하셔도 되는데, 이 방식은 프론트엔드 수정 시마다 다시 빌드가 필요해 실시간 반영이 되지 않아 불편합니다.)

 

로컬 주소는 웹 프로젝트 구성에 따라 다를 수 있습니다. VITE를 사용하는 경우 vite.config.ts에 host: true를 추가하면 프로젝트 실행 시 로컬 접속 수조를 확인할 수 있습니다.

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000,
    host: true,
  },
  resolve: {
    alias: {
      "@": "/src",
      container: "/src/container",
    },
  },
});

 

백엔드의 경우에도 외부 접근이 가능하게 실행해야 합니다. 

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

0.0.0.0을 통해 외부 접근을 허용해 줍시다. 

 

설정 적용

설정을 변경한 이후에는 aos와 ios에 적용시켜 줍시다.

npx cap sync // android, ios 둘 다 
npx cap sync android // android만 
npx cap sync ios // ios만 

npx cap open android // android studio 열기 
npx cap open ios // xcode 열기

 

여기까지가 React 기반의 프로젝트에 Capacitor를 적용해 Android와 iOS 앱으로 실행하기 위한 기본적인 설정을 모두 마쳤습니다. 이번 글에서는 Capacitor의 개념부터 시작해 패키지 설치, 초기화, 플랫폼 추가 그리고 로컬 및 배포 환경에 따른 설정 방법까지 살펴봤습니다. 이제 웹으로 개발한 React 애플리케이션을 실제 모바일 앱 환경에서 실행할 수 있는 준비는 끝난 셈입니다. 

 

다음 글에서는 capacitor 플러그인에 대해 알아보고, Safe Area 처리, 그리고 로그인 기능을 중심으로 실전에서 활용하는 방법을 다뤄보겠습니다. 

[capacitor] Safe Area 적용하기

언제나처럼 ㅡ 시작은 삽질이지만, 끝은 지식입니다.