Capacitor los plugins conectan tecnologías web con características nativas del dispositivo, lo que permite el desarrollo de aplicaciones multiplataforma. Esta guía te ayuda a:
- Configurar tu entorno: Herramientas como Node.js, Xcode, y Android Studio son esenciales.
- Seguir los estándares de código: Usa TypeScript, Swift, y Kotlin con convenciones de nomenclatura consistentes y manejo de errores.
- Probar exhaustivamente: Escribe pruebas unitarias para JavaScript, iOS, y Android para asegurar la fiabilidad.
- Documentar claramente: Usa JSDoc y archivos README para una fácil adopción.
- Enviar una solicitud de extracción: Asegúrate de tener un código de alta calidad, pruebas y documentación antes de contribuir.
Guía Completa de Código Abierto - Cómo Contribuir
Configuración del Entorno de Desarrollo
Crear un entorno de desarrollo adecuado es clave para el desarrollo eficiente de plugins. Una configuración bien preparada permite una codificación, prueba y despliegue fluidos de tus plugins.
Herramientas y habilidades que necesitarás
Antes de comenzar, asegúrate de tener las siguientes herramientas instaladas:
Categoría | Requisitos |
---|---|
Herramientas Básicas | Node.js (LTS), npm 6+, Git |
IDE/Editors | Visual Studio Code o tu editor preferido |
Desarrollo en iOS | Xcode, SwiftLint, CocoaPods |
Desarrollo en Android | Android Studio, Android SDK, JDK |
También deberías sentirte cómodo con TypeScript para desarrollo web y ya sea Swift (para iOS) o Java/Kotlin (para Android) para tareas de desarrollo nativo [1][2].
Configurando el Monorepo
El ecosistema de plugins de Capacitor se basa en una estructura de monorepo. Este enfoque asegura que tu trabajo esté alineado con los estándares de la comunidad desde el principio.
-
Fork y Clonar el Repositorio
Comienza haciendo un fork del repositorio de plugins de Capacitor en GitHub. Luego, clona tu repositorio forkeado:Terminal window git clone https://github.com/your-username/capacitor-plugins.gitcd capacitor-pluginsnpm install -
Instalar Dependencias y Construir
Ejecuta el siguiente comando para instalar todo lo que necesitas y construir los plugins:Terminal window npm run build -
Configurar Control de Versiones
Usa ramas de características para tus cambios y mantén tu fork sincronizado con el repositorio principal.
Preparando las Plataformas Nativas
Para el desarrollo multiplataforma, necesitarás configurar tanto los entornos de iOS como de Android.
Para iOS:
-
Descarga Xcode desde la App Store de Mac.
-
Instala herramientas de línea de comandos usando:
Terminal window xcode-select --install -
Instala CocoaPods con:
Terminal window sudo gem install cocoapods -
Configura una cuenta de desarrollador de Apple y los certificados necesarios.
-
Usa SwiftLint (opcional) para mantener la calidad del código.
Para Android:
- Instala Android Studio junto con el SDK más reciente y un dispositivo virtual.
- Asegúrate de tener un JDK instalado.
- Configura el SDK de Android correctamente dentro de Android Studio.
Una vez que estas plataformas estén configuradas, estarás listo para seguir prácticas de codificación establecidas y sumergirte en el desarrollo de plugins.
Guía de Estándares de Código
Ahora que tu entorno de desarrollo está configurado, adhiérete a estas pautas para construir plugins que sean fáciles de mantener y usar.
Cumplimiento de la Guía de Estilo
El ecosistema de plugins de Capacitor impone estrictos estándares de codificación utilizando herramientas como ESLint, Prettier y SwiftLint. Aquí hay un resumen rápido del formato requerido:
Componente | Formato |
---|---|
Variables | deviceInfo (camelCase) |
Clases | BatteryManager (PascalCase) |
Métodos | getLanguageCode() (camelCase) |
Constantes | MAX_RETRY_COUNT (SNAKE_CASE) |
Los plugins deben usar TypeScript para una mejor seguridad de tipos y características ES6+ como async/await
. Además, sigue las convenciones de codificación específicas de la plataforma para Swift (iOS) y Kotlin (Android).
Manejo de Errores y Tipos
El manejo consistente de errores es crucial para la compatibilidad multiplataforma. Aquí hay un ejemplo:
async checkPermissions(): Promise<PermissionStatus> { try { const result = await this.implementation.checkPermissions(); return result; } catch (error) { throw new Error(`Permission check failed: ${error.message}`); }}
Para la seguridad de tipos:
- Utiliza interfaces enfocadas adaptadas a casos de uso específicos.
- Aplica tipos de unión para variaciones específicas de la plataforma.
- Implementa guardianes de tipo para validar tipos en tiempo de ejecución [1].
Documentación del Código
Una buena documentación es clave para hacer que tu plugin sea accesible y fácil de usar. Cumple con estas prácticas:
- Documentación de la API: Escribe comentarios JSDoc que funcionen con
@capacitor/docgen
. Por ejemplo:
/** * @description Get the device's current battery level * @returns Promise with the battery level percentage */async getBatteryLevel(): Promise<{ level: number }>;
- Estructura del README: Incluye información esencial como pasos de instalación, instrucciones de configuración, requisitos específicos de la plataforma, ejemplos de uso, y una referencia de API detallada.
Una documentación bien escrita asegura que tu plugin sea fácil de adoptar y contribuye a la comunidad más amplia de Capacitor.
sbb-itb-f9944d2
Guía de Pruebas de Plugins
Probar los plugins de Capacitor implica centrarse en algunas áreas críticas para asegurar una funcionalidad y fiabilidad fluidas.
Pruebas del Puente Nativo
Las pruebas del puente nativo aseguran una comunicación adecuada entre JavaScript y el código nativo. Para comenzar, configura tu entorno de pruebas con marcos adaptados a cada plataforma.
Aquí hay un ejemplo de una prueba unitaria de Jest para el lado de JavaScript:
// Example of a Jest unit test for the JavaScript bridgedescribe('DeviceInfo Plugin', () => { test('getBatteryLevel returns valid percentage', async () => { const result = await DeviceInfo.getBatteryLevel(); expect(result.level).toBeGreaterThanOrEqual(0); expect(result.level).toBeLessThanOrEqual(100); });});
Para las pruebas en el lado nativo, usa XCTest para iOS y JUnit para Android. A continuación, un ejemplo para Android:
@Testfun testBatteryLevel() { val plugin = DeviceInfo() val result = plugin.getBatteryLevel() assertTrue(result.level in 0..100)}
Una vez que hayas confirmado que la funcionalidad principal del puente funciona como se esperaba, pasa a probar flujos de trabajo completos del usuario.
Pruebas Completas de Plugins
Para asegurarte de que tu plugin funciona bien en diferentes escenarios, prueba varias categorías:
Categoría de Prueba | Áreas Clave de Enfoque |
---|---|
Pruebas de Integración | Funcionalidad multiplataforma |
Pruebas de Rendimiento | Uso de recursos y tiempos de respuesta |
Pruebas de Seguridad | Manejo de datos y comprobaciones de permisos |
Para plugins con características complejas, simula escenarios de usuario del mundo real. Por ejemplo, si estás probando un plugin DeviceInfo, verifica:
- Cargas exitosas bajo diferentes condiciones de red
- Informes de progreso precisos
- Uso de memoria durante transferencias de archivos grandes
Pruebas OTA con Capgo
Las herramientas de código abierto de Capgo facilitan el despliegue y prueba de actualizaciones rápidamente. Aquí se explica cómo usarlo:
- Configura canales de actualización como dev, staging, y producción.
- Automatiza los despliegues con herramientas de CI/CD.
- Envía actualizaciones al instante.
- Monitorea el rendimiento y problemas a través del tablero de Capgo.
Para despliegues por fases, Capgo te permite limitar las actualizaciones a un pequeño porcentaje de usuarios. Por ejemplo, puedes implementar una nueva versión al 25% de los usuarios cada 24 horas:
// Example configuration for staged rollout{ "plugin": "camera-plugin", "version": "1.2.0", "rollout": { "percentage": 25, "interval": "24h" }}
Este enfoque gradual ayuda a identificar problemas temprano aprovechando los comentarios de la comunidad antes de un lanzamiento completo.
Proceso de Solicitud de Extracción
Una vez que hayas probado exhaustivamente tus cambios, sigue estos pasos para enviar tu solicitud de extracción:
Lista de Verificación para la Presentación de PR
Antes de enviar, asegúrate de haber cubierto estas áreas clave:
Categoría | Qué Comprobar |
---|---|
Calidad del Código | - Asegúrate de que las implementaciones de Swift/Kotlin estén alineadas con la API web. |
Pruebas | - Añade pruebas unitarias para cualquier nueva funcionalidad. |
Documentación | - Actualiza el README, la documentación en línea, y el CHANGELOG según sea necesario. |
Pautas de la Comunidad
Al colaborar, adhiérete a estas mejores prácticas:
- Responde rápidamente a los comentarios de los revisores.
- Mantén las discusiones centradas en detalles técnicos.
- Usa la función de sugerencia de GitHub para proponer cambios de código.
- Envía solicitudes de extracción pequeñas y enfocadas que aborden una característica o problema a la vez.
Para cambios más grandes, es buena idea crear un problema primero y discutir tu enfoque. El equipo de Capacitor se basa en GitHub Actions para verificaciones automatizadas, y todas las verificaciones deben pasar antes de que tu solicitud de extracción pueda ser revisada.
Guía de Integración con Capgo
Si tu plugin implica actualizaciones en vivo, asegúrate de que funcione sin problemas con Capgo antes de enviar:
-
Control de Versiones
Utiliza una clara versión semántica para tu plugin y documenta todos los cambios en el changelog. El sistema de Capgo ayuda a rastrear la adopción de versiones en los dispositivos de los usuarios. -
Integración de CI/CD
Integra Capgo en tu pipeline de CI/CD para automatizar los despliegues de actualizaciones. -
Monitoreo de Actualizaciones
Monitorea las tasas de éxito de los despliegues y asegura el cumplimiento con las directrices de la tienda de aplicaciones.
Resumen
Para hacer una contribución significativa con tu plugin, es importante seguir el proceso establecido y cumplir con los estándares de la comunidad. Esto incluye adherirse a las pautas de codificación de Capacitor y probar exhaustivamente tu trabajo.
La lista de verificación de PR destaca la necesidad de presentaciones de alta calidad. Si tu plugin admite actualizaciones en vivo, integrarse con Capgo (como se mencionó anteriormente) puede ayudarte a lanzar actualizaciones rápidamente sin esperar aprobaciones de la tienda de aplicaciones.
Una vez que tu PR esté fusionada, mantente involucrado rastreando problemas y liberando actualizaciones de versiones. La interacción regular con la comunidad, el mantenimiento constante y mantenerse al día con las actualizaciones de Capacitor asegurarán que tu plugin siga siendo útil y relevante.
Presta atención a los comentarios de los usuarios y realiza actualizaciones según sea necesario. Este esfuerzo continuo ayuda a mantener la calidad general del ecosistema y mantiene tu plugin valioso para los desarrolladores.