Capacitor 8을 사용하여 Next.js 모바일 앱부터 시작하는 방법

소개

Next.js로 모바일 앱을 처음부터 만들고 싶으신가요? 이 가이드는 모바일을 위해 처음부터 설정된 Next.js 15 프로젝트를 만드는 방법을 안내합니다. 그리고 그 프로젝트를 Native iOS와 Android 앱으로 패키징하는 방법을 알려줍니다. Capacitor 8.

Capacitor를 사용하여

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

~30분

• 만들어 볼 것:
• 새로운 Next.js 15 프로젝트
• Capacitor 8 with essential plugins
• Capacitor 8와 필수 플러그인
• Native iOS와 Android 앱

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

필수 조건

다음 설치 여부를 확인하세요:

• Node.js 18+ ( node --version)
• Bun )curl -fsSL https://bun.sh/install | bash)
• 패키지 매니저 ( Xcode
• (macOS 전용, iOS 개발용) (안드로이드 개발을위한)

Step 1: 새로운 Next.js 프로젝트 만들기

먼저 Next.js 15 프로젝트를 새로 만드세요:

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

입력받을 때 다음 옵션을 선택하세요:

• TypeScript: 예 (권장)
• ESLint: 예
• Tailwind CSS: 예 (모바일 스타일링을위한 권장)
• src/ 디렉토리: 예
• 애플리케이션 라우터: 예 (권장)
• 임포트 별칭: 기본 (@/*)

프로젝트로 이동:

cd my-mobile-app

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에서 올바른 라우팅을 보장

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: __CAPGO_KEEP_0__ 8 설치

Capacitor core 패키지 설치:

Capacitor의 필수 플러그인 설치:

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

이러한 플러그인이 무엇을 하는지:

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

@__CAPGO_KEEP_0__/app

• @capacitor/app @__CAPGO_KEEP_0__/keyboard
• capacitor 8을 설치하세요. — 키보드 동작 제어
• @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 7단계: 빌드 및 실행

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

iOS 시뮬레이터에서 열기:

bun run mobile

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

bun run mobile:ios

and

bun run mobile:android

In Xcode (iOS):

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

In Android Studio:

1. Gradle이 동기화 완료를 기다리세요
2. Android 에뮬레이터에서 기기 드롭다운에서 선택하세요
3. Run 버튼을 클릭하거나 Shift + F10

Step 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에서 다시 빌드하세요.

code의 Next.js 편집은 이제 장치에서 즉시 반영됩니다.

10. 단계: 첫 번째 모바일 화면 만들기

간단한 모바일 친화적인 홈 스크린을 만들겠습니다. 업데이트 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>
  );
}

11. 단계: 안전 영역 처리

모바일 기기는 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
└── ...

다음 단계

컨텍스트: Capgo Builder / 네이티브 클라우드 빌드 제품 페이지. 역할: 짧은 UI 레이블 또는 네비게이션 아이템. 메시지 키 `native_build_builder_credit_next` (네이티브 빌드 빌더 크레딧 넥스트).

현재 Next.js 모바일 앱이 작동합니다. 다음 단계는 무엇입니까?:

• 앱 아이콘: 기본 아이콘을 ios/App/App/Assets.xcassets 와 android/app/src/main/res
• 스플래시 화면: 자연스러운 프로젝트에서 커스터마이즈하거나 @capacitor/splash-screen 설정
• 깊이 있는 링크: 앱의 URL 스키마를 구성하십시오

추가 기능 추가

• 카메라: bun add @capacitor/camera
• 위치 정보: 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 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/from viewport Pages Router app/layout.tsx:

import type { Viewport } from 'next';

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

에서 뷰포트 메타 태그를 넣으십시오. (pages/__CAPGO_KEEP_0__ pages/_app.tsxiOS 안전 영역을 한 번에 처리하기 _document.tsx.

iOS 안전 영역을 한 번에 처리하기

앱 셸을 하나만 만들고 안전 영역 패딩을 적용하세요 — 여러 개의 중첩된 컴포넌트에서 안전 영역 패딩을 적용하지 마세요:

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. 중첩된 컴포넌트에서 안전 영역 패딩을 여러 번 적용하면 UI가 잘린 것처럼 보이거나 너무 크게 보입니다.

그것과 @capgo/tailwind-capacitor를 사용하면 같은 패딩을 표현할 수 있습니다. pt-safe pb-safe px-safe 그것과

@Capacitor iOS contentInset 를 never context:Page/area: Live updates product page. Role: Short UI label or navigation item. Message key `live_update_dynamic_label_to` (Live Update Dynamic Label To).

In capacitor.config.ts, native inset을 사용하고 CSS (또는 Native Navigation의 )가 safe area를 관리하도록 하세요: contentInsetMode: 'css'__CAPGO_KEEP_0__의 자동 콘텐츠 inset과 CSS padding을 혼합하는 것은 일반적인 double spacing의 원인입니다.

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

를 사용하는 요소, 고정 픽셀 너비, 또는 큰 100vwIn Safari Web Inspector에서 실행하세요: w-screenTailwind의 경우 min-width.

를 사용하세요

[...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,
  }));

with w-screen replace w-full 가능할 때. 많은 수평 방향으로 넘치는 문제는 duplicated safe-area padding, 또는 고정 너비 컨테이너에서 오는 것이 아니라 viewport meta tag 자체에서 오는 것이 아니다. 100vw / w-screen앱 업데이트를 OTA로 푸시하는 방법

설정

__CAPGO_KEEP_0__ Capgo 문제 해결

bunx @capgo/cli init

설명: iOS: '개발자 인증서가 없습니다.'

실행 다시 시도해 보세요. bun install iOS: '개발자 인증서가 없습니다.'

Xcode를 열고 Signing & Capabilities로 이동하여 개발자 팀을 선택하세요. __CAPGO_KEEP_0__

안드로이드: “SDK 위치를 찾을 수 없음” 생성 android/local.properties 과 sdk.dir=/path/to/android/sdk

변경 사항이 기기에서 나타나지 않음 변경 사항이 나타나도록 하려면 bun run mobile 변경 사항을 적용한 후에

__CAPGO_KEEP_0__ 8 문서

• Capacitor 8 Documentation
• __CAPGO_KEEP_0__ - 실시간 업데이트
• Capgo/__CAPGO_KEEP_1__-네이티브 네비게이션
• capgo/capacitor-트랜지션
• @capgo/capacitor-transitions
• @capgo/tailwind-capacitor

Capgo으로 앱을 배포할 준비가 되었나요? Capgo을 사용하여 업데이트를 더 빠르게 전달하는 방법을 알아보세요. 무료 계정으로 가입하세요. 오늘.

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

__CAPGO_KEEP_0__을 사용 중이라면 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 Native Builds Capgo 통합 Capgo 제품 워크플로우 CI/CD 통합 __CAPGO_KEEP_0__ CI/CD 통합 구현 세부 사항 GitHub 액션 통합 구현 세부 사항 for the implementation detail in GitHub Actions Integration.