시작하기

빠른 시작

bun add @capgo/capacitor-plus
npx cap sync

자주 하는 실수

• 모든 @capacitor/* 의존성을 교체하세요.
• 마이그레이션 후 native 프로젝트를 재생성하세요.
• 버전을 올리기 전에 릴리스 노트를 확인하세요.

새 프로젝트 설치

AI 지원 설정으로 Capacitor+를 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

그런 다음 아래 프롬프트를 사용하세요:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capacitor-plus/core`, `@capacitor-plus/cli`, `@capacitor-plus/android`, and `@capacitor-plus/ios` packages in my project.

수동 설정을 원하면 다음 명령어를 실행해 패키지를 설치한 뒤, 아래 플랫폼별 지침을 따르세요:

1. 코어 패키지 설치

   npm install @capacitor-plus/core @capacitor-plus/cli

2. 플랫폼 패키지 추가

   npm install @capacitor-plus/android  # for Android
   npm install @capacitor-plus/ios      # for iOS

3. Capacitor 초기화

   npm

   npx cap init

   pnpm

   pnpm cap init

   yarn

   yarn cap init

   bun

   bunx cap init

4. 플랫폼 추가

   npm

   npx cap add android

   pnpm

   pnpm cap add android

   yarn

   yarn cap add android

   bun

   bunx cap add android

   npm

   npx cap add ios

   pnpm

   pnpm cap add ios

   yarn

   yarn cap add ios

   bun

   bunx cap add ios

공식 Capacitor에서 마이그레이션하기

기존 Capacitor 프로젝트를 사용 중이라면, Capacitor+로의 마이그레이션은 매우 간단합니다:

1. 공식 패키지 제거

   npm uninstall @capacitor/core @capacitor/cli @capacitor/android @capacitor/ios

2. Capacitor+ 패키지 설치

   npm install @capacitor-plus/core @capacitor-plus/cli
   npm install @capacitor-plus/android  # if using Android
   npm install @capacitor-plus/ios      # if using iOS

3. 프로젝트 동기화

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

참고

code 변경 사항이 필요 없습니다! Capacitor+는 공식 Capacitor와 동일한 API를 제공합니다. 기존의 import 및 code를 그대로 유지할 수 있습니다.

사용량

API 호환성을 지원하는 Capacitor+ 덕분에, 기존 code를 수정 없이 그대로 사용할 수 있습니다:

import { Capacitor } from '@capacitor/core';
import { registerPlugin } from '@capacitor/core';

// Check platform
const platform = Capacitor.getPlatform();
console.log('Running on:', platform);

// Check if native
if (Capacitor.isNativePlatform()) {
  console.log('Running on native platform');
}

// Register a custom plugin
const MyPlugin = registerPlugin('MyPlugin');

공식 Capacitor 플러그인 사용 시

모든 공식 Capacitor 플러그인은 완벽하게 작동합니다:

import { Camera, CameraResultType } from '@capacitor/camera';
import { Geolocation } from '@capacitor/geolocation';
import { Storage } from '@capacitor/preferences';

// Camera
const photo = await Camera.getPhoto({
  quality: 90,
  resultType: CameraResultType.Uri
});

// Geolocation
const position = await Geolocation.getCurrentPosition();

// Storage
await Storage.set({ key: 'name', value: 'John' });

Capgo 플러그인 사용

Capgo 플러그인은 Capacitor+와 완벽하게 호환됩니다:

import { CapacitorUpdater } from '@capgo/capacitor-updater';
import { ScreenOrientation } from '@capgo/capacitor-screen-orientation';
import { CapacitorFlash } from '@capgo/capacitor-flash';

// Live updates
await CapacitorUpdater.notifyAppReady();

// Screen orientation
await ScreenOrientation.lock({ orientation: 'portrait' });

// Flashlight
await CapacitorFlash.toggle();

동기화 방식

┌─────────────────────┐     ┌──────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  ionic-team/        │     │  CI/CD           │     │  Claude Code     │     │  npm publish    │
│  capacitor          │────▶│  Pipeline        │────▶│  Security Review │────▶│  @capacitor-plus│
│  (upstream)         │     │  (daily sync)    │     │  (AI analysis)   │     │  packages       │
└─────────────────────┘     └──────────────────┘     └──────────────────┘     └─────────────────┘

1. 일일 동기화: GitHub Actions가 다음에서 최신 변경 사항을 가져옵니다 ionic-team/capacitor
2. PR 생성: 변경 사항이 다음 브랜치로 pull request됩니다: plus branch
3. CI 검증: 전체 테스트 스위트 실행 (lint, unit tests, iOS build, Android build)
4. 보안 리뷰: AI 기반 분석을 통해 취약점 및 breaking changes 확인
5. 자동 머지: CI 통과 및 보안 리뷰 승인 시에만 실행
6. 자동 배포: npm에 새 버전이 배포됩니다: @capacitor-plus/*

보안 리뷰 상세 정보

모든 업스트림 동기화 시 다음 항목을 분석합니다:

체크 항목	탐지 내용
보안	커맨드 인젝션, XSS, path traversal, 하드코딩된 시크릿
주요 변경 사항	제거/이름 변경된 API, 시그니처 변경, 설정 변경
안정성	널 역참조, 처리되지 않은 예외, 레이스 컨디션, 메모리 누수
데이터 안전성	데이터 손실 시나리오, 개인정보 침해, 보안에 취약한 저장소
Code 무결성	난독화된 code, 의심스러운 네트워크 호출, 백도어

주의

문제가 감지되면 PR은 수동 검토 대상으로 플래그가 지정되며 자동 머지되지 않습니다. 이를 통해 항상 안정적이고 안전한 릴리스를 보장합니다.

PR 제출하기

공식 Capacitor 레포지토리에서 PR이 멈춰 있나요? Capacitor+에서 바로 머지하세요:

1. Issue 생성 플러그인의 Capacitor+ 레포지토리 업스트림 PR 링크 연결

2. 직접 제출하기 해당 브랜치로 plus PR을 보내주세요

3. 팀에서 검토 및 CI를 실행하며, 통과 시 머지합니다.

이렇게 하면 업스트림 릴리스 주기를 기다리지 않고도 본인의 작업물을 즉시 활용할 수 있습니다.

자주 묻는 질문

실제 서비스에 사용해도 되나요?

네. Capacitor+는 실제 서비스 중인 앱에서 사용되고 있습니다. 모든 릴리스는 공식 Capacitor와 동일한 테스트 스위트를 통과하며, 추가적인 보안 분석도 거칩니다.

기존 공식 플러그인도 계속 작동하나요?

네, 모두 가능합니다. @capacitor/* 모든 플러그인은 Capacitor+와 즉시 호환됩니다.

업스트림에서 breaking change가 발생하면 어떻게 되나요?

AI 보안 리뷰가 breaking change를 감지하여 수동 검토 대상으로 분류합니다. 변경 사항이 머지되기 전에 문서화된 내용을 확인할 수 있습니다.

이슈는 어떻게 보고하나요?

다음 저장소에 이슈를 등록해 주세요: Capacitor+ GitHub 리포지토리공식 Capacitor에도 영향을 미치는 이슈의 경우, 업스트림과의 조율을 도와드립니다.

기여할 수 있나요?

물론입니다! PR은 언제나 환영합니다. 직접 수정을 제출하시거나 특정 upstream PR의 머지를 요청하실 수 있습니다.

시작하기 다음 단계

사용 중이라면 시작하기 네이티브 플러그인 작업을 계획하려면, 이를 다음 항목과 연결하세요: Capacitor+ (@capacitor-plus) 패키지 사용하기 Capacitor+ (@capacitor-plus) 패키지 사용 시 네이티브 기능에 대해서는, Capgo 플러그인 디렉토리 Capgo Plugin Directory의 제품 워크플로우에 맞춰, Capgo의 Capacitor 플러그인 Capgo의 Capacitor 플러그인 구현 상세 내용에 대해서는, 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트 구현 상세 내용에 대해서는, Ionic Enterprise 플러그인 대안 Ionic Enterprise 플러그인 대안의 제품 워크플로우에 대해서는.