Capacitor 8로 Next.js 모바일 앱을 처음부터 만들기

소개

Next.js로 모바일 앱을 처음부터 만들고 싶나요? 이 가이드는 처음부터 모바일용으로 구성된 새 Next.js 15 프로젝트를 생성한 뒤, iOS 및 Android 네이티브 앱으로 패키징하는 방법을 안내합니다. Capacitor 8.

이 튜토리얼을 마치면 시뮬레이터에서 동작하는 모바일 앱을 갖게 되며, 계속 개발해 최종적으로 App Store와 Google Play에 출시할 수 있습니다.

소요 시간: 약 30분

만들게 될 것:

• App Router를 사용하는 새로운 Next.js 15 프로젝트
• 모바일용 static export 설정
• Capacitor 8과 필수 플러그인
• iOS 및 Android 네이티브 앱
• Live reload 개발 환경 구축

이미 Next.js 앱이 있나요? 확인해 보세요 Next.js 앱을 모바일로 변환하기 대신 사용하세요.

사전 요구사항

다음 도구들이 설치되어 있는지 확인하세요:

• Node.js 18+ (확인하려면 node --version)
• Bun 패키지 매니저 (curl -fsSL https://bun.sh/install | bash)
• iOS 프로파일링 (macOS 전용, iOS 개발용)
• 디버깅하기 (Android 개발용)

1단계: 새로운 Next.js 프로젝트 생성

먼저 새 Next.js 15 프로젝트를 생성하세요:

bunx create-next-app@latest my-mobile-app

프롬프트가 나타나면 다음 옵션을 선택하세요:

• TypeScript: 사용 (권장)
• ESLint: 지원
• Tailwind CSS: 사용 (모바일 스타일링 권장)
• src/ 디렉토리: 지원
• App Router: 사용 (권장)
• Import alias: 기본값 (@/*)

프로젝트 디렉토리로 이동하세요:

cd my-mobile-app

2단계: Next.js 정적 내보내기 설정

Capacitor에는 정적 HTML/JS/CSS 파일이 필요합니다. 다음을 업데이트해 Next.js를 static export로 구성하세요: next.config.ts:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
  // Ensure trailing slashes for proper routing in Capacitor
  trailingSlash: true,
};

export default nextConfig;

이 설정이 필요한 이유:

• output: 'export' — Node.js 서버 없이 정적 HTML을 생성합니다.
• images: { unoptimized: true } — Next.js Image Optimization을 비활성화합니다 (서버 필요).
• trailingSlash: true — 네이티브 WebView에서 올바른 라우팅을 보장합니다.

3단계: 모바일 스크립트 추가

다음 파일을 package.json 모바일 개발 스크립트로 업데이트하세요:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "mobile": "bun run build && bunx cap sync",
    "mobile:ios": "bun run mobile && bunx cap open ios",
    "mobile:android": "bun run mobile && bunx cap open android"
  }
}

빌드를 테스트하세요:

bun run build

다음이 표시되어야 합니다: out 정적 파일이 있는 디렉토리입니다.

4단계: Capacitor 8 설치

Capacitor 코어 패키지를 설치하세요:

bun add @capacitor/core
bun add -D @capacitor/cli

대부분의 모바일 앱에 필요한 필수 플러그인을 설치하세요:

bun add @capacitor/app @capacitor/keyboard @capacitor/splash-screen @capacitor/status-bar @capacitor/preferences

플러그인 기능:

• @capacitor/app — 앱 라이프사이클 이벤트 (포그라운드/백그라운드, 딥링크)
• @capacitor/keyboard — 키보드 동작 제어
• @capacitor/splash-screen — 네이티브 스플래시 스크린 제어
• @capacitor/status-bar — 기기 상태 표시줄 스타일링
• @capacitor/preferences — 키-값 저장소 (localStorage와 비슷하지만 네이티브)

5단계: Capacitor 초기화

프로젝트 정보로 Capacitor를 초기화하세요:

bunx cap init "My Mobile App" com.example.mymobileapp --web-dir out

변경 전:

• "My Mobile App" 앱 표시 이름 입력
• com.example.mymobileapp 앱 ID 입력 (리버스 도메인 표기법)

다음이 생성됩니다: capacitor.config.ts. 플러그인 설정으로 업데이트하세요:

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

const config: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      splashFullScreen: true,
      splashImmersive: true,
    },
    Keyboard: {
      resize: 'body',
      resizeOnFullScreen: true,
    },
    StatusBar: {
      style: 'light',
    },
  },
};

export default config;

6단계: 네이티브 플랫폼 추가

플랫폼 패키지 설치:

bun add @capacitor/ios @capacitor/android

네이티브 프로젝트 생성:

bunx cap add ios
bunx cap add android

다음이 생성됩니다: ios 및 android 네이티브 프로젝트가 포함된 디렉토리입니다.

7단계: 빌드 및 실행

프로젝트를 빌드하고 네이티브 플랫폼과 동기화하세요:

bun run mobile

iOS Simulator에서 열기:

bun run mobile:ios

또는 Android Emulator:

bun run mobile:android

Xcode (iOS)에서:

1. 기기 드롭다운에서 시뮬레이터를 선택하세요
2. Play 버튼을 클릭하거나 누르세요 Cmd + R

Android Studio에서:

1. Gradle 동기화가 완료될 때까지 기다리세요
2. 디바이스 드롭다운에서 에뮬레이터를 선택하세요
3. Run 버튼을 클릭하거나 누르세요 Shift + F10

8단계: Live Reload 설정

더 빠른 개발을 위해 live reload를 활성화하면 변경 사항이 기기에 즉시 반영됩니다.

1. 로컬 IP 주소를 확인하세요:

# macOS
ipconfig getifaddr en0

# Windows
ipconfig

2. 개발용 Capacitor 설정을 생성합니다. 다음을 추가하세요: capacitor.config.ts:

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

const devConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
  plugins: {
    // ... same plugin config
  },
};

const prodConfig: CapacitorConfig = {
  appId: 'com.example.mymobileapp',
  appName: 'My Mobile App',
  webDir: 'out',
  plugins: {
    // ... same plugin config
  },
};

const config = process.env.NODE_ENV === 'development' ? devConfig : prodConfig;

export default config;

3. 개발 서버를 시작하고 설정을 네이티브에 복사합니다:

bun run dev &
NODE_ENV=development bunx cap copy

4. Xcode/Android Studio에서 다시 빌드

이제 Next.js code를 수정하면 기기에 hot-reload됩니다.

9단계: 첫 모바일 화면 만들기

모바일 친화적인 간단한 홈 화면을 만들어 봅시다. 업데이트 src/app/page.tsx:

'use client';

import { useEffect, useState } from 'react';
import { App } from '@capacitor/app';
import { Keyboard } from '@capacitor/keyboard';

export default function Home() {
  const [appInfo, setAppInfo] = useState<{ name: string; version: string } | null>(null);

  useEffect(() => {
    // Get app info on mount
    App.getInfo().then(setAppInfo).catch(console.error);

    // Handle back button on Android
    const backHandler = App.addListener('backButton', ({ canGoBack }) => {
      if (!canGoBack) {
        App.exitApp();
      } else {
        window.history.back();
      }
    });

    // Hide keyboard when tapping outside inputs
    const keyboardHandler = Keyboard.addListener('keyboardWillShow', () => {
      document.body.classList.add('keyboard-open');
    });

    return () => {
      backHandler.then(h => h.remove());
      keyboardHandler.then(h => h.remove());
    };
  }, []);

  return (
    <main className="min-h-screen bg-linear-to-b from-blue-500 to-blue-700 flex flex-col items-center justify-center p-6 text-white">
      <h1 className="text-4xl font-bold mb-4">My Mobile App</h1>
      <p className="text-xl mb-8 text-center opacity-90">
        Built with Next.js 15 + Capacitor 8
      </p>

      {appInfo && (
        <div className="bg-white/20 rounded-lg p-4 backdrop-blur-sm">
          <p className="text-sm">
            {appInfo.name} v{appInfo.version}
          </p>
        </div>
      )}

      <div className="mt-12 space-y-4 w-full max-w-sm">
        <button className="w-full py-4 px-6 bg-white text-blue-600 rounded-xl font-semibold text-lg shadow-lg active:scale-95 transition-transform">
          Get Started
        </button>
        <button className="w-full py-4 px-6 bg-white/20 text-white rounded-xl font-semibold text-lg backdrop-blur-sm active:scale-95 transition-transform">
          Learn More
        </button>
      </div>
    </main>
  );
}

10단계: Safe Area 처리 추가

모바일 기기에는 노치, 홈 인디케이터, 상태 표시줄이 있습니다. Tailwind를 사용하여 Safe Area 처리를 추가하세요.

업데이트 src/app/globals.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

:root {
  --sat: env(safe-area-inset-top);
  --sar: env(safe-area-inset-right);
  --sab: env(safe-area-inset-bottom);
  --sal: env(safe-area-inset-left);
}

body {
  padding-top: var(--sat);
  padding-right: var(--sar);
  padding-bottom: var(--sab);
  padding-left: var(--sal);
}

/* Prevent text selection on mobile */
* {
  -webkit-user-select: none;
  user-select: none;
  -webkit-tap-highlight-color: transparent;
}

/* Allow text selection in inputs */
input, textarea {
  -webkit-user-select: auto;
  user-select: auto;
}

/* Keyboard handling */
.keyboard-open {
  --sab: 0px;
}

프로젝트 구조

프로젝트 결과물은 다음과 같습니다:

my-mobile-app/
├── android/              # Android native project
├── ios/                  # iOS native project
├── out/                  # Static build output
├── src/
│   ├── app/
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   └── ...
├── capacitor.config.ts   # Capacitor configuration
├── next.config.ts        # Next.js configuration
├── package.json
└── ...

다음 단계

이제 작동하는 Next.js 모바일 앱이 준비되었습니다. 다음 단계는 다음과 같습니다:

필수 설정

• 앱 아이콘: 다음 경로의 기본 아이콘을 교체하세요: ios/App/App/Assets.xcassets 및 android/app/src/main/res
• 스플래시 화면: 네이티브 프로젝트에서 커스터마이즈하거나 사용하세요: @capacitor/splash-screen 설정
• 딥링크: 앱의 URL scheme을 설정하세요

더 많은 기능 추가

• 카메라: bun add @capacitor/camera
• Geolocation: bun add @capacitor/geolocation
• 푸시 알림: bun add @capacitor/push-notifications
• 파일 시스템: bun add @capacitor/filesystem

네이티브 UI 및 트랜지션

네이티브 모바일 느낌을 위해 Konsta UI 대신 Capgo 플러그인을 사용하세요:

• @capgo/capacitor-native-navigation — Liquid Glass 탭 바 및 네이티브 네비게이션 바
• @capgo/capacitor-transitions — 네이티브 느낌의 페이지 전환 효과

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

Tailwind safe area 설정을 위해 다음을 추가하세요: @capgo/tailwind-capacitor:

bun add -D tailwind-capacitor

자세한 내용은 @capgo/capacitor-native-navigation 사용하기, @capgo/capacitor-transitions 사용하기, 그리고 tailwind-capacitor 레포지토리 Next.js 전용 설정을 위해.

iOS 레이아웃 이슈 해결 (Viewport, Safe Area, 가로 오버플로우)

iOS에서 콘텐츠가 잘리거나, 밀리거나, 가로 스크롤이 생긴다면, 더 추가하거나 overflow-x: hidden viewport 태그를 조정하는 것만으로는 보통 해결되지 않습니다. 다음 점검을 순서대로 진행하세요.

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

App Router (app/): export viewport 과 app/layout.tsx:

import type { Viewport } from 'next';

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  viewportFit: 'cover',
};

Pages Router (pages/): viewport meta 태그를 다음 위치에 넣으세요. pages/_app.tsx, 아니라 _document.tsx.

iOS safe area는 루트 래퍼 한 곳에서만 처리하세요

단일 앱 셸을 생성하고 그곳에 safe area 패딩을 적용하세요. 여러 중첩된 컴포넌트에 각각 적용하지 마세요:

html,
body,
#__next {
  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. 헤더, 모달, 레이아웃 래퍼에 safe-area 패딩이 중복되면 UI가 잘리거나 너무 커 보일 수 있습니다.

사용하면 @capgo/tailwind-capacitor, 다음과 같은 유틸리티로 동일한 패딩을 표현할 수 있습니다. pt-safe pb-safe px-safe 해당 단일 셸에서.

Capacitor iOS를 설정하세요 contentInset 대상 never 먼저

다음에서 capacitor.config.ts, native inset을 비활성화하는 편이 좋고 CSS(또는 Native Navigation의 contentInsetMode: 'css')가 safe area를 제어하도록 하세요:

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

Capacitor의 자동 content inset과 CSS env(safe-area-inset-*) padding을 함께 쓰면 이중 여백이 생기는 흔한 원인입니다.

실제로 overflow되는 요소를 찾으세요

흔한 원인은 다음을 사용하는 요소입니다: 100vw, Tailwind 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 포함 w-full 가능하면 사용하세요. 많은 가로 오버플로 문제는 100vw / w-screen중복된 safe-area 패딩이나 고정 너비 컨테이너 때문이며, viewport meta tag 자체 때문은 아닙니다.

Over-the-Air 업데이트

설정하기 Capgo App Store 재제출 없이 업데이트를 푸시하려면:

bunx @capgo/cli init

문제 해결

“Cannot find module” 오류로 빌드 실패 실행 bun install 다시 시도해 주세요.

iOS: “No signing identity found” 오류 Xcode를 열고 Signing & Capabilities로 이동한 뒤 개발 팀을 선택하세요.

Android: “SDK 위치를 찾을 수 없음” 생성 android/local.properties 포함 sdk.dir=/path/to/android/sdk

기기에 변경 사항이 반영되지 않음 변경 사항을 적용한 후 반드시 bun run mobile 를 실행했는지 확인하세요. 라이브 리로드를 사용하려면 IP 주소가 올바른지, 개발 서버가 실행 중인지 확인하세요.

리소스

• Capacitor 8 문서
• Next.js 15 문서
• Capgo - Live Updates
• @capgo/capacitor-native-navigation
• @capgo/capacitor-transitions
• @capgo/tailwind-capacitor

앱을 출시할 준비가 되셨나요? Capgo를 통해 업데이트를 더 빠르게 배포하는 방법을 알아보세요 — 무료 계정 가입하기 만들어 보세요.

Capacitor로 Next.js 모바일 앱 처음부터 만들기 8단계 이어서 하기

사용 중이라면 Capacitor 8로 Next.js 모바일 앱을 처음부터 만들기 CI/CD 자동화를 계획하려면, 다음을 연결하세요 Capgo CI/CD 설정하기 Capgo CI/CD의 제품 워크플로우용, Capgo Native Build Capgo Native Builds의 제품 워크플로우용, Capgo 연동 서비스 Capgo Integrations의 제품 워크플로우용, CI/CD 통합 CI/CD Integration의 구현 세부 사항은, 그리고 GitHub Actions 연동 GitHub Actions Integration의 구현 세부 사항을 참고하세요.