소개
기존의 다음.js 웹 애플리케이션이 있나요? 이 안내서에서는 __CAPGO_KEEP_0__ Capacitor __CAPGO_KEEP_0__
Capacitor은 웹 앱을 네이티브 컨테이너에 감싸줍니다. 이로써 카메라, 파일 시스템, 푸시 알림과 같은 장치 API에 접근할 수 있으면서도 기존의 React 코드베이스를 유지할 수 있습니다. React Native와 달리, code을 사용하는 Next.js 앱은 기존대로 유지되며 다시 작성할 필요가 없습니다.
학습할 내용:
- 기존의 Next.js 앱을 정적 내보내기로 구성합니다.
- Capacitor 8에 필수 네이티브 플러그인을 추가하여 Capacitor을 설정합니다.
- iOS 및 Android 시뮬레이터에서 빌드 및 테스트합니다.
- 빠른 개발을 위해 라이브 리로드를 활성화합니다.
- iOS 레이아웃 문제를 해결합니다 (뷰포트, 안전 영역, 수평 방향 오버플로우)
- Capgo Native Navigation과 Transitions를 사용하여 네이티브처럼 느껴지는 UI를 추가합니다.
새로운 프로젝트를 시작하고 싶다면, __CAPGO_KEEP_0__을 사용하는 Next.js 모바일 앱을 만드는 방법에 대한 가이드를 확인하세요. Next.js와 __CAPGO_KEEP_0__을 사용하는 이점.
Capacitor 재사용성
- Code은 웹 앱을 네이티브 컨테이너에 감싸줍니다. 이로써 카메라, 파일 시스템, 푸시 알림과 같은 장치 API에 접근할 수 있으면서도 기존의 React 코드베이스를 유지할 수 있습니다. React Native와 달리, __CAPGO_KEEP_1__을 사용하는 Next.js 앱은 기존대로 유지되며 다시 작성할 필요가 없습니다.: Next.js는 웹과 모바일 앱 간에 재사용 가능한 컴포넌트를 작성하고 code를 공유할 수 있으므로 개발 시간과 노력을 절약할 수 있습니다.
- 성능: Next.js는 서버 사이드 렌더링 및 code 분할과 같은 내장 성능 최적화를 제공하여 빠른 로딩 시간과 smooth한 사용자 경험을 보장합니다.
- 자연스러운 Native 기능: Capacitor는 카메라, 위치 정보, 및 더 많은 기능을 제공하여 기능이 풍부한 모바일 앱을 빌드할 수 있습니다.
- 간소화된 개발: Capacitor를 사용하면 웹 기술을 익숙한 개발 환경에서 개발하고 테스트할 수 있으며 학습 곡선이 줄어들고 개발 프로세스가 단순화됩니다.
사전 조건
시작하기 전에 다음을 확인하세요.
- Node.js 18+ 설치
- 기존의 Next.js 15+ 애플리케이션
- Xcode (iOS 개발을 위해 macOS만)
- Android Studio (Android 개발을 위해)
모바일을 위한 Next.js 앱 설정
Next.js 앱을 모바일로 설정하는 첫 번째 단계는 정적 내보내기 설정을 구성하는 것입니다. Capacitor는 정적 HTML/JS/CSS 파일을 네이티브 앱으로 패키징하기 위해 필요합니다.
파일을 열고 내보내기 설정을 추가하세요: next.config.js The next.config.ts(또는
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
images: {
unoptimized: true,
},
};
module.exports = nextConfig;) output: 'export' __CAPGO_KEEP_0__를 사용하여 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정적 내보내기 결과를 확인할 수 있습니다. out 프로젝트의 루트 폴더에 있는 폴더입니다. 이 폴더에는 Capacitor가 네이티브 앱에 포함할 정적 파일이 모두 포함되어 있습니다.
Adding Capacitor 8 to Your Project
Next.js 앱을 네이티브 모바일 컨테이너로 패키징하려면 다음 단계를 따르세요.
- Install Capacitor core and 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__CAPGO_KEEP_0__을 앱 이름으로 대체합니다 my-app __CAPGO_KEEP_0__을 앱 이름으로 대체합니다 com.example.myapp __CAPGO_KEEP_0__를 사용하여 앱 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 To build the Android project, you need android Android Studio
. For iOS, you need a Mac with Xcode. For iOS, you need a Mac with Xcode. __CAPGO_KEEP_0__ will create and folders at the root of your project containing the native projects..
- 프로젝트를 빌드하고 동기화하세요:
bun run mobileNext.js 프로젝트를 빌드하고 네이티브 플랫폼과 정적 파일을 동기화하는 커스텀 스크립트를 실행합니다.
네이티브 앱 빌드 및 배포
네이티브 모바일 앱을 빌드 및 배포하려면 다음 단계를 따르세요: iOS 앱을 개발하려면 Xcode 를 설치해야 하며, Android 앱을 개발하려면 Android Studio 를 설치해야 합니다. 또한 앱 스토어에서 앱을 배포하려면 iOS에서는 Apple Developer Program에 등록하고 Android에서는 Google Play Console에 등록해야 합니다.
- 네이티브 프로젝트를 열세요:
iOS:
bun run mobile:iosAndroid:
bun run mobile:android또는 직접 Capacitor CLI:
bunx cap open ios
bunx cap open android- 앱을 빌드하고 실행하세요:
-
Android Studio에서 프로젝트가 준비되기를 기다리십시오. 그런 다음 연결된 장치나 에뮬레이터에 앱을 배포하기 위해 "Run" 버튼을 클릭하십시오.
-
Xcode에서 실제 장치에 앱을 배포하기 위해 서명 계정을 설정하십시오. 이 작업을 처음하는 경우 Xcode는 Apple Developer Program에 가입한 경우에만 프로세스를 안내하십시오. 설정이 완료되면 "Play" 버튼을 클릭하여 연결된 장치에서 앱을 실행하십시오.
Next.js 웹 앱을 성공적으로 모바일 장치에 배포했습니다.
Capacitor Live Reload
개발 중에는 즉시 모바일 장치에서 변경 사항을 볼 수 있는 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는 copy 명령어는 웹 폴더와 구성 변경 사항을 native 프로젝트로 복사하고 전체 프로젝트를 업데이트하지 않습니다.
- Android Studio 또는 Xcode를 사용하여 기기에서 앱을 다시 빌드하고 실행하세요.
Next.js 앱에 변경 사항을 만들면 모바일 앱이 자동으로 다시 로드되어 변경 사항을 반영합니다.
주의: 새로운 플러그인을 설치하거나 native 파일을 변경하면 live reloading이 웹 code 변경 사항만 적용되므로 native 프로젝트를 다시 빌드해야 합니다.
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__ 플러그인은 앱을 다시 빌드하지 않고 동기화만 하면 됩니다.
여러 년 동안 Ionic 을 사용하여 크로스 플랫폼 애플리케이션을 개발해 왔습니다. 하지만 Next.js와 통합하는 것은 복잡하고, 이미 Tailwind CSS 4를 사용하고 있다면 가치가 없습니다. Next.js + __CAPGO_KEEP_0__ 앱에서 원시적인 모바일 느낌을 얻으려면, __CAPGO_KEEP_1__ 플러그인을 사용하는 것이 좋습니다. 웹 전용 UI 키트인 Konsta UI와 같은 것보다는:.
@Capacitor/Capgo-native-navigation
- @capgo/capacitor-native-navigation @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions
- @capgo/capacitor-transitions 두 개 모두 설치하세요.
__CAPGO_KEEP_0__
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',
},
});리퀴드 글라스 탭 바를 렌더링하세요 (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(),
, Using @capgo/capacitor-native-navigation __CAPGO_KEEP_0__ capgo와 capacitor를 사용하여.
Tailwind에서 안전한 영역
Tailwind CSS에서 장치 안전 영역을 사용하려면 capgo와 tailwind-capacitor __CAPGO_KEEP_0__에서 tailwind-capacitor npm에서 safe-areas Capacitor-친화적인 Tailwind 플러그인
bun add -D tailwind-capacitor__CAPGO_KEEP_0__ styles/globals.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";__CAPGO_KEEP_0__와 같은 유용한 기능을 사용하십시오. pt-safe, pb-safe__CAPGO_KEEP_0__와 px-safe __CAPGO_KEEP_0__ env(safe-area-inset-*) __CAPGO_KEEP_0__에서 PR을 열어주세요. open a PR on GitHub.
App Router에서 export합니다.
from Pages Router overflow-x: hidden viewport meta 태그를
not __CAPGO_KEEP_0__에서
iOS 레이아웃 문제를 해결하는 방법 (뷰포트, 안전 영역, 가로 스크롤) (app/iOS에서 콘텐츠가 잘린 것처럼 보이거나 shift되어 보이거나 가로 스크롤이 가능하다면, 더 많은 내용을 추가하거나 뷰포트 태그를 조정하는 것만으로는 해결되지 않습니다. 이 체크를 순서대로 진행하세요. viewport iOS에서 콘텐츠가 잘린 것처럼 보이거나 shift되어 보이거나 가로 스크롤이 가능하다면, 뷰포트 태그를 올바르게 적용하는지 확인하세요. 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 pt-safe pb-safe px-safe 를 설정하세요.
Set Capacitor iOS contentInset 로 never 첫 번째
In capacitor.config.ts, native inset을 비활성화하고 CSS (또는 Native Navigation의 )가 safe area를 관리하도록 하세요. contentInsetMode: 'css'Tailwind CSS와 __CAPGO_KEEP_0__의 자동 콘텐츠 inset을 혼합하는 것은 일반적인 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 CSS, 고정 픽셀 너비, 또는 큰
Safari Web Inspector에서 실행하세요:
Tailwind CSS의 경우 100vwTailwind CSS를 사용하여 w-screen를 대체하세요. 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 가능한 경우에 100vw / w-screen가로 방향으로의 오버플로우 문제는
, 중복된 안전 영역 패딩 또는 고정 너비 컨테이너에서 오는 것이 아니라, viewport meta 태그 자체에서 오는 것이 아니다.
To ensure optimal performance of your Next.js and Capacitor app, consider the following best practices:
- __CAPGO_KEEP_0__와 함께 최적의 성능을 보장하기 위해, 다음의 최적화 방법을 고려하십시오:
- __CAPGO_KEEP_0__의 크기를 최소화하기 위해 사용하지 않는 의존성과 자산을 제거하십시오.
- 이미지 및 기타 미디어 파일을 로딩 시간을 줄이기 위해 최적화하십시오.
- 컴포넌트 및 페이지를 초기 로딩 성능을 개선하기 위해 지연 로딩을 구현하십시오.
- Leverage Capacitor’s built-in optimizations, such as web view caching and app bundling.
__CAPGO_KEEP_0__의 내장 최적화 기능을 활용하십시오. 예를 들어, 웹 뷰 캐싱 및 앱 번들링을 사용하십시오.
You’ve successfully converted your existing Next.js web application into native iOS and Android apps using Capacitor 8. Your web codebase now runs natively on mobile devices with access to device APIs.
__CAPGO_KEEP_0__
- Next.js를 정적 내보내기 위해 구성했습니다.
- Capacitor 8에 필수 플러그인을 추가했습니다.
- iOS 및 Android 시뮬레이터에 빌드 및 배포했습니다.
- 개발을 위해 라이브 리로드를 활성화했습니다.
- 일반 iOS 레이아웃 문제를 해결했습니다 (뷰포트, 안전 영역, 오버플로우)
- Capgo Native Navigation 및 Transitions를 사용하여 네이티브 느낌의 UI를 추가했습니다.
다음 단계:
- 설정 Capgo 앱 스토어 재제출 없이 오버 더 에어 업데이트를 위해 설정했습니다.
- 카메라, 위치 정보, 또는 푸시 알림과 같은 더 많은 네이티브 플러그인을 추가하세요.
- __CAPGO_KEEP_0__ 및 __CAPGO_KEEP_1__ 아이콘 및 스플래시 화면을 프로덕션에 맞게 구성하세요.
- __CAPGO_KEEP_0__ 앱을 App Store 및 Google Play 제출 준비하세요.
새로운 프로젝트를 시작하고 싶으세요? __CAPGO_KEEP_0__ Next.js 모바일 앱을 처음부터 시작하는 방법 __CAPGO_KEEP_0__ 가이드된_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을 사용하여 다음.js 앱을 iOS & Android로 변환하세요.
__CAPGO_KEEP_0__을 사용 중이라면 Capacitor 8을 사용하여 네이티브 플러그인 작업을 계획하세요. __CAPGO_KEEP_0__ 플러그인 디렉토리와 연결하세요. Capgo 플러그인 디렉토리에서 제품 워크플로우를 확인하세요. Capgo 8을 사용하여 다음.js 앱을 iOS & Android로 변환하세요. Capacitor 플러그인들에 의해 Capgo Capacitor 플러그인들에 의해 Capgo의 구현 세부 정보에 대해 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부 정보에 대해 아이오닉 엔터프라이즈 플러그인 대체 아이오닉 엔터프라이즈 플러그인 대체의 제품 워크플로에 대해, 그리고 Capgo 네이티브 빌드 Capgo 네이티브 빌드의 제품 워크플로에 대해.
