Capacitor 플러그인은 웹 기술과 네이티브 디바이스 기능을 연결하여 크로스 플랫폼 앱 개발을가능하게 합니다. 이 가이드에서는 다음을 안내합니다:
- 개발 환경 설정: 다음과 같은 도구 Node.js, iOS 프로파일링, 그리고 디버깅하기 가 필수입니다.
- Code 표준을 따르세요: TypeScript, Swift, 그리고 Kotlin 일관된 명명 규칙과 에러 핸들링을 적용하세요.
- 철저한 테스트: 신뢰성을 확보하기 위해 JavaScript, iOS, Android용 유닛 테스트를 작성하세요.
- 명확한 문서화: 사용자가 쉽게 도입할 수 있도록 JSDoc과 README 파일을 활용하세요.
- Pull Request 제출: 기여하기 전에 고품질의 code, 테스트, 문서화를 갖추었는지 확인하세요.
오픈 소스 완벽 가이드 - 기여 방법
개발 환경 설정
효율적인 플러그인 개발을 위해서는 적절한 개발 환경 구축이 핵심입니다. 잘 준비된 환경은 플러그인의 원활한 코딩, 테스트 및 배포를 가능하게 합니다.
필요한 도구와 기술
시작하기 전에 다음 도구들이 설치되어 있는지 확인하세요:
| 카테고리 | 요구 사항 |
|---|---|
| 핵심 도구 | Node.js (LTS), npm 6+, Git |
| IDE/에디터 | Visual Studio Code 또는 선호하는 에디터 |
| iOS 개발 | Xcode, SwiftLint, CocoaPods |
| Android 개발 | Android Studio, Android SDK, JDK |
또한 웹 개발에는 TypeScript, 네이티브 개발 작업에는 Swift(iOS) 또는 Java/Kotlin(Android)에 익숙해야 합니다. [1][2].
모노레포 설정하기
이 Capacitor 플러그인 생태계는 모노레포 구조를 기반으로 합니다. 이 방식을 통해 처음부터 커뮤니티 표준에 부합하는 작업을 할 수 있습니다.
-
Repository Fork 및 Clone
먼저 GitHub에서 Capacitor plugins repository를 fork한 다음, fork한 repository를 clone하세요:git clone https://github.com/your-username/capacitor-plugins.git cd capacitor-plugins npm install -
Dependencies 설치 및 Build
다음 명령어를 실행하여 필요한 모든 패키지를 설치하고 plugins를 빌드하세요:npm run build -
Version Control 설정
변경 사항에는 feature branch를 사용하고, fork한 repository가 upstream repository와 동기화되도록 유지하세요.
Native 플랫폼 준비하기
크로스 플랫폼 개발을 위해 iOS와 Android 환경을 모두 설정해야 합니다.
iOS의 경우:
-
Mac App Store에서 Xcode를 다운로드하세요.
-
다음 명령어로 command-line tools를 설치하세요:
xcode-select --install -
다음 명령어로 CocoaPods를 설치하세요:
sudo gem install cocoapods -
Apple Developer 계정과 필요한 인증서를 설정하세요.
-
code 품질 유지를 위해 SwiftLint를 사용하세요(선택 사항).
Android의 경우:
- Android Studio와 최신 SDK, 가상 디바이스를 함께 설치하세요.
- JDK가 설치되어 있는지 확인하세요.
- Android Studio에서 Android SDK를 올바르게 설정하세요.
플랫폼 설정이 완료되면, 정해진 코딩 관례를 따르며 본격적인 플러그인 개발을 시작할 수 있습니다.
Code 표준 가이드
개발 환경 구축을 마쳤다면, 유지보수와 사용이 용이한 플러그인을 만들기 위해 다음 가이드를 준수해 주세요.
스타일 가이드 준수
이 Capacitor 플러그인 생태계는 다음과 같은 도구를 사용하여 엄격한 코딩 표준을 적용합니다: ESLint, Prettier, 그리고 SwiftLint입니다. 필수 포맷팅 규칙은 다음과 같습니다:
| 구성 요소 | 형식 |
|---|---|
| 변수 | deviceInfo (camelCase) |
| 클래스 | BatteryManager (PascalCase) |
| 메서드 | getLanguageCode() (camelCase) |
| 상수 | MAX_RETRY_COUNT (SNAKE_CASE) |
플러그인은 더 나은 타입 안정성과 ES6+ 기능을 위해 TypeScript를 사용해야 합니다. 예: async/await또한 Swift(iOS)와 Kotlin(Android)의 플랫폼별 코딩 컨벤션을 따르세요.
에러 및 타입 관리
크로스 플랫폼 호환성을 위해 일관된 에러 핸들링이 매우 중요합니다. 예시는 다음과 같습니다:
async checkPermissions(): Promise<PermissionStatus> {
try {
const result = await this.implementation.checkPermissions();
return result;
} catch (error) {
throw new Error(`Permission check failed: ${error.message}`);
}
}
타입 안전성을 위해:
- 특정 유스케이스에 맞춘 전용 인터페이스를 사용하세요.
- 플랫폼별 차이에는 유니온 타입을 적용하세요.
Code 문서
좋은 문서는 플러그인을 쉽게 접하고 사용할 수 있게 하는 핵심입니다. 다음 원칙을 따르세요:
- API 문서: 호환되는 JSDoc 주석을 작성하세요:
@capacitor/docgen로 끝납니다. 예:
/**
* @description Get the device's current battery level
* @returns Promise with the battery level percentage
*/
async getBatteryLevel(): Promise<{ level: number }>;
- README 구조: 설치 단계, 설정 방법, 플랫폼별 요구 사항, 사용 예시, 그리고 상세한 API 레퍼런스와 같은 필수 정보를 포함하세요.
잘 작성된 문서는 플러그인을 쉽게 도입할 수 있게 하며, 더 넓은 Capacitor 커뮤니티에 기여합니다.
sbb-itb-f9944d2
플러그인 테스트 가이드
Capacitor 플러그인을 테스트할 때는 원활한 기능과 안정성을 보장하기 위해 몇 가지 핵심 영역에 집중해야 합니다.
Native Bridge 테스트
Native bridge 테스트는 JavaScript와 native code 간의 올바른 통신을 보장합니다. 시작하려면 각 플랫폼에 맞는 프레임워크로 테스트 환경을 설정하세요.
다음은 Jest 기반 JavaScript 측 unit test 예시입니다:
// Example of a Jest unit test for the JavaScript bridge
describe('DeviceInfo Plugin', () => {
test('getBatteryLevel returns valid percentage', async () => {
const result = await DeviceInfo.getBatteryLevel();
expect(result.level).toBeGreaterThanOrEqual(0);
expect(result.level).toBeLessThanOrEqual(100);
});
});
Native 측을 테스트하려면 iOS에는 XCTest, Android에는 JUnit을 사용하세요. 아래는 Android 예시입니다:
@Test
fun testBatteryLevel() {
val plugin = DeviceInfo()
val result = plugin.getBatteryLevel()
assertTrue(result.level in 0..100)
}
핵심 bridge 기능이 예상대로 작동하는지 확인했다면, 이제 전체 사용자 워크플로우 테스트로 넘어가세요.
전체 플러그인 테스트
다양한 시나리오에서 플러그인이 제대로 작동하는지 확인하려면 다음 카테고리를 테스트하세요:
| 테스트 카테고리 | 핵심 집중 분야 |
|---|---|
| 통합 테스트 | 크로스 플랫폼 기능 |
| 성능 테스트 | 리소스 사용량 및 응답 시간 |
| 보안 테스트 | 데이터 처리 및 권한 확인 |
기능이 복잡한 플러그인이라면 실제 사용자 시나리오를 시뮬레이션하세요. 예를 들어 DeviceInfo 플러그인을 테스트할 때는 다음을 확인하세요:
- 다양한 네트워크 환경에서의 성공적인 업로드
- 정확한 진행률 보고
- 대용량 파일 전송 중 메모리 사용량
OTA 테스트를 위한 Capgo

Capgo의 오픈소스 도구를 사용하면 업데이트를 빠르게 배포하고 테스트할 수 있습니다. 사용 방법은 다음과 같습니다:
- 설정하기 업데이트 채널 dev, staging, production 등 환경별로
- CI/CD 도구로 배포를 자동화하세요.
- 업데이트를 즉시 배포하세요.
- 를 통해 성능과 문제를 모니터링하세요 Capgo 대시보드.
단계적 롤아웃을 위해 Capgo은 업데이트 대상 사용자를 소수 비율로 제한할 수 있습니다. 예를 들어, 24시간마다 사용자의 25%에게 새 버전을 배포할 수 있습니다:
// Example configuration for staged rollout
{
"plugin": "camera-plugin",
"version": "1.2.0",
"rollout": {
"percentage": 25,
"interval": "24h"
}
}
이 단계적 접근 방식은 전체 릴리스 전에 커뮤니티 피드백을 활용하여 문제를 조기에 발견하는 데 도움이 됩니다.
Pull Request 프로세스
변경 사항에 대한 테스트를 모두 마쳤다면, 다음 단계에 따라 pull request를 제출해 주세요:
PR 제출 체크리스트
제출 전에 다음 핵심 항목을 모두 확인하세요:
| 카테고리 | 체크 항목 |
|---|---|
| Code 품질 | - Swift/Kotlin 구현이 웹 API와 일치하는지 확인하세요. |
| 테스트 | - 새로운 기능에 대한 유닛 테스트를 추가하세요. - CI/CD pipeline 체크가 성공했는지 확인하세요. |
| 문서 | - 필요에 따라 README, 인라인 문서, CHANGELOG를 업데이트하세요. |
커뮤니티 가이드라인
협업할 때는 다음 베스트 프랙티스를 따르세요:
- 리뷰어 피드백에 빠르게 응답하세요.
- 논의는 기술적인 세부 사항에 집중하세요.
- code 변경 사항을 제안하려면 GitHub의 suggestion 기능을 사용하세요.
- 한 번에 하나의 기능이나 이슈만 다루는 작고 명확한 pull request를 제출하세요.
규모가 큰 변경 사항은 먼저 issue를 만들어 접근 방식을 논의하는 것이 좋습니다. Capacitor 팀은 자동화된 검사를 위해 GitHub Actions를 사용하며, pull request가 리뷰되기 전 모든 검사를 통과해야 합니다.
Capgo 통합 가이드
플러그인에서 live updates를 다룬다면, 제출 전 Capgo와 원활하게 작동하는지 확인하세요:
-
버전 관리
플러그인에 명확한 semantic versioning을 사용하고 모든 변경 사항을 changelog에 기록하세요. Capgo 시스템은 사용자 기기 전반의 버전 적용 현황을 추적하는 데 도움을 줍니다. -
CI/CD 통합
업데이트 배포를 자동화하려면 Capgo를 CI/CD 파이프라인에 통합하세요. -
업데이트 모니터링
배포 성공률을 모니터링하고 앱 스토어 가이드라인 준수 여부를 확인하세요.
요약
플러그인으로 의미 있는 기여를 하려면 정해진 프로세스를 따르고 커뮤니티 표준을 충족하는 것이 중요합니다. 여기에는 Capacitor의 코딩 가이드라인을 따르고 작업을 철저히 테스트하는 것이 포함됩니다.
PR 체크리스트는 고품질 제출물을 요구합니다. 플러그인이 라이브 업데이트를 지원한다면, 앞서 언급했듯이 Capgo와 통합해 앱 스토어 승인을 기다리지 않고 업데이트를 빠르게 출시할 수 있습니다.
PR이 머지되면 이슈를 추적하고 버전 업데이트를 릴리스하며 계속 참여하세요. 커뮤니티와의 꾸준한 소통, 지속적인 유지보수, 그리고 Capacitor 업데이트를 꾸준히 따라가는 것은 플러그인이 계속 유용하고 관련성 있게 유지되도록 보장합니다.
사용자 피드백에 귀 기울이고 필요에 따라 업데이트하세요. 이러한 지속적인 노력은 생태계 전반의 품질을 유지하고 플러그인이 개발자에게 계속 가치 있도록 하는 데 도움이 됩니다.
Capacitor 플러그인 기여 가이드에서 계속하기
사용 중이라면 Capacitor 플러그인 기여 가이드 네이티브 플러그인 작업을 계획하려면, 이를 다음 항목과 연결하세요: Capgo 플러그인 디렉토리 Capgo Plugin Directory의 제품 워크플로우에 맞춰, Capgo의 Capacitor 플러그인 Capgo의 Capacitor 플러그인 구현 상세 내용에 대해서는, 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부 사항은, Ionic Enterprise 플러그인 대안 Ionic Enterprise 플러그인 대안의 제품 워크플로우와, Capgo Native Build Capgo Native Builds의 제품 워크플로우를 위해.