Capacitor 8을 사용하여 Next.js 앱을 iOS & Android로 변환하세요.

Introduction

기존의 Next.js 웹 애플리케이스가 있나요? 이 안내서에서 Capacitor 8 — 성능이 개선되고 새로운 기능이 추가된 최신 버전입니다.

Capacitor는 웹 앱을 네이티브 컨테이너에 감싸서 기존의 React 코드베이스에 액세스할 수 있도록 해줍니다. 카메라, 파일 시스템, 푸시 알림과 같은 장치 API에 접근할 수 있습니다. React Native와 달리, 다시 작성할 필요가 없습니다 — Next.js code는 그대로 작동합니다.

학습할 내용:

기존의 Next.js 앱을 정적 내보내기로 구성합니다.
Capacitor 8과 필수 네이티브 플러그인을 추가합니다.
iOS 및 Android 시뮬레이터에서 빌드 및 테스트합니다.
빠른 개발을 위해 라이브 리로드를 활성화합니다.
iOS 레이아웃 문제를 해결합니다 (뷰포트, 안전 영역, 수평적 오버플로우)
Capgo Native Navigation and Transitions를 사용하여 네이티브한 느낌의 UI를 추가합니다

새로운 프로젝트를 시작하기 위해 무엇을 해야 하나요? Building a Next.js Mobile App from Scratch.

Next.js를 사용하는 Capacitor의 이점

Code의 재사용성: Next.js는 웹과 모바일 앱 간에 code를 공유하고 개발 시간과 노력을 절약할 수 있는 재사용 가능한 컴포넌트를 작성할 수 있도록 해줍니다.
성능: Next.js는 서버 사이드 렌더링 및 code 스플리팅과 같은 내장 성능 최적화 기능을 제공하여 빠른 로딩 시간과 smooth한 사용자 경험을 보장합니다.
네이티브 기능: Capacitor는 카메라, 위치 정보, 및 더 많은 네이티브 장치 기능에 접근할 수 있도록 해주어 기능-rich한 모바일 앱을 빌드할 수 있습니다.
간소화된 개발: Capacitor를 사용하면 familiar한 웹 기술을 사용하여 모바일 앱을 개발하고 테스트할 수 있으며 학습 곡선이 줄어들고 개발 프로세스가 단순화됩니다.

사전 요구 사항

__CAPGO_KEEP_0__를 구성하기 전에 다음을 확인하세요.

Node.js 18 이상이 설치되어야 합니다.
기존 Next.js 15 이상의 애플리케이션
Xcode (iOS 개발을 위해 macOS만 해당)
Android Studio (Android 개발을 위해)

Next.js 앱을 모바일로 구성하는 방법

Next.js 앱을 정적으로 내보내는 데 필요한 첫 단계는 Next.js 앱을 정적 내보내기로 구성하는 것입니다. Capacitor는 정적 HTML/JS/CSS 파일을 네이티브 앱으로 패키징하기 위해 필요합니다.

Open your next.config.js (or next.config.ts) file and add the export configuration:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
};

module.exports = nextConfig;

The output: 'export' setting tells Next.js to generate static HTML files, and images: { unoptimized: true } Cloudflare bypasses Next.js image optimization which requires a server.

Important: If you’re using features that require a server (API routes, server components with data fetching, etc.), you’ll need to refactor those to use client-side alternatives or external APIs.

Add mobile-specific scripts to your 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"
  }
}

Test the static export by running:

bun run build

You should see an out Capacitor folder at the root of your project. This contains all the static files that Capacitor will bundle into your native app.

Capacitor 프로젝트에 8을 추가하는 방법

Next.js 앱을 네이티브 모바일 컨테이너로 패키징하려면 다음 단계를 따르세요.

Capacitor core 및 CLI을 설치하세요.

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

Capacitor에서 일반적으로 필요로하는 플러그인을 설치하세요.

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

이 플러그인은 다음 기능을 제공합니다.

@capacitor/app: 앱 라이프사이클 이벤트를 처리합니다 (전경/후면, URL)
@capacitor/keyboard: 모바일 키보드 동작을 제어합니다.
@capacitor/splash-screen: 네이티브 스플래시 스크린을 관리합니다.
@capacitor/preferences: 영구적으로 키-값 데이터를 저장하세요

Capacitor을 초기화하여 프로젝트 세부 정보를 입력하세요:

bunx cap init my-app com.example.myapp --web-dir out

대체 my-app 앱 이름으로 대체하고 com.example.myapp 역 도메인 표기법으로 앱 ID (역 도메인 표기법)로 대체합니다.

__CAPGO_KEEP_0__을 사용하여 올바른 구성으로 파일을 생성하거나 업데이트하세요: capacitor.config.ts 원시 플랫폼을 설치하세요:

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

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'out',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      showSpinner: false,
      splashFullScreen: true,
      splashImmersive: true,
    },
  },
};

export default config;

원시 플랫폼 폴더를 추가하세요:

bun add @capacitor/ios @capacitor/android

__CAPGO_KEEP_0__은 프로젝트의 루트 폴더에 원시 프로젝트 폴더와 폴더를 생성합니다.

bunx cap add ios
bunx cap add android

Capacitor은 프로젝트의 루트 폴더에 원시 프로젝트 폴더와 폴더를 생성합니다. ios __CAPGO_KEEP_0__은 프로젝트의 루트 폴더에 원시 프로젝트 폴더와 폴더를 생성합니다. android __CAPGO_KEEP_0__은 프로젝트의 루트 폴더에 원시 프로젝트 폴더와 폴더를 생성합니다.

__CAPGO_KEEP_0__을 빌드하려면 Android 프로젝트가 필요합니다. __CAPGO_KEEP_0__. iOS의 경우 Mac에 __CAPGO_KEEP_0__.

프로젝트를 빌드하고 동기화하세요.

bun run mobile

__CAPGO_KEEP_1__는 사용자 정의 스크립트를 실행하여 Next.js 프로젝트를 빌드하고 네이티브 플랫폼과 정적 파일을 동기화합니다.

네이티브 앱 빌드 및 배포

네이티브 모바일 앱을 빌드하고 배포하려면 다음 단계를 따르세요: iOS 앱을 개발하려면 __CAPGO_KEEP_0__ 가 설치되어야 하며, Android 앱을 개발하려면 __CAPGO_KEEP_0__ 가 설치되어야 합니다. 또한 앱 스토어에 앱을 배포하려면 iOS의 경우 Apple Developer Program에 등록하고 Android의 경우 Google Play Console에 등록해야 합니다.

Open the native projects:

iOS용으로:

bun run mobile:ios

Android용으로:

bun run mobile:android

또는 직접 Capacitor CLI을 사용하세요:

bunx cap open ios
bunx cap open android

앱을 빌드하고 실행하세요:

android-studio-run

Android Studio에서 프로젝트가 준비될 때까지 기다리세요. 그런 다음 연결된 장치나 에뮬레이터에 앱을 배포하기 위해 '실행' 버튼을 클릭하세요.
Xcode에서 실제 장치에 앱을 배포하기 위해 서명 계정을 설정하세요. 이 작업을 처음하는 경우 Xcode는 Apple Developer Program에 가입한 경우에만 앱을 실행하는 방법을 안내합니다. 설정이 완료되면 '재생' 버튼을 클릭하여 연결된 장치에서 앱을 실행하세요.

성공했습니다! Next.js 웹 앱을 모바일 장치에 성공적으로 배포했습니다.

하지만 개발 중에는 더 빠른 방법이 있습니다...

Capacitor Live Reload

개발 중에는 즉시 모바일 기기에서 변경 사항을 볼 수 있는 라이브 리로드 기능을 사용할 수 있습니다. 이 기능을 활성화하려면 다음 단계를 따르세요.

IP 주소 찾기:

macOS에서 터미널에서 다음 명령어를 실행하세요.
```
ipconfig getifaddr en0
```
Windows에서 실행하세요.
```
ipconfig
```
IPv4 주소가 출력된 곳에서 찾으세요.

개발 서버에 대한 capacitor.config.ts 를 업데이트하세요.

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

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'out',
  server: {
    url: 'http://YOUR_IP_ADDRESS:3000',
    cleartext: true,
  },
};

export default config;

개발 서버 주소에 YOUR_IP_ADDRESS 를 입력하세요 (예: 192.168.1.100).

native 프로젝트에 변경 사항을 적용하세요.

bunx cap copy

native 프로젝트에서 변경 사항을 적용하려면 다음을 수행하세요: copy command는 웹 폴더와 구성 변경을 native 프로젝트로 복사하고 전체 프로젝트를 업데이트하지 않고 합니다.

Android Studio 또는 Xcode를 사용하여 앱을 디바이스에서 다시 빌드하고 실행하세요.

Next.js 앱에 대한 변경 사항을 언제든지 만들면 모바일 앱이 자동으로 다시 로드되어 변경 사항을 반영합니다.

주의: 새로운 플러그인을 설치하거나 native 파일을 변경하면 live reloading은 웹 code 변경 사항에만 적용되므로 native 프로젝트를 다시 빌드해야 합니다.

Capacitor 플러그인 사용

Capacitor 플러그인은 Next.js 앱에서 native 디바이스 기능에 접근할 수 있도록 해줍니다. 예를 들어 Share 플러그인을 사용해 보겠습니다. Share 플러그인 설치: Share 플러그인을 사용하는

파일을 업데이트하세요.

bun add @capacitor/share

native 프로젝트와의 동기화: pages/index.js __CAPGO_KEEP_0__ 플러그인 사용하기:

import Head from 'next/head';
import styles from '../styles/Home.module.css';
import { Share } from '@capacitor/share';

export default function Home() {
  const share = async () => {
    await Share.share({
      title: 'Open Youtube',
      text: 'Check new video on youtube',
      url: 'https://www.youtube.com',
      dialogTitle: 'Share with friends',
    });
  };

  return (
    <div className={styles.container}>
      <Head>
        <title>Create Next App</title>
        <meta name="description" content="Generated by create next app" />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className={styles.main}>
        <h1 className={styles.title}>
          Welcome to <a href="https://nextjs.org">Capgo!</a>
        </h1>

        <p className={styles.description}>
          <h2>Cool channel</h2>
          <button onClick={() => share()}>Share now!</button>
        </p>
      </main>
    </div>
  );
}

__CAPGO_KEEP_0__ 플러그인은 Next.js 앱에서 native 디바이스 기능에 접근할 수 있도록 해줍니다. 예를 들어 Share 플러그인을 사용해 보겠습니다.

As mentioned earlier, when installing new plugins, we need to perform a sync operation and then redeploy the app to our device. To do this, run the 다음 명령어를 실행하세요:

bun run mobile

Or just sync without rebuilding:

bunx cap sync

Rebuild and run the app on your device.

Now, when you click the “Share now!” button, the native share dialog will appear, allowing you to share the content with other apps.

Next, you can make the app feel more native on iOS and Android with Capgo navigation and transitions, and fix common iOS layout issues that cause horizontal overflow or cropped safe areas. ## Capgo Native Navigation and Transitions로 Native-feeling UI를 구현하세요

I’ve worked for years with Ionic to build cross-platform applications, but integrating it with Next.js is hacky and rarely worth it when you already have Tailwind CSS 4.

For a native mobile feel in a Next.js + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:

@capgo/capacitor-native-navigation — iOS에서 Liquid Glass 탭바, Android에서 흐린 탭바 스타일을 사용하는 네이티브 네비게이션바, 그리고 네이티브 크롬을 소유한 플러그인이 있는 Next.js 라우터.
@capgo/capacitor-transitions — WebView layer에서 Ionic-style 페이지 전환과 iOS의 edge swipe-back를 사용할 수 있습니다. Ionic UI를 채택하지 않습니다.

두 개를 모두 설치하세요.

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

CSS inset 모드를 사용하여 네이티브 바를 존중하는 웹 콘텐츠를 네이티브 네비게이션과 구성하세요.

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

Liquid Glass 탭바를 렌더링하세요 (iOS는 시스템 소유 렌더링을 사용하고 Android는 흐린 WebView 배경을 사용합니다).

await NativeNavigation.setTabbar({
  selectedId: 'home',
  labelVisibilityMode: 'labeled',
  icons: true,
  colors: { dynamic: true },
  tabs: [
    { id: 'home', title: 'Home', icon: { svg: '...' } },
    { id: 'settings', title: 'Settings', icon: { svg: '...' } },
  ],
});

await NativeNavigation.addListener('tabSelect', ({ id }) => {
  router.push(`/${id}`);
});

앱 셸에서 네이티브 페이지 전환을 추가하세요.

import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';

initTransitions({ platform: 'auto' });

페이지를 cap-router-outlet, cap-page, cap-content, setDirection('forward') , setDirection('back') , router.push() 또는 router.back(). Do not duplicate web headers or footers when native navigation owns those surfaces.

See the full guides: Using @capgo/capacitor-native-navigation 및 Using @capgo/capacitor-transitions.

Tailwind에서 안전한 영역

Tailwind CSS에서 장치 안전 영역을 사용하려면 @capgo/tailwind-capacitor (__CAPGO_KEEP_0__으로 출판됨). It provides tailwind-capacitor npm-friendly Tailwind 플러그인과 다른 유용한 기능: safe-areas Capacitor

bun add -D tailwind-capacitor

In styles/globals.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

Next.js 프로젝트에서 사용할 수 있는 유용한 도구들을 사용하세요. pt-safe, pb-safe, px-safe 대신에 env(safe-area-inset-*) 수동으로 open a PR on GitHub.

Next.js 설정에 필요한 기능이 누락되어 있는 경우,

__CAPGO_KEEP_0__ overflow-x: hidden Fixing iOS Layout Issues (Viewport, Safe Area, and Horizontal Overflow)

iOS에서 콘텐츠가 잘려나가거나-shifted되거나 가로 스크롤이 가능하다면,

Viewport 태그를 수정하거나 (app/App Router 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 (Next.js는 뷰포트 동작에 대한 태그를 기대하는 방식과 다르게 태그를 적용할 수 있습니다.) _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);
}

. 중복된 안전 영역 패딩이 헤더, 모달, 레이아웃 wrapper에 적용되어 UI가 잘린 것처럼 보이거나 너무 크게 보일 수 있습니다. .app-shell그리고

@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitor__CAPGO_KEEP_0__ iOS를 __CAPGO_KEEP_0__로 설정하세요. pt-safe pb-safe px-safe 단일 셸에서만 사용하세요.

Capacitor iOS를 첫 번째로 설정하세요. `contentInset` __CAPGO_KEEP_0__를 사용하여 원하는 패딩을 표현하세요. `never` 단일 셸에서만 사용하세요.

__CAPGO_KEEP_0__ iOS를 __CAPGO_KEEP_0__로 설정하세요. capacitor.config.ts__CAPGO_KEEP_0__를 사용하여 원하는 패딩을 표현하세요. contentInsetMode: 'css'__CAPGO_KEEP_0__ iOS를 첫 번째로 설정하세요.

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

Capacitor를 사용하여 원하는 패딩을 표현하세요. env(safe-area-inset-*) __CAPGO_KEEP_0__ iOS를 __CAPGO_KEEP_0__로 설정하세요.

__CAPGO_KEEP_0__를 사용하여 원하는 패딩을 표현하세요.

__CAPGO_KEEP_0__ iOS를 첫 번째로 설정하세요. 100vw, Tailwind w-screen, a fixed pixel width, or a large 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안전 영역 패딩이 중복되거나, 고정 너비 컨테이너에서 발생합니다. — viewport meta 태그 자체에서 발생하지 않습니다.

성능 최적화

Next.js 및 Capacitor 앱의 최적 성능을 보장하기 위해 다음의 최적화 방법을 고려하세요:

사용되지 않는 의존성 및 자산을 제거하여 앱 크기를 최소화하세요.
이미지 및 기타 미디어 파일을 로드 시간을 줄이기 위해 최적화하세요.
컴포넌트 및 페이지의 초기 로드 성능을 향상시키기 위해 지연 로딩을 구현하세요.
서버 사이드 렌더링 (SSR)과 Next.js를 사용하여 앱의 로딩 속도와 검색 엔진 최적화 (SEO)를 향상하세요.
Capacitor의 내장 최적화 기능, chẳng hạn như 웹 뷰 캐싱 및 앱 번들링을 활용하세요.

결론

Capacitor 8을 사용하여 기존의 Next.js 웹 애플리케이션을 네이티브 iOS 및 Android 앱으로 변환했습니다. 웹 코드베이스는 이제 모바일 장치에서 네이티브로 실행되며 장치 API에 접근할 수 있습니다.

완료한 일들:

Next.js를 정적 내보내기 위해 구성했습니다.
Capacitor 8을 포함하여 필수 플러그인을 추가했습니다.
iOS 및 Android 시뮬레이터로 빌드 및 배포했습니다.
개발 중에 라이브 리로드를 활성화했습니다.
iOS 레이아웃 문제 (뷰포트, 안전 영역, 오버플로)를 해결했습니다.
Capgo Native Navigation 및 Transitions를 사용하여 네이티브한 느낌의 UI를 추가했습니다.

다음 단계:

설정 Capgo 앱 스토어 재제출 없이 오버 더 에어 업데이트 설정
카메라, 위치 정보, 푸시 알림 등 네이티브 플러그인 추가
프로덕션용 앱 아이콘 및 스플래시 스크린 구성
앱 스토어 및 구글 플레이 제출 준비

새로운 프로젝트 시작? Next.js 모바일 앱부터 시작하는 방법 가이드된_walkthrough를 확인하세요.

자원

Next.js 문서
@capgo/capacitor-native-navigation — Liquid Glass tab bar 및 네이티브 크롬
Capacitor 8 문서
@capgo/capacitor-transitions — 네이티브 느낌의 페이지 전환
@capgo/tailwind-capacitor — Tailwind safe-area 유틸리티를 위한 Capacitor
Capgo - Capacitor 앱을 위한 실시간 업데이트

Capgo을 사용하여 더 나은 앱을 더 빠르게 빌드하는 방법을 알아보세요. __CAPGO_KEEP_0__ 무료 계정으로 가입하세요. 오늘.

Capacitor 8을 사용하여 Convert Your Next.js 앱을 iOS 및 Android로 계속 진행하세요.

__CAPGO_KEEP_0__을 사용 중이라면 iOS 및 Android 앱으로 변환하기 위해 Capacitor 8을 사용하세요. native 플러그인 작업을 계획하기 위해 연결하세요. Capgo 플러그인 디렉토리 Capgo 플러그인 디렉토리에서 제품 워크플로우를 위해. Capacitor 플러그인들에 의해 Capgo Capacitor 플러그인들에 의해 Capgo의 구현 세부 사항을 위해. 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부 사항을 위해. Ionic Enterprise 플러그인 대체 Ionic Enterprise 플러그인 대체의 제품 워크플로우를 위해. Capgo 네이티브 빌드 Capgo 네이티브 빌드의 제품 워크플로우를 위해.

Capacitor 8을 사용하여 다음.js 앱을 iOS &amp; Android로 변환하세요.