Capacitor les plugins connectent les technologies web aux fonctionnalités natives de l’appareil, permettant le développement d’applications multiplateformes. Ce guide vous aide à :
- Configurer votre environnement : des outils comme Node.js, Xcode, et Android Studio sont indispensables.
- Respectez les standards Code : Utilisez TypeScript, Swift, et Kotlin avec des conventions de nommage cohérentes et une gestion des erreurs.
- Testez minutieusement : écrivez des tests unitaires pour JavaScript, iOS et Android afin de garantir la fiabilité.
- Documentez clairement : utilisez JSDoc et des fichiers README pour faciliter l’adoption.
- Soumettez une pull request: Assurez-vous d’un code de haute qualité, de tests et d’une documentation solides avant de contribuer.
Guide complet de l’open source – Comment contribuer
Configuration de l’environnement de développement
Créer un environnement de développement adapté est essentiel pour développer des plugins efficacement. Une configuration soignée permet de coder, tester et déployer vos plugins sans accroc.
Outils et compétences requis
Avant de commencer, vérifiez que les outils suivants sont installés :
| Catégorie | Prérequis |
|---|---|
| Outils de base | Node.js (LTS), npm 6+, Git |
| IDE/éditeurs | Visual Studio Code ou votre éditeur préféré |
| Développement iOS | Xcode, SwiftLint, CocoaPods |
| Développement Android | Android Studio, Android SDK, JDK |
Vous devez également être à l’aise avec TypeScript pour le développement web, ainsi qu’avec Swift (pour iOS) ou Java/Kotlin (pour Android) pour les tâches de développement natif [1][2].
Configuration du monorepo
Le Plugins Capacitor l’écosystème repose sur une structure monorepo. Cette approche garantit que votre travail est conforme aux standards de la communauté dès le départ.
-
Forker et cloner le dépôt
Commencez par forker le dépôt de plugins Capacitor sur GitHub. Puis, clonez votre dépôt forké :git clone https://github.com/your-username/capacitor-plugins.git cd capacitor-plugins npm install -
Installer les dépendances et compiler
Exécutez la commande suivante pour installer tout ce dont vous avez besoin et compiler les plugins :npm run build -
Configurer la gestion de versions
Utilisez des branches de fonctionnalité pour vos modifications et gardez votre fork synchronisé avec le dépôt amont.
Préparer les plateformes natives
Pour le développement multiplateforme, vous devez configurer les environnements iOS et Android.
Pour iOS :
-
Téléchargez Xcode depuis le Mac App Store.
-
Installez les outils en ligne de commande avec :
xcode-select --install -
Installez CocoaPods avec :
sudo gem install cocoapods -
Créez un compte Apple Developer et les certificats nécessaires.
-
Utilisez SwiftLint (facultatif) pour maintenir la qualité du code.
Pour Android :
- Installez Android Studio avec le dernier SDK et un appareil virtuel.
- Assurez-vous d’avoir un JDK installé.
- Configurez correctement le SDK Android dans Android Studio.
Une fois ces plateformes configurées, vous serez prêt à suivre les bonnes pratiques de code et à vous lancer dans le développement de plugins.
Guide des standards Code
Maintenant que votre environnement de développement est prêt, respectez ces directives pour créer des plugins faciles à maintenir et à utiliser.
Conformité au guide de style
Le écosystème de plugins Capacitor impose des standards de code stricts via des outils comme ESLint, Prettier, et SwiftLint. Voici un aperçu rapide du formatage requis :
| Composant | Formatage |
|---|---|
| Variables | deviceInfo (camelCase) |
| Classes | BatteryManager (PascalCase) |
| Méthodes | getLanguageCode() (camelCase) |
| Constantes | MAX_RETRY_COUNT (SNAKE_CASE) |
Les plugins doivent utiliser TypeScript pour une meilleure sécurité des types et des fonctionnalités ES6+ comme async/awaitDe plus, respectez les conventions de codage spécifiques à chaque plateforme pour Swift (iOS) et Kotlin (Android).
Gestion des erreurs et des types
Une gestion cohérente des erreurs est essentielle pour la compatibilité multiplateforme. Voici un exemple :
async checkPermissions(): Promise<PermissionStatus> {
try {
const result = await this.implementation.checkPermissions();
return result;
} catch (error) {
throw new Error(`Permission check failed: ${error.message}`);
}
}
Pour la sécurité des types :
- Utilisez des interfaces ciblées adaptées à des cas d’usage précis.
- Appliquez des types union pour les variations spécifiques à la plateforme.
Documentation Code
Une bonne documentation est essentielle pour rendre votre plugin accessible et facile à utiliser. Suivez ces bonnes pratiques :
- Documentation API: Rédigez des commentaires JSDoc compatibles avec
@capacitor/docgen. Par exemple :
/**
* @description Get the device's current battery level
* @returns Promise with the battery level percentage
*/
async getBatteryLevel(): Promise<{ level: number }>;
- Structure du README: Incluez les informations essentielles comme les étapes d’installation, les instructions de configuration, les exigences spécifiques à chaque plateforme, des exemples d’utilisation et une référence détaillée de l’API.
Une documentation bien rédigée garantit que votre plugin est facile à adopter et contribue à la communauté Capacitor plus large.
sbb-itb-f9944d2
Guide de test des plugins
Tester les plugins Capacitor demande de se concentrer sur quelques points critiques pour garantir un fonctionnement fluide et fiable.
Tests du bridge natif
Les tests du bridge natif garantissent une communication correcte entre JavaScript et le code natif. Pour commencer, configurez votre environnement de test avec des frameworks adaptés à chaque plateforme.
Voici un exemple de Jest test unitaire pour la partie JavaScript :
// 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);
});
});
Pour les tests côté natif, utilisez XCTest pour iOS et JUnit pour Android. Voici un exemple pour Android :
@Test
fun testBatteryLevel() {
val plugin = DeviceInfo()
val result = plugin.getBatteryLevel()
assertTrue(result.level in 0..100)
}
Une fois que vous avez confirmé que la fonctionnalité de base du bridge fonctionne comme prévu, passez au test des workflows utilisateurs complets.
Tests complets du plugin
Pour garantir que votre plugin fonctionne bien dans différents scénarios, testez plusieurs catégories :
| Catégorie de test | Points clés |
|---|---|
| Tests d'intégration | Fonctionnalités multiplateformes |
| Tests de performance | Utilisation des ressources et temps de réponse |
| Tests de sécurité | Data handling and permission checks |
Pour les plugins aux fonctionnalités complexes, simulez des scénarios utilisateurs réels. Par exemple, si vous testez un plugin DeviceInfo, vérifiez :
- Uploads réussis dans différentes conditions réseau
- Rapport de progression précis
- Memory usage during large file transfers
Tests OTA avec Capgo

Les outils open source de Capgo facilitent le déploiement et le test rapides des mises à jour. Voici comment les utiliser :
- Configuration canaux de mise à jour comme dev, staging et production.
- Automatisez les déploiements avec des outils CI/CD.
- Poussez les mises à jour instantanément.
- Surveillez les performances et les problèmes via le dashboard Capgo.
Pour les déploiements progressifs, Capgo vous permet de limiter les mises à jour à un petit pourcentage d'utilisateurs. Par exemple, vous pouvez déployer une nouvelle version à 25 % des utilisateurs toutes les 24 heures :
// Example configuration for staged rollout
{
"plugin": "camera-plugin",
"version": "1.2.0",
"rollout": {
"percentage": 25,
"interval": "24h"
}
}
Cette approche progressive aide à identifier les problèmes tôt grâce aux retours de la communauté avant une release complète.
Processus de pull request
Une fois vos modifications soigneusement testées, suivez ces étapes pour soumettre votre pull request :
Checklist de soumission de PR
Avant de soumettre, assurez-vous d'avoir couvert ces points clés :
| Catégorie | Points à vérifier |
|---|---|
| Code Qualité | - Vérifiez que les implémentations Swift/Kotlin sont alignées avec l’API web. |
| En test | - Add unit tests for any new functionality. - Confirmez que les vérifications du pipeline CI/CD sont réussies. |
| Documentation | - Mettez à jour le README, la documentation en ligne et le CHANGELOG si nécessaire. |
Directives de la communauté
Lors de la collaboration, respectez ces bonnes pratiques :
- Répondez rapidement aux retours des reviewers.
- Gardez les discussions centrées sur les détails techniques.
- Use GitHub’s suggestion feature to propose code changes.
- Soumettez des pull requests petites et ciblées, traitant une fonctionnalité ou un problème à la fois.
Pour les modifications importantes, il est conseillé de créer d’abord un issue et de discuter de votre approche. L’équipe Capacitor s’appuie sur les GitHub Actions pour les vérifications automatisées, et toutes les vérifications doivent réussir avant que votre pull request ne soit examinée.
Capgo Guide d'intégration
Si votre plugin implique des live updates, assurez-vous qu’il fonctionne parfaitement avec Capgo avant de le soumettre :
-
Gestion des versions
Utilisez un versionnage sémantique clair pour votre plugin et documentez tous les changements dans le changelog. Le système de Capgo aide à suivre l’adoption des versions sur les appareils des utilisateurs. -
Intégration CI/CD
Intégrez Capgo à votre pipeline CI/CD pour automatiser les déploiements de mises à jour. -
Suivi des mises à jour
Surveillez les taux de réussite des déploiements et assurez la conformité aux directives des stores.
Résumé
Pour apporter une contribution significative avec votre plugin, il est essentiel de suivre le processus établi et de respecter les normes de la communauté. Cela implique de se conformer aux directives de codage de Capacitor et de tester soigneusement votre travail.
La liste de contrôle des PR souligne l'importance de soumissions de haute qualité. Si votre plugin prend en charge les live updates, l'intégration avec Capgo (comme mentionné précédemment) peut vous aider à publier des mises à jour rapidement, sans attendre l'approbation des stores.
Une fois votre PR fusionnée, restez actif en suivant les issues et en publiant les mises à jour de version. Une interaction régulière avec la communauté, un maintien le suivi des mises à jour de Capacitor garantiront que votre plugin reste utile et pertinent.
Prêtez attention aux retours des utilisateurs et effectuez les mises à jour nécessaires. Cet effort continu contribue à maintenir la qualité globale de l'écosystème et à garder votre plugin précieux pour les développeurs.
Continuer depuis le Guide de contribution aux plugins Capacitor
Si vous utilisez Capacitor Guide de contribution aux plugins pour planifier le travail sur les plugins natifs, connectez-l’à Capgo Répertoire des plugins pour le workflow produit dans Capgo Plugin Directory, Plugins Capacitor par Capgo pour les détails d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans Adding or Updating Plugins, Alternatives aux plugins Ionic Enterprise pour le workflow produit dans les alternatives aux plugins Ionic Enterprise, et Capgo Native Build pour le workflow produit dans Capgo Native Builds.