Nuxt 앱을 iOS & Android로 변환하는 방법: Capacitor 8

Introduction

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

Capacitor는 웹 앱을 네이티브 컨테이너에 감싸줌으로써 기존 Vue 코드베이스를 유지하면서 카메라, 파일 시스템, 푸시 알림과 같은 장치 API에 접근할 수 있게 해줍니다. Flutter나 React Native와 달리, 다시 작성할 필요가 없습니다 — Nuxt code는 그대로 작동합니다.

학습할 내용:

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

새로운 프로젝트를 시작하려면? Nuxt 모바일 앱을 처음부터 시작하는 방법.

Capacitor를 사용하는 이점

• Code 재사용성: 웹과 모바일 앱 간에 Vue 컴포넌트 및 논리를 공유하세요.
• 성능: Nuxt의 정적 생성은 모바일용 최적화된 번들을 생성합니다.
• 자연스러운 기능: Capacitor 플러그인을 통해 카메라, 위치 정보, 파일 시스템과 같은 장치 기능에 접근하세요.
• 간소화된 개발:熟悉한 Vue/Nuxt 패턴을 사용하여 네이티브 개발을 배워야 할 필요가 없습니다.

사전 요구 사항

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

• Node.js 18 이상이 설치되어야 합니다. 설치
• 기존 Nuxt 4 애플리케이션 Xcode
• (iOS 개발을 위해 macOS만 지원합니다.) Android Studio
• (Android 개발을 위해) 모바일을 위한 Nuxt 앱 구성

Nuxt 앱을 정적 생성으로 구성하는 첫 단계입니다. __CAPGO_KEEP_0__는 정적 HTML/JS/CSS 파일을 네이티브 앱으로 패키징하기 위해 필요합니다.

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

정확히 하려면 package.json __CAPGO_KEEP_0__에 generate 스크립트가 있어야 합니다:

{
  "scripts": {
    "dev": "nuxt dev",
    "build": "nuxt build",
    "generate": "nuxt generate",
    "preview": "nuxt preview",
    "mobile": "bun run generate && bunx cap sync",
    "mobile:ios": "bun run mobile && bunx cap open ios",
    "mobile:android": "bun run mobile && bunx cap open android"
  }
}

중요: 서버 사이드 기능(API 루트, 서버 미들웨어 등)을 사용 중이라면, 클라이언트 사이드 대안 또는 외부 API를 사용하여 리팩토링해야 합니다.

__CAPGO_KEEP_0__의 정적 생성을 테스트하려면 다음 명령어를 실행하세요:

bun run generate

__CAPGO_KEEP_0__를 실행하면 .output/public Capacitor 폴더에 정적 파일이 있습니다. 이 폴더는 Capacitor가 네이티브 앱에 패키징할 것입니다.

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

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

1. Capacitor 코어와 CLI을 설치하세요:

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

2. Capacitor의 일반적인 플러그인을 설치하세요. 사용할 것 같은 플러그인을 설치하세요:

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

이 플러그인은 필수적인 기능을 제공합니다:

• @capacitor/app앱 생명주기 이벤트를 처리합니다 (전면/후면, 깊은 링크)
• @capacitor/keyboard모바일 키보드 동작을 제어합니다
• @capacitor/splash-screen자연스러운 스플래시 화면을 관리합니다
• @capacitor/status-bar디바이스 상태바 스타일을 관리합니다
• @capacitor/preferences키-값 스토리지 (localStorage와 유사하지만 네이티브)

3. Capacitor을 프로젝트 세부 정보와 초기화하세요.

bunx cap init my-app com.example.myapp --web-dir .output/public

__CAPGO_KEEP_0__을 교체하세요. my-app __CAPGO_KEEP_0__ com.example.myapp 앱 이름과

4. 앱 ID (역 도메인 표기법). capacitor.config.ts 프로젝트 루트에 native 프로젝트가 포함된 폴더를 생성합니다.

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

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: '.output/public',
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      androidScaleType: 'CENTER_CROP',
      splashFullScreen: true,
      splashImmersive: true,
    },
    Keyboard: {
      resize: 'body',
      resizeOnFullScreen: true,
    },
    StatusBar: {
      style: 'dark',
    },
  },
};

export default config;

5. native 플랫폼을 설치합니다.

bun add @capacitor/ios @capacitor/android

6. native 플랫폼 폴더를 추가합니다.

bunx cap add ios
bunx cap add android

Capacitor will create ios 그리고 android native 플랫폼 폴더를 프로젝트 루트에 생성합니다.

Android 프로젝트를 빌드하려면 Android Studio가 필요합니다. iOS를 위해 Mac이 필요합니다.. For iOS, you need a Mac with Xcode.

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

bun run mobile

__CAPGO_KEEP_0__이 실행되며 정적 Nuxt 빌드를 생성하고 네이티브 플랫폼과 파일을 동기화합니다.

네이티브 앱 빌드 및 배포

네이티브 모바일 앱을 빌드 및 배포하려면 다음 단계를 따르세요:

iOS 앱을 개발하려면 Xcode가 설치되어야 하며 Android 앱을 개발하려면 Android Studio가 설치되어야 합니다. 또한 앱 스토어에 앱을 배포하려면 iOS에서는 Apple Developer Program에 등록하고 Android에서는 Google Play Console에 등록해야 합니다. 네이티브 프로젝트 열기: iOS의 경우: Android의 경우: Xcode

1. Android Studio

For Android:

bun run mobile:ios

For Android:

bun run mobile:android

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

bunx cap open ios
bunx cap open android

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

• 안드로이드 스튜디오에서 프로젝트가 준비되면 'Run' 버튼을 클릭하여 연결된 기기나 에뮬레이터에 앱을 배포하세요.

• Xcode에서 실제 기기에 앱을 배포하려면 서명 계정을 설정하세요. 이 과정을 처음으로 진행하는 경우 Xcode는 Apple Developer Program에 가입한 경우에만 앱을 배포할 수 있도록 안내합니다. 설정이 완료되면 'Play' 버튼을 클릭하여 연결된 기기에서 앱을 실행하세요.

성공했습니다! Nuxt 웹 앱을 모바일 기기에 성공적으로 배포했습니다.

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

Capacitor Live Reload

개발 중에는 즉시 변경 사항을 모바일 기기에서 확인할 수 있는 Live Reload 기능을 사용할 수 있습니다. 이 기능을 활성화하려면 다음 단계를 따르세요:

1. __CAPGO_KEEP_0__ 주소 찾기:

• __CAPGO_KEEP_1__ 터미널에서 다음 명령어를 실행하세요:

  ipconfig getifaddr en0

• __CAPGO_KEEP_2__:

  ipconfig

  __CAPGO_KEEP_3__에서 IPv4 주소를 찾으세요.

2. __CAPGO_KEEP_4__를 업데이트 하세요: capacitor.config.ts __CAPGO_KEEP_5__를 __CAPGO_KEEP_6__ (예: __CAPGO_KEEP_7__)로 대체하세요.

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

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

export default config;

__CAPGO_KEEP_8__ 변경 사항을 원시 프로젝트에 적용하세요: YOUR_IP_ADDRESS __CAPGO_KEEP_9__ 명령어는 웹 폴더와 구성 변경 사항을 원시 프로젝트로 복사하지만 전체 프로젝트를 업데이트하지 않습니다. 192.168.1.100).

3. __CAPGO_KEEP_10__를 시작하고 Xcode/Android Studio에서 다시 빌드하세요:

bunx cap copy

__CAPGO_KEEP_11__ 명령어는 __CAPGO_KEEP_12__ 폴더와 구성 변경 사항을 원시 프로젝트로 복사하지만 전체 프로젝트를 업데이트하지 않습니다. copy __CAPGO_KEEP_13__ 명령어는 __CAPGO_KEEP_14__ 폴더와 구성 변경 사항을 원시 프로젝트로 복사하지만 전체 프로젝트를 업데이트하지 않습니다.

4. __CAPGO_KEEP_15__ 명령어는 __CAPGO_KEEP_16__ 폴더와 구성 변경 사항을 원시 프로젝트로 복사하지만 전체 프로젝트를 업데이트하지 않습니다.

bun run dev

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

참고: 새로운 플러그인을 설치하거나 네이티브 파일에 변경 사항이 있으면 네이티브 프로젝트를 다시 빌드해야 합니다. 왜냐하면 라이브 리로딩은 웹 code 변경 사항에만 적용되기 때문입니다.

Capacitor 플러그인 사용

Capacitor 플러그인은 Nuxt 앱에서 네이티브 디바이스 기능에 접근할 수 있도록 해줍니다. 예를 들어 Share 플러그인을 사용해 보겠습니다. Share 플러그인 설치: Share 플러그인을 사용하는 페이지를 만들거나 업데이트 하세요. Nuxt 4에서는 페이지가

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

bun add @capacitor/share

2. 또는 다시 빌드하지 않고 동기화하세요: app/pages/:

<template>
  <div class="p-6">
    <h1 class="text-2xl font-bold mb-4">Welcome to Nuxt + Capacitor!</h1>
    <button
      @click="shareContent"
      class="px-6 py-3 bg-blue-600 text-white rounded-lg font-semibold"
    >
      Share now!
    </button>
  </div>
</template>

<script setup lang="ts">
import { Share } from '@capacitor/share';

async function shareContent() {
  await Share.share({
    title: 'Check this out!',
    text: 'Built with Nuxt and Capacitor',
    url: 'https://capacitorjs.com',
    dialogTitle: 'Share with friends',
  });
}
</script>

3. 앱을 다시 빌드하고 장치에 실행하세요.

bun run mobile

targetLanguage

bunx cap sync

4. protectedTokens

지금, “현재 공유!” 버튼을 클릭하면 원시 공유 대화 상자가 나타납니다.

다음으로, 앱이 iOS 및 Android에서 더 원시적인 느낌을 줄 수 있도록 Capgo 네비게이션 및 전환을 사용하고, 수평 스크롤이나 안전 영역이 잘려지는 iOS 레이아웃 문제를 해결할 수 있습니다.

Capgo 원시 UI와 네이티브 네비게이션 및 전환

__CAPGO_KEEP_1__ 년 동안 Ionic 을 사용하여 크로스 플랫폼 애플리케이션을 개발했지만, Nuxt와 통합하는 것은 복잡하고 거의 가치가 없습니다. 이미 사용 중인 Tailwind CSS.

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

• Nuxt + capgo 앱에서 원시 모바일 느낌을 얻으려면 capacitor 플러그인을 사용하는 것이 좋습니다. 웹 전용 UI 키트인 Konsta UI와 같은 UI 키트 대신. @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation
• @capgo/capacitor-transitions @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions

Install both:

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

앱 셸에서 네이티브 페이지 전환을 추가하십시오.

<script setup>
import { ref, onMounted } from 'vue';
import { useRouter } from 'vue-router';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/vue';

initTransitions({ platform: 'auto' });

const router = useRouter();
const outletRef = ref(null);

onMounted(() => {
  if (outletRef.value) {
    setupRouterOutlet(outletRef.value, { platform: 'auto', swipeGesture: 'auto' });
  }
});

const openSettings = () => {
  setDirection('forward');
  router.push('/settings');
};
</script>

<template>
  <cap-router-outlet ref="outletRef">
    <router-view />
  </cap-router-outlet>
</template>

Wrap routed pages in cap-router-outlet, cap-page, cap-content, setDirection('forward') , setDirection('back') 네이티브 네비게이션이 해당 표면을 소유할 때 웹 헤더나 푸터를 중복하지 마십시오.

자세한 안내서를 참조하십시오: @capgo/capacitor-네이티브-네비게이션 사용하기 and @capgo/capacitor-transitions.

안전 영역에 Tailwind

Tailwind CSS에서 장치 안전 영역을 사용하려면 @capgo/tailwind-capacitor (__CAPGO_KEEP_0__으로 출판됨 tailwind-capacitor npm에서). Tailwind CSS에서 npm-친화적인 유틸리티와 다른 플러그인을 제공합니다. safe-areas utilities and other Capacitor-friendly Tailwind plugins:

bun add -D tailwind-capacitor

Nuxt 4와 Tailwind CSS 4를 사용할 때, CSS 파일에서 이 임포트를 유지하세요. app/assets/css/main.css:

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

Tailwind CSS의 유틸리티를 사용하세요. nuxt.config.ts.

Use utilities such as pt-safe, pb-safe, px-safe instead of sprinkling env(safe-area-inset-*) __CAPGO_KEEP_0__에서 PR을 열어주세요. open a PR on GitHub.

콘텐츠가 iOS에서 잘라진 것처럼 보이거나 shift되어 보이거나 가로 스크롤이 가능하다면

뷰포트 태그를 더 추가하거나 조정하는 것만으로 문제를 해결할 수 없습니다. 다음 순서대로 체크해 보세요. overflow-x: hidden 뷰포트 메타 태그가 올바르게 적용되어 있는지 확인하세요.

뷰포트를

,에 적용하세요. nuxt.config.tsiOS의 안전 영역을 한 개의 루트 wrapper에서만 처리하세요. app.head:

export default defineNuxtConfig({
  app: {
    head: {
      meta: [
        {
          name: 'viewport',
          content: 'width=device-width, initial-scale=1, viewport-fit=cover',
        },
      ],
    },
  },
});

싱글 앱 셸을 생성하고 안전 영역 패딩을 거기에 적용하세요 — 여러 개의 중첩된 컴포넌트에 적용하지 마세요:

모든 페이지 콘텐츠를

html,
body,
#__nuxt {
  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. Duplicated safe-area padding in headers, modals, and layout wrappers often makes the UI look cropped or too large.

__CAPGO_KEEP_0__ @capgo/tailwind-capacitor__CAPGO_KEEP_0__ pt-safe pb-safe px-safe __CAPGO_KEEP_0__

Capacitor contentInset __CAPGO_KEEP_0__ never __CAPGO_KEEP_0__

__CAPGO_KEEP_0__ capacitor.config.ts__CAPGO_KEEP_0__ contentInsetMode: 'css'__CAPGO_KEEP_0__

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

Capacitor env(safe-area-inset-*) __CAPGO_KEEP_0__

__CAPGO_KEEP_0__

__CAPGO_KEEP_1__ 100vw__CAPGO_KEEP_2__ w-screen__CAPGO_KEEP_3__ min-width.

__CAPGO_KEEP_4__

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

__CAPGO_KEEP_5__ w-screen __CAPGO_KEEP_6__ w-full __CAPGO_KEEP_7__ 100vw / w-screen__CAPGO_KEEP_8__

__CAPGO_KEEP_9__

You’ve successfully converted your existing Nuxt web application into native iOS and Android apps using Capacitor 8. Your Vue codebase now runs natively on mobile devices with access to device APIs.

__CAPGO_KEEP_11__

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

다음 단계:

• 설정 Capgo 앱 스토어 재제출 없이 오버 더 에어 업데이트
• 카메라, 위치 정보, 푸시 알림과 같은 더 많은 네이티브 플러그인을 추가하세요.
• 제품용으로 앱 아이콘 및 스플래시 화면을 구성하세요.
• 앱 스토어와 구글 플레이 제출을 위해 앱을 준비하세요.

새로운 프로젝트를 시작하려면 Nuxt 모바일 앱을 처음부터 만들기 가이드된 워크숍을 확인하세요.

자원

• Nuxt 문서
• Capacitor 8 문서
• @capgo/capacitor-native-navigation — Liquid Glass 탭바와 네이티브 크롬
• @capgo/capacitor-transitions — 네이티브 느낌의 페이지 전환
• @capgo/tailwind-capacitor --- Capacitor의 안전 영역 유틸리티
• Capgo - Capacitor 앱을 위한 실시간 업데이트

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

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

__CAPGO_KEEP_0__를 사용 중이라면 Convert Your Nuxt App to iOS & Android with Capacitor 8 __CAPGO_KEEP_0__ 8을 사용하여 native 플러그인 작업을 계획하고 Capgo 플러그인 디렉토리와 연결하세요. Capgo 플러그인 디렉토리에서 제품 워크플로우를 위해 Capacitor 플러그인으로 Capgo Capacitor 플러그인 구현 세부 사항에 대해 Capgo에서 설명합니다. 플러그인 추가 또는 업데이트 __CAPGO_KEEP_0__ 플러그인 추가 또는 업데이트에 대한 구현 세부 사항입니다. 아이온 이코노미컬 엔터프라이즈 플러그인 대안 아이온 이코노미컬 엔터프라이즈 플러그인 대안에 대한 제품 워크플로입니다. Capgo 네이티브 빌드 Capgo 네이티브 빌드에 대한 제품 워크플로입니다.