[Next.js] Capacitor를 사용한 하이브리드 앱 설정

👋🏻 Intro

현재 진행 중인 Next.js 프로젝트를 모바일 앱(Android/iOS) 형태로 변환하는 작업이 필요하게 되었다.
특히나 네이티브 기능이 필요한 경우였고, Capacitor를 활용하여 브릿지 역할을 수행할 수 있음을 알게 되었다.

🧐 Capacitor란?

Capacitor는 웹 애플리케이션을 네이티브 앱 (Android, iOS)으로 감싸서 실행할 수 있도록 도와주는 프레임워크를 의미한다.

Next.js와 같은 웹 프로젝트를 모바일 환경에서도 활용할 수 있도록 지원하며, 이를 통해 네이티브 기능(예: NFC, GPS, 카메라 등)과도 연동할 수 있다.

모든 Capacitor 설정은 해당 공식 문서와 함께 했습니다 😀https://capacitorjs.com/docs/getting-started

1. 설치하기

1-1. Capacitor 패키지 설치

먼저, 기존 Next.js 프로젝트에 Capacitor를 추가해준다.

npm install @capacitor/core
npm install -D @capacitor/cli

1-2. Capacitor 초기화

위에서 패키지 설치가 완료되면, Capacitor를 사용하기 위한 프로젝트를 초기화가 필요하다.

npx cap init

초기화를 하면 아래와 같은 내용을 질문하고 이는 기호에 맞게 진행한다.

• App name : 앱의 이름
• App Package ID : 도메인 형식으로 앱 ID 설정 (예: com.example.app)
• Web directory: out → Next.js는 정적 빌드를 사용하므로 out 폴더 사용

이를 통해 capacitor.config.ts 파일이 생성된다.

2. Capacitor.config.ts 수정

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

const config: CapacitorConfig = {
  appId: "com.example.app",
  appName: "next-app",
  webDir: "out",
  server: {
    url: "http://내_로컬_IP:PORT", // IP 주소로 강제 지정
    cleartext: true, // HTTP 사용 허용
  },
};

export default config;

• webDir: 'out' : Capacitor가 웹 자산을 어디에서 가져오는지 설정
  (빌드 시 생성되는 out이라는 폴더에서 가져올 것을 의미)
• server.url : 모바일에서는 localhost를 통한 접근이 어려우므로, IP 주소로 강제 지정이 필요
• cleartext: true → HTTP 통신 허용 (HTTPS가 아닌 경우 필요)

3. Next.js 빌드 설정 (next.config.js 수정)

Next.js 프로젝트를 정적 사이트(out/ 폴더) 형태로 인식될 수 있도록 설정해야 한다.

const nextConfig = {
  reactStrictMode: true,
  output: "export",  // 정적 HTML 생성
  images: {
    unoptimized: true,  // next/image 최적화 기능 비활성화
  },
};

module.exports = nextConfig;

• images.unoptimized: true를 설정하면 next/image를 사용할 때 에러 방지
• output: "export" 설정을 통해 정적 사이트(out/ 폴더)로 변환

4. Android & iOS 플랫폼 추가

Capacitor에서 Android 및 iOS 플랫폼을 추가하여 앱으로 패키징할 수 있도록 설정합니다.

npm install @capacitor/android @capacitor/ios

4-1. Android & iOS 프로젝트 추가

npx cap add android
npx cap add ios

이를 통해 android/ 및 ios/ 폴더가 자동으로 생성된다.

5. 빌드 후 Capacitor와 동기화

Next.js 프로젝트를 정적 사이트(out/ 폴더)에 빌드한 후 Capacitor와 동기화합니다.

5-1. Next.js 프로젝트 빌드

npm run build

이를 통해 out/ 폴더가 생성된다.

5-2. Capacitor와 동기화

npx cap sync

Capacitor 프로젝트(iOS/Android)와 Next.js 프로젝트를 동기화

6. iOS 및 Android 앱 실행

6-1. iOS 앱 실행 (Xcode)

npx cap run ios

Xcode에서 실행되며 iOS 시뮬레이터에서 앱을 실행

6-2. Android 앱 실행 (Android Studio)

npx cap run android

Android Studio에서 Android 에뮬레이터를 통해 앱을 실행