Aller au contenu principal

Capacitor Guide de contribution aux plugins

Apprenez à contribuer efficacement aux plugins Capacitor grâce à un guide complet couvrant la configuration, les normes de codage, les tests et la documentation.

Capacitor Guide de contribution aux plugins Capgo illustration du blog

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.

  1. 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
  2. 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
  3. 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 :

  1. 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 }>;
  1. 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

Interface du dashboard Capgo Live Update

Les outils open source de Capgo facilitent le déploiement et le test rapides des mises à jour. Voici comment les utiliser :

  1. Configuration canaux de mise à jour comme dev, staging et production.
  2. Automatisez les déploiements avec des outils CI/CD.
  3. Poussez les mises à jour instantanément.
  4. 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 :

  1. 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.

  2. Intégration CI/CD
    Intégrez Capgo à votre pipeline CI/CD pour automatiser les déploiements de mises à jour.

  3. 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.

Live updates pour les apps Capacitor

Lorsqu'un bug de la couche web est en ligne, déployez le correctif via Capgo au lieu d'attendre des jours l'approbation des stores. Les utilisateurs reçoivent la mise à jour en arrière-plan, tandis que les changements natifs suivent le circuit de validation habituel.

Les derniers articles du blog

Capgo vous offre les meilleures informations pour créer une application mobile vraiment professionnelle.