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

소개

Next.js 웹 애플리케이션이 이미 존재하는 경우? 이 안내서에서는 iOS 및 Android 모바일 앱으로 변환하는 방법을 배울 것입니다. Capacitor 8 — 성능이 향상되고 새로운 기능이 추가된 최신 버전입니다.

Capacitor는 웹 앱을 네이티브 컨테이너에.wrap하여 기기 API (카메라, 파일 시스템, 푸시 알림 등) 접근을 제공하면서 기존 React 코드베이스를 유지합니다. React Native와 달리, 다시 작성할 필요가 없습니다. — Next.js code는 그대로 작동합니다.

학습할 내용:

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

새로운 프로젝트를 시작하려면? __CAPGO_KEEP_0__ 가이드를 확인하세요. __CAPGO_KEEP_1__에서 Native 모바일 앱을 빌드하는 방법.

Capacitor의 이점

Code 재사용: code를 사용하면 웹 앱과 모바일 앱 간에 재사용 가능한 컴포넌트를 작성하고 code를 공유할 수 있어 개발 시간과 노력을 절약할 수 있습니다.
성능: Next.js offers built-in performance optimizations, such as server-side rendering and code splitting, ensuring fast loading times and a smooth user experience.
: __CAPGO_KEEP_0__는 서버 사이드 렌더링 및 __CAPGO_KEEP_0__ 스플리팅과 같은 내장 성능 최적화 기능을 제공하여 빠른 로딩 시간과 smooth한 사용자 경험을 보장합니다.: Capacitor provides access to native device features like the camera, geolocation, and more, allowing you to build feature-rich mobile apps.
: __CAPGO_KEEP_0__는 카메라, 위치 정보, 등 네이티브 디바이스 기능에 접근할 수 있어 기능-rich한 모바일 앱을 빌드할 수 있습니다.: With Capacitor, you can develop and test your mobile app using familiar web technologies, reducing the learning curve and streamlining the development process.

: __CAPGO_KEEP_0__를 사용하면 familiar한 웹 기술을 사용하여 모바일 앱을 개발하고 테스트할 수 있어 학습 곡선이 줄어들고 개발 프로세스가 단순화됩니다.

시작하기 전에 다음을 확인하세요:

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

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

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

모바일 앱을 Native로 빌드하는 방법 next.config.js (또는 next.config.ts) 파일을 열고 export 설정을 추가하세요:

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

module.exports = nextConfig;

Next.js에서 output: 'export' Next.js에서 정적 HTML 파일을 생성하고 서버를 필요로 하는 Next.js 이미지 최적화를 우회합니다. images: { unoptimized: true } 중요:

서버가 필요한 기능(__CAPGO_KEEP_0__ 라우트, 데이터 페칭을 하는 서버 컴포넌트 등)을 사용 중이라면, 클라이언트 측 대체 또는 외부 API를 사용하여 리팩토링해야 합니다. 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.

정적 export를 테스트하려면: 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"
  }
}

Native 앱에 포함될 정적 파일이 포함된 폴더가 프로젝트의 루트에 생성되어야 합니다.

bun run build

__CAPGO_KEEP_0__ out Capacitor

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

다음 단계를 따라 네트克斯 .JS 앱을 네이티브 모바일 컨테이너로 패키지화하세요.

Capacitor 코어 및 CLI을 설치하세요.

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

Capacitor 플러그인을 설치하세요. 이 플러그인은 일반적으로 필요합니다.

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

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

@capacitor/앱: 앱 라이프 사이클 이벤트 (전경/배경, URL)를 처리합니다.
@capacitor/키보드: 모바일 키보드 동작을 제어합니다.
@capacitor/스플래시 스크린: 네이티브 스크린을 관리합니다.
@capacitor/설정: 데이터 저장소 키-값 데이터 지속적으로

프로젝트 세부 정보와 함께 Capacitor을 초기화하세요:

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

바꾸기 my-app 앱 이름과 com.example.myapp 앱 ID (역 도메인 표기법)와

정상적인 구성으로 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 android

Capacitor은 ios 프로젝트의 루트 폴더에 자연스러운 프로젝트 폴더를 생성합니다. android 폴더

Android 프로젝트를 만들려면 __CAPGO_KEEP_0__가 필요합니다. Android Studio. iOS의 경우 Mac에 Xcode.

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

bun run mobile

이것은 Next.js 프로젝트를 빌드하고 정적 파일을 네이티브 플랫폼과 동기화하는 커스텀 스크립트를 실행합니다.

네이티브 앱 빌드 및 배포

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

모바일 앱을 위한 네이티브 프로젝트를 열어주세요:

iOS용:

bun run mobile:ios

Android용:

bun run mobile:android

또는 Capacitor CLI으로 직접:

bunx cap open ios
bunx cap open android

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

android-studio-run

안드로이드 스튜디오에서 프로젝트가 준비될 때까지 기다리세요. 그런 다음 연결된 장치나 에뮬레이터에 앱을 배포하기 위해 "실행" 버튼을 클릭하세요.
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).

개발 프로젝트에 변경 사항을 적용하세요:

bunx cap copy

__CAPGO_KEEP_0__ copy 명령어는 웹 폴더와 구성 변경 사항을 네이티브 프로젝트로 복사하고 전체 프로젝트를 업데이트하지 않습니다.

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

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

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 플러그인을 사용하기 위해 파일을 업데이트하세요.

변경 사항을 네이티브 프로젝트와 동기화하세요.

bun add @capacitor/share

__CAPGO_KEEP_0__ 플러그인을 사용하여 네이티브 장치 기능에 접근할 수 있습니다. 예를 들어 Share 플러그인을 사용해 보겠습니다. pages/index.js Share 플러그인을 설치하세요.

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>
  );
}

Share 플러그인을 사용하기 위해 파일을 업데이트하세요.

이전에서 언급한 것처럼 새로운 플러그인을 설치할 때는 sync 연산을 수행하고 앱을 다시 장치에 배포해야 합니다. 이를 수행하려면 다음 명령어를 실행하세요:

bun run mobile

혹은 다시 빌드하지 않고만 sync를 수행하세요:

bunx cap sync

앱을 장치에 다시 배포하세요.

‘Share now!’ 버튼을 클릭하면 네이티브 공유 대화상자가 나타나, 다른 앱과 콘텐츠를 공유할 수 있습니다.

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. ## Native-feeling UI with Capgo Native Navigation and Transitions

## 네이티브 UI를 위한 __CAPGO_KEEP_1__ 네이티브 네비게이션 및 전환 여러 해 동안 Ionic 을 사용하여 크로스 플랫폼 앱을 개발해 왔습니다. .

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 native navbar, Liquid Glass tab bar on iOS, and a blurred tab bar style on Android. Your Next.js router keeps route state; the plugin owns the native chrome.
@capgo/capacitor-transitions Ionic-style page transitions and iOS edge swipe-back in the WebView layer, without adopting Ionic UI.

설치 BOTH:

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

자연스러운 네비게이션을 위해 native navigation을 CSS inset mode로 구성하십시오. 웹 콘텐츠는 native bars를 존중하십시오:

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}`);
});

native page transitions을 앱 셸에 추가하십시오:

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

initTransitions({ platform: 'auto' });

Wrap routed pages in cap-router-outlet, cap-pageand cap-contentor call setDirection('forward') 또는 setDirection('back') 앱플로우와 Capawesome을 비교하기 전에, 이슈를 먼저 생성하고 논의하십시오. 새로운 기능에 대한 작업을 시작하기 전에, 이슈를 먼저 생성하고 논의하십시오. router.push() 또는 router.back()다른 헤더나 푸터를 중복하지 마세요.

자세한 설명서를 참조하세요: @capgo/capacitor-native-navigation 사용하기 또는 @capgo/capacitor-transitions 사용하기.

안전 영역에 Tailwind 사용하기

Tailwind CSS에서 디바이스 안전 영역을 사용하려면 @capgo/tailwind-capacitor (__CAPGO_KEEP_0__에서 출판) tailwind-capacitor 다음 npm-친화적인 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";

사용할 수 있는 유틸리티 pt-safe, pb-safe, px-safe 대신 수동으로 env(safe-area-inset-*) 을 사용하세요. 프로젝트는 활발히 개발 중이며, Next.js 설정에 필요한 것이 빠진 경우 GitHub.

에 PR을 열어보세요.

iOS 레이아웃 문제 해결 (뷰포트, 안전 영역, 가로 스크롤) overflow-x: hidden iOS에서 콘텐츠가 잘려나거나-shifted되거나 가로 스크롤이 가능하다면,

또는

뷰포트 태그만 조정하는 것만으로는 해결되지 않습니다. 이러한 체크를 순서대로 진행하세요. (app/뷰포트 메타 태그가 올바르게 적용되었는지 확인하세요. viewport from app/layout.tsx:

import type { Viewport } from 'next';

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

Pages Router (pages/viewport meta 태그를 넣어야 합니다. pages/_app.tsx아니 _document.tsx Next.js는 viewport 동작에 대한 태그를 기대하는 방식과 다르게 태그를 적용할 수 있습니다. _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);
}

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

@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitorNative 모바일 앱을 구축하는 방법에 대해 알아보세요. pt-safe pb-safe px-safe 단일 셸에서 사용할 수 있는 패딩을 표현할 수 있습니다.

Set Capacitor iOS `contentInset` 첫 번째 `never` 페이지에

CSS (또는 Native Navigation의) capacitor.config.tsCSS의 패딩과 __CAPGO_KEEP_0__의 자동 콘텐츠 인셋을 혼합하는 것은 일반적인 오버플로우 원인입니다. contentInsetMode: 'css'실제로 오버플로우가 발생하는 요소를 찾습니다.

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-*) __CAPGO_KEEP_0__의 요소를 사용하는 요소입니다.

__CAPGO_KEEP_0__ iOS

Live Update의 동적 레이블을 설정합니다. 100vw, Tailwind w-screen, 고정픽셀 너비 또는 대형 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 앱의 최적 성능을 보장하기 위해 다음의最佳 관행을 고려하십시오:

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

결론

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

완료한 일들:

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

다음 단계:

설정 Capgo Capacitor와 Next.js를 사용하여 네이티브 모바일 앱을 빌드하는 방법
앱 스토어 재제출 없이 오버 더 에어 업데이트
카메라, 위치 정보, 푸시 알림과 같은 네이티브 플러그인을 더 추가하세요
제품용 앱 아이콘과 스플래시 화면을 구성하세요

앱 스토어와 구글 플레이 제출을 위해 앱을 준비하세요 새로운 프로젝트를 시작하고 싶으세요? Next.js 모바일 앱을 처음부터 구축하는 방법

가이드된_walkthrough를 확인하세요.

자원
@capgo/capacitor-native-navigation --- Liquid Glass 탭바와 네이티브 크롬
Capacitor 8 문서
@capgo/capacitor-transitions --- 네이티브한 느낌의 페이지 전환
@capgo/tailwind-capacitor --- Tailwind safe-area 유틸리티를 위한 Capacitor
Capgo - Live Updates for Capacitor 앱

Capgo을 사용하여 더 나은 앱을 더 빠르게 빌드하는 방법을 배워보세요. __CAPGO_KEEP_0__에 가입하세요. 오늘부터.

Convert Your Next.js App to iOS & Android with Capacitor 8

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

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

소개