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

소개

Next.js로 모바일 앱을 처음부터 다시 만들고 싶으신가요? 이 가이드에서는 모바일 앱을 처음부터 다시 만들기 위해 Next.js 15 프로젝트를 생성하고, __CAPGO_KEEP_0__를 사용하여 iOS 및 Android 앱으로 패키징하는 방법을 안내합니다. Capacitor 8.

이 튜토리얼을 마치면, 시뮬레이터에서 작동하는 작동하는 모바일 앱을 만들 수 있으며, 개발을 계속하고 나중에는 앱 스토어와 구글 플레이 스토어에 게시할 수 있습니다.

소요 시간: ~30분

만들어질 내용:

• 새로운 Next.js 15 프로젝트
• App Router
• Capacitor 8 with essential plugins
• iOS 및 Android 앱
• 실시간 리로드 개발 환경

Next.js 앱이 이미 있으신가요? Next.js 앱을 모바일로 변환하세요 대신

준비 사항

다음 항목이 설치되어야 합니다:

• Node.js 18+ (__CAPGO_KEEP_0__ node --version)
• Bun Xcodecurl -fsSL https://bun.sh/install | bash)
• Xcode (macOS only, for iOS development)
• Android Studio (for Android development)

Step 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

Step 2: Next.js를 정적 내보내기 위해 구성하기

Capacitor는 정적 HTML/JS/CSS 파일이 필요합니다. 정적 내보내기 위해 Next.js를 구성하려면 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' — 정적 HTML을 생성하여 Node.js 서버가 필요하지 않도록 함
• images: { unoptimized: true } — Next.js 이미지 최적화를 비활성화 (서버가 필요함)
• trailingSlash: true — 네이티브 WebView에서 올바른 라우팅을 보장합니다.

Step 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 디렉토리를 볼 수 있습니다.

Step 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/키보드 — 키보드 동작 제어
• @capacitor/스플래시 스크린 — 네이티브 스플래시 스크린 제어
• @capacitor/상태 바 — 장치 상태 바 스타일링
• @capacitor/설정 — 키-값 저장소 (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 컨텍스트: Capgo 마케팅 웹사이트. 역할: 짧은 UI 레이블 또는 네비게이션 아이템. 위치: trust.astro 페이지. 메시지 키 `and` (And).

네이티브 프로젝트가 포함된 디렉토리입니다.

7단계: 빌드 및 실행

bun run mobile

iOS 시뮬레이터에서 열기:

bun run mobile:ios

또는 Android 에뮬레이터에서 열기:

bun run mobile:android

Xcode (iOS)에서:

1. 디바이스 드롭다운에서 시뮬레이터를 선택하세요
2. 플레이 버튼을 클릭하거나 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의 편집을 장치에서 실시간으로 반영할 수 있습니다.

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단계: 안전 영역 처리

모바일 기기는 notch, 홈 인디케이터, 상태 바를 가지고 있습니다. Tailwind를 사용하여 안전 영역 처리를 추가하세요.

업데이트 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
• 스플래시 화면: 자연스러운 프로젝트에서 personalize 하거나 @capacitor/splash-screen 설정
• 깊이 있는 링크: 앱의 URL 스키마를 구성하십시오

추가 기능 추가

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

자연스러운 UI 및 전환

Capgo 플러그인을 사용하여 Konsta UI 대신 네이티브 모바일 경험을 얻으세요:

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

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

Tailwind safe areas를 위해 추가하세요: @capgo/tailwind-capacitor:

bun add -D tailwind-capacitor

참조 Using @capgo/capacitor-native-navigation, Using @capgo/capacitor-transitions, 그리고 tailwind-capacitor 저장소 Next.js에 대한 구체적인 설정을위한

iOS 레이아웃 문제를 해결하기 (뷰포트, 안전 영역, 수평 스크롤)

iOS에서 콘텐츠가 잘려나거나-shifted 또는 수평 스크롤이 가능하다면, 더 많은 overflow-x: hidden 또는 뷰포트 태그를 조정하는 것만으로는 문제를 해결할 수 없다. 이러한 확인을 순서대로 진행하십시오.

뷰포트 메타 태그가 올바르게 적용되었는지 확인하십시오

App Router (app/: export viewport from app/layout.tsx:

import type { Viewport } from 'next';

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

페이지 라우터 (pages/뷰포트 메타 태그를 넣어라 pages/_app.tsx, _document.tsx.

iOS 안전 영역을 하나의 루트 wrapper에서만 처리하라

싱글 앱 셸을 만들고 안전 영역 패딩을 거기에 적용하라 — 여러 개의 중첩된 컴포넌트에서만 하지 말라

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. 중복된 안전 영역 패딩이 헤더, 모달, 레이아웃 wrapper에 있으면 UI가 잘린 것처럼 보이거나 너무 크게 보인다.

그것과 함께 @capgo/tailwind-capacitor와 같은 패딩을 표현할 수 있는 유틸리티를 사용할 수 있다. pt-safe pb-safe px-safe __CAPGO_KEEP_0__ iOS

Set Capacitor iOS contentInset 까지 never 첫 번째

In capacitor.config.ts, Native Navigation의 안전한 영역을 CSS (또는 Native Navigation의) contentInsetMode: 'css'CSS의 자동 콘텐츠 인셋과 __CAPGO_KEEP_0__의 패딩을 혼합하는 것은 더블 스페이싱의 일반적인 원인입니다.

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

Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) 일반적으로 원인은 요소가

, Tailwind

, 고정 픽셀 너비 또는 큰 100vwSafari Web Inspector에서 실행하세요: w-screen, a fixed pixel width, or a large min-width.

In Safari Web Inspector, run:

[...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수평 방향으로의 오버플로우 문제는 대부분 duplicated safe-area padding, 또는 고정 너비 컨테이너에서 오는 것이 아니라 viewport meta 태그 자체에서 오는 것이 아니다.

Over-the-Air 업데이트

설정 Capgo 애플리케이션 스토어의 재제출 없이 업데이트를 푸시하려면

bunx @capgo/cli init

문제 해결

설명 빌드가 "Cannot find module"로 실패합니다. bun install 실행하고 다시 시도해 보세요.

iOS: “인증서를 찾을 수 없습니다” Open Xcode, Signing & Capabilities로 이동하여 개발 팀을 선택하세요.

Android: “SDK 위치를 찾을 수 없습니다” 생성 android/local.properties 과 sdk.dir=/path/to/android/sdk

장치에 변경 사항이 나타나지 않습니다 변경 사항이 나타나지 않으면, 변경 사항을 저장한 후 다시 실행하세요. 라이브 리로드를 위해 IP 주소가 정확하고 개발 서버가 실행 중인지 확인하세요. bun run mobile 자원

__CAPGO_KEEP_0__ 8 문서

• Capacitor 8 Documentation
• __CAPGO_KEEP_0__ - 라이브 업데이트
• Capgo
• @capgo/capacitor-native-navigation
• @capgo/capacitor-transitions
• @capgo/tailwind-capacitor

앱을 배달하기 위해 준비되셨나요? Capgo을 사용하여 업데이트를 더 빠르게 전달하는 방법을 배워보세요 — 무료 계정으로 가입하세요 오늘.

Build a Next.js Mobile App from Scratch with Capacitor 8

Build a Next.js Mobile App from Scratch with __CAPGO_KEEP_0__ 8 Build a Next.js Mobile App from Scratch with Capacitor 8 __CAPGO_KEEP_0__ CI/CD Capgo CI/CD Capgo CI/CD Capgo Native Builds Capgo Native Builds Capgo Integrations Capgo Integrations CI/CD 연동 __CAPGO_KEEP_0__ 액션 연동 GitHub 액션 연동 for the implementation detail in GitHub Actions Integration.