소개
기존의 Next.js 웹 애플리케이션이 있나요? 이 가이드에서는 __CAPGO_KEEP_0__를 사용하여 기존의 Next.js 웹 애플리케이션을 native iOS 및 Android 모바일 앱으로 변환하는 방법을 배웁니다. Capacitor 8 — 성능이 향상되고 새로운 기능이 추가된 최신 버전
Capacitor은 웹 앱을 네이티브 컨테이너에 감싸줌으로써 카메라, 파일 시스템, 푸시 알림과 같은 장치 API에 접근할 수 있게 해줍니다. existing React 코드베이스를 유지하면서 code이 Next.js로 실행되도록 합니다.
학습할 내용:
- 기존의 Next.js 앱을 정적 내보내기로 구성합니다.
- Capacitor 8에 필수 네이티브 플러그인을 추가하여
- iOS 및 Android 시뮬레이터에서 빌드 및 테스트합니다.
- 빠른 개발을 위해 라이브 리로드를 활성화합니다.
- iOS 레이아웃 문제를 해결합니다 (뷰포트, 안전 영역, 수평 방향 오버플로우)
- Capgo 네이티브 네비게이션 및 트랜지션을 사용하여 네이티브 느낌의 UI를 추가합니다.
새로운 프로젝트를 시작하고 싶으신가요? __CAPGO_KEEP_0__의 이점을 확인하세요..
Capacitor 재사용성의 이점을 확인하세요.
- Code의 이점을 확인하세요.: Next.js는 재사용 가능한 컴포넌트를 작성하고 웹 및 모바일 앱 간에 code를 공유할 수 있으므로 개발 시간과 노력을 절약할 수 있습니다.
- 성능: Next.js는 서버 사이드 렌더링 및 code 분할과 같은 내장 성능 최적화를 제공하여 빠른 로딩 시간과 smooth한 사용자 경험을 보장합니다.
- 자연스러운 네이티브 기능: Capacitor는 카메라, 위치 정보 및 더 많은 네이티브 장치 기능에 대한 접근을 제공하여 기능-rich한 모바일 앱을 빌드할 수 있습니다.
- 간소화된 개발: Capacitor를 사용하면 친숙한 웹 기술을 사용하여 모바일 앱을 개발하고 테스트할 수 있으며 학습 곡선이 줄어들고 개발 프로세스가 단순화됩니다.
사전 요구 사항
시작하기 전에 다음을 확인하세요:
- Node.js 18+ 설치
- 기존 Next.js 15+ 응용 프로그램
- Xcode (iOS 개발을 위해 macOS만)
- Android Studio (Android 개발을 위해)
Next.js 앱을 모바일로 구성하는 방법
Next.js 앱을 정적으로 내보내기 위해 첫 번째 단계는 Capacitor이 정적 HTML/JS/CSS 파일을 모바일 앱으로 패키징할 수 있도록 하기 위한 설정입니다.
Next.js 앱을 정적으로 내보내기 위해 첫 번째 단계는 __CAPGO_KEEP_0__이 정적 HTML/JS/CSS 파일을 모바일 앱으로 패키징할 수 있도록 하기 위한 설정입니다. next.config.js Next.js 앱을 정적으로 내보내기 위해 첫 번째 단계는 __CAPGO_KEEP_0__이 정적 HTML/JS/CSS 파일을 모바일 앱으로 패키징할 수 있도록 하기 위한 설정입니다. next.config.tsNext.js 앱을 정적으로 내보내기 위해 첫 번째 단계는 __CAPGO_KEEP_0__이 정적 HTML/JS/CSS 파일을 모바일 앱으로 패키징할 수 있도록 하기 위한 설정입니다.
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
images: {
unoptimized: true,
},
};
module.exports = nextConfig;Next.js 앱을 정적으로 내보내기 위해 첫 번째 단계는 __CAPGO_KEEP_0__이 정적 HTML/JS/CSS 파일을 모바일 앱으로 패키징할 수 있도록 하기 위한 설정입니다. output: 'export' Next.js에서 정적 HTML 파일을 생성하도록 지시하는 설정입니다. images: { unoptimized: true } Next.js의 이미지 최적화를 사용할 수 없으며 서버가 필요합니다.
중요: 서버가 필요한 기능(API 라우트, 데이터 페칭을 하는 서버 컴포넌트 등)을 사용 중이라면, 클라이언트 측 대안 또는 외부 API를 사용하거나 리팩토링해야 합니다.
모바일 전용 스크립트를 추가하세요. 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정적 내보내기 테스트를 완료하면 __CAPGO_KEEP_0__ 폴더가 프로젝트의 루트 폴더에 생성됩니다. 이 폴더에는 __CAPGO_KEEP_0__가 네이티브 앱에 포함할 정적 파일이 모두 포함되어 있습니다. out folder at the root of your project. This contains all the static files that Capacitor will bundle into your native app.
Adding Capacitor 8 to Your Project
Capgo core 및 __CAPGO_KEEP_1__을 설치하세요.
- Install Capacitor core and CLI:
bun add @capacitor/core
bun add -D @capacitor/cli- Capacitor 8을 프로젝트에 추가하는 방법
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 outReplace my-app 앱 이름으로 대체하세요 com.example.myapp 앱 ID (역 도메인 표기법)과 함께 사용하세요.
- Create or update the
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- 자연 플랫폼 폴더 추가:
bunx cap add ios
bunx cap add androidCapacitor은 프로젝트의 루트 폴더에 있는 자연 프로젝트를 포함하는 폴더를 생성하고 ios 그리고 android 폴더를 생성합니다.
Android 프로젝트를 빌드하려면 Android Studio가 필요합니다. iOS의 경우 Mac와 Xcode가 필요합니다.__CAPGO_KEEP_0__ __CAPGO_KEEP_0__.
- 프로젝트를 빌드하고 동기화하세요:
bun run mobile이것은 Next.js 프로젝트를 빌드하고 네이티브 플랫폼과 정적 파일을 동기화하는 커스텀 스크립트를 실행합니다.
네이티브 앱 빌드 및 배포
네이티브 모바일 앱을 빌드 및 배포하려면 다음 단계를 따르세요: iOS 앱을 개발하려면 Xcode가 설치되어야 하며, Android 앱을 개발하려면 Android Studio가 설치되어야 합니다. 또한 앱 스토어에서 앱을 배포하려면 iOS에서는 Apple Developer Program에 등록하고 Android에서는 Google Play Console에 등록해야 합니다. 네이티브 프로젝트 열기: iOS: Android: 또는 직접 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__:
- Building and Deploying Native Apps
To build and deploy your native mobile app, follow these steps: To develop iOS apps, you need to have
bun run mobile:iosXcode
bun run mobile:androidOr directly with Capacitor CLI:
bunx cap open ios
bunx cap open android- 앱을 빌드하고 실행하세요:
-
안드로이드 스튜디오에서 프로젝트가 준비될 때까지 기다리십시오. 그런 다음 연결된 장치나 에뮬레이터에 앱을 배포하기 위해 "실행" 버튼을 클릭하십시오.
-
축하합니다! Next.js 웹 앱을 성공적으로 모바일 장치에 배포했습니다.
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 예를 들어, 로컬 IP 주소 ( 192.168.1.100).
- 원시 프로젝트에 변경 사항을 적용하세요:
bunx cap copy명령어는 웹 폴더와 구성 변경 사항을 원시 프로젝트로 복사하고 전체 프로젝트를 업데이트하지 않습니다. copy Android Studio 또는 Xcode를 사용하여 기기에서 앱을 다시 빌드하고 실행하세요.
- Next.js 앱에 대한 변경 사항을 만들면, 모바일 앱은 자동으로 변경 사항을 반영하여 다시 로드됩니다.
주의: 새로운 플러그인을 설치하거나 원시 파일에 변경 사항을 만들면, 원시 프로젝트를 다시 빌드해야 합니다. 왜냐하면 라이브 리로딩은 웹 __CAPGO_KEEP_0__ 변경 사항만 적용되기 때문입니다.
Note: If you install new plugins or make changes to native files, you’ll need to rebuild the native project since live reloading only applies to web code changes.
Capacitor 플러그인 사용하기
Capacitor 플러그인은 Next.js 앱에서 네이티브 디바이스 기능에 접근할 수 있도록 해줍니다. 예를 들어 Share 플러그인을 사용하는 방법에 대해 알아보겠습니다. Share 플러그인 사용하기 Share 플러그인을 설치하세요.
- __CAPGO_KEEP_0__ 파일을 Share 플러그인을 사용하는 파일로 업데이트하세요.
bun add @capacitor/share- 변경 사항을 네이티브 프로젝트와 동기화하세요.
pages/index.js이전 섹션에서 언급했듯이 새로운 플러그인을 설치할 때는 동기화 작업을 수행하고 앱을 다시 배포해야 합니다. 이 작업을 수행하려면 다음 명령어를 실행하세요.
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>
);
}- 또는 재빌드 없이 동기화만 하세요.
앱을 다시 빌드하고 디바이스에서 실행하세요.
bun run mobile이제 “공유하기!” 버튼을 클릭하면 네이티브 공유 대화상자가 나타나고, 콘텐츠를 다른 앱과 공유할 수 있습니다.
bunx cap sync- __CAPGO_KEEP_0__ 플러그인 설치하기
__CAPGO_KEEP_0__ 플러그인은 네이티브 디바이스 기능에 접근할 수 있도록 해줍니다.
__CAPGO_KEEP_0__를 사용하여 여러 년 동안 Ionic 을 사용하여 크로스 플랫폼 애플리케이션을 만들었습니다. 하지만 Next.js와 통합하는 것은 복잡하고 거의 가치가 없습니다. 이미 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 플러그인을 사용하는 것이 좋습니다. 웹 전용 UI 키트인 Konsta UI와 같은 UI 키트 대신. @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation
- @capgo/capacitor-transitions @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions
— WebView layer에서 Ionic-style 페이지 전환과 iOS 에지 스와이프 백을 지원합니다. Ionic UI를 사용하지 않아도 됩니다.Both를 설치하세요.
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync__CAPGO_KEEP_0__ CSS inset 모드에서 네이티브 네비게이션을 구성하여 웹 콘텐츠가 네이티브 바를 존중하도록 하세요.
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});__CAPGO_KEEP_0__에서 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' });__CAPGO_KEEP_0__에서 __CAPGO_KEEP_1__된 페이지를 cap-router-outlet, cap-page, 및 cap-content, 및 __CAPGO_KEEP_2__()를 호출하세요. setDirection('forward') __CAPGO_KEEP_2__()를 __CAPGO_KEEP_3__() 또는 __CAPGO_KEEP_4__() 전에 또는 __CAPGO_KEEP_5__() 또는 __CAPGO_KEEP_6__() 후에 호출하세요. setDirection('back') 네이티브 네비게이션에서 웹 헤더 또는 푸터를 중복하지 마세요. router.push() __CAPGO_KEEP_0__에서 __CAPGO_KEEP_1__-네이티브-네비게이션을 참조하세요. router.back()__CAPGO_KEEP_0__에서 __CAPGO_KEEP_1__-네이티브-네비게이션을 사용하는 방법을 참조하세요.
__CAPGO_KEEP_0__에서 __CAPGO_KEEP_1__-네이티브-네비게이션을 사용하는 방법을 참조하세요. capgo에서 capacitor-네이티브-네비게이션을 사용하는 방법을 참조하세요. 및 @capgo/capacitor-전환을 사용합니다..
Tailwind의 디바이스 안전 영역
Tailwind CSS의 디바이스 안전 영역을 사용하려면 @capgo/tailwind-capacitor (__CAPGO_KEEP_0__에서 tailwind-capacitor npm에서 safe-areas Capacitor-친화적인 Tailwind 플러그인:
bun add -D tailwind-capacitor대신 styles/globals.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";및 pt-safe, pb-safe대신 px-safe __CAPGO_KEEP_0__ env(safe-area-inset-*) Next.js 환경에서 프로젝트를 직접 개발하고 있습니다. 만약 Next.js 설정에 필요한 것이 빠져 있다면 GitHub에 PR을 열어주세요.
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 Router (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-shellWith @__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__
, 동일한 패딩을 표현할 수 있는 유틸리티들처럼 @capgo/tailwind-capacitorSet __CAPGO_KEEP_0__ iOS pt-safe pb-safe px-safe 안전 영역을
Capacitor contentInset __CAPGO_KEEP_1__ never first
In capacitor.config.ts, native inset을 비활성화하고 CSS (또는 Native Navigation의 )가 safe area를 관리하도록 하세요. contentInsetMode: 'css'Mixing __CAPGO_KEEP_0__’s automatic content inset with 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
, 고정 픽셀 너비, 또는 100vwSafari Web Inspector에서 실행하세요: w-screenTailwind를 사용하여 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,
}));With Tailwind, replace w-screen __CAPGO_KEEP_0__ w-full __CAPGO_KEEP_0__의 경우, 가능할 때는 100vw / w-screen, 중복된 safe-area 패딩, 또는 고정 너비 컨테이너 — viewport meta 태그 자체에서 오는 것이 아님.
성능 최적화
Capacitor와 함께 최적의 성능을 보장하기 위해, 다음의 최적화 방법을 고려하세요.
- 불필요한 의존성 및 자산을 제거하여 앱 크기를 최소화하세요.
- 이미지 및 기타 미디어 파일을 로딩 시간을 줄이기 위해 최적화하세요.
- 컴포넌트 및 페이지에 대해 지연 로딩을 구현하여 초기 로드 성능을 개선하세요.
- Next.js와 함께 서버 사이드 렌더링 (SSR)을 사용하여 앱의 로딩 속도와 검색 엔진 최적화 (SEO)를 향상하세요.
- Capacitor의 내장 최적화 기능, 예를 들어 웹 뷰 캐싱 및 앱 번들링을 활용하세요.
결론
Capacitor 8을 사용하여 기존의 Next.js 웹 애플리케이션을 iOS 및 Android 앱으로 성공적으로 변환했습니다. Capacitor의 웹 코드베이스는 이제 모바일 기기에서 네이티브로 실행되며, 장치 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 탭바 및 네이티브 크롬
- Capacitor 8 문서
- @capgo/capacitor-transitions — 네이티브 느낌의 페이지 전환
- @capgo/tailwind-capacitor — Capacitor의 안전 영역 유틸리티
- Capgo - Capacitor 앱을 위한 실시간 업데이트
Capgo을 사용하여 더 나은 앱을 더 빠르게 빌드하는 방법을 알아보세요. __CAPGO_KEEP_0__ 무료 계정으로 가입하세요 오늘.
Capacitor 8을 사용하여 Convert Your Next.js App to iOS & Android
__CAPGO_KEEP_0__을 사용 중이라면 Capacitor 8을 사용하여 Convert Your Next.js App to iOS & Android __CAPGO_KEEP_0__을 연결하여 Capgo 플러그인 디렉토리 Capgo 플러그인 디렉토리에서 제품 워크플로우 Capacitor 플러그인들에 의해 Capgo Capacitor 플러그인들에 의해 Capgo의 구현 세부 사항 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부 사항 Ionic Enterprise 플러그인 대체 Ionic Enterprise 플러그인 대체의 제품 워크플로우 Capgo 네이티브 빌드 Capgo 네이티브 빌드의 제품 워크플로우
