Saltar al contenido principal

Guía de contribución de plugins de Capacitor

Aprende a contribuir eficazmente en los plugins de Capacitor con esta guía completa sobre configuración, estándares de code, testing y documentación.

Guía de contribución de plugins de Capacitor Capgo ilustración de blog

Capacitor los plugins conectan tecnologías web con funciones nativas del dispositivo, permitiendo el desarrollo de apps multiplataforma. Esta guía te ayudará a:

  • Configurar tu entorno: Herramientas como Node.js, Xcode, y Android Studio son esenciales.
  • Sigue los estándares de Code: Usa TypeScript, Swift, y Kotlin con convenciones de nombres y manejo de errores consistentes.
  • Testea a fondo: Escribe unit tests para JavaScript, iOS y Android para garantizar la fiabilidad.
  • Documenta con claridad: Usa JSDoc y archivos README para facilitar la adopción.
  • Envía un Pull Request: Asegura un code de alta calidad, testing y documentación antes de contribuir.

Guía completa de Open Source: cómo contribuir

Configuración del entorno de desarrollo

Crear un entorno de desarrollo adecuado es clave para desarrollar plugins eficientemente. Un setup bien preparado permite programar, testear y desplegar tus plugins sin problemas.

Herramientas y habilidades necesarias

Antes de empezar, asegúrate de tener instaladas las siguientes herramientas:

Categoría Requisitos
Core Tools Node.js (LTS), npm 6+, Git
IDE/Editores Visual Studio Code o tu editor preferido
Desarrollo para 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 con Swift (para iOS) o Java/Kotlin (para Android) para tareas de desarrollo nativo [1][2].

Configuración del monorepo

El plugins de Capacitor el ecosistema se basa en una estructura de monorepo. Así aseguras que tu trabajo cumpla con los estándares de la comunidad desde el principio.

  1. Haz un Fork y Clona el Repositorio
    Empieza haciendo un fork del repositorio de plugins de Capacitor en GitHub. Luego, clona tu fork:

    git clone https://github.com/your-username/capacitor-plugins.git
    cd capacitor-plugins
    npm install
  2. Instala las Dependencias y Haz el Build
    Ejecuta el siguiente comando para instalar todo lo necesario y hacer el build de los plugins:

    npm run build
  3. Configura el control de versiones
    Usa feature branches para tus cambios y mantén tu fork sincronizado con el repositorio upstream.

Preparación de plataformas nativas

Para el desarrollo multiplataforma, tendrás que configurar los entornos de iOS y Android.

Para iOS:

  • Descarga Xcode desde la Mac App Store.

  • Instala las command-line tools con:

    xcode-select --install
  • Instala CocoaPods con:

    sudo gem install cocoapods
  • Configura una cuenta de Apple Developer y los certificados necesarios.

  • Usa SwiftLint (opcional) para mantener la calidad de code.

Para Android:

  • Instala Android Studio junto con la última versión de SDK y un dispositivo virtual.
  • Asegúrate de tener un JDK instalado.
  • Configura correctamente el SDK de Android en Android Studio.

Una vez configuradas estas plataformas, estarás listo para seguir las mejores prácticas de código y sumergirte en el desarrollo de plugins.

Guía de estándares de Code

Ahora que tu entorno de desarrollo está listo, sigue estas pautas para crear plugins fáciles de mantener y usar.

Cumplimiento de la guía de estilo

El ecosistema de plugins de Capacitor impone estándares de código estrictos usando herramientas como ESLint, Prettier, y SwiftLint. Aquí tienes 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 mejorar el tipado y aprovechar ES6+, como async/await. Además, sigue las convenciones de código de cada plataforma para Swift (iOS) y Kotlin (Android).

Gestión de errores y tipos

Un manejo de errores consistente es clave para la compatibilidad multiplataforma. Aquí 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 mayor seguridad de tipos:

  • Usa interfaces específicas para cada caso de uso.
  • Aplica union types para variaciones por plataforma.

Documentación de Code

Una buena documentación es clave para que tu plugin sea accesible y fácil de usar. Sigue estas prácticas:

  1. Documentación de 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 }>;
  1. Estructura del README: Incluye info esencial como pasos de instalación, configuración, requisitos por plataforma, ejemplos de uso y una referencia detallada de API.

Una buena documentación facilita la adopción de tu plugin y ayuda a la comunidad de Capacitor.

sbb-itb-f9944d2

Guía de testing de plugins

Probar los plugins de Capacitor requiere enfocarse en áreas críticas para garantizar su funcionalidad y fiabilidad.

Tests del bridge nativo

El testing del bridge nativo garantiza una comunicación adecuada entre JavaScript y el code nativo. Para empezar, configura tu entorno de testing con frameworks adaptados a cada plataforma.

Aquí tienes un ejemplo de un Jest unit test del lado 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);
  });
});

Para testear el lado nativo, usa XCTest en iOS y JUnit en Android. Aquí tienes un ejemplo para Android:

@Test
fun testBatteryLevel() {
    val plugin = DeviceInfo()
    val result = plugin.getBatteryLevel()
    assertTrue(result.level in 0..100)
}

Una vez confirmes que la funcionalidad principal del bridge funciona como se espera, pasa a testear workflows completos de usuario.

Tests completos del plugin

Para asegurarte de que tu plugin funcione bien en distintos escenarios, prueba varias categorías:

Categoría de test Áreas de enfoque clave
Tests de integración Funcionalidad multiplataforma
Tests de rendimiento Uso de recursos y tiempos de respuesta
Tests de seguridad Manejo de datos y verificación de permisos

Para plugins con funciones complejas, simula escenarios reales de usuario. Por ejemplo, si testeas un plugin de DeviceInfo, verifica:

  • Uploads exitosos en distintas condiciones de red
  • Reporte de progreso preciso
  • Uso de memoria en transferencias de archivos grandes

Testing OTA con Capgo

Interfaz del dashboard de Capgo Live Update

Las herramientas open-source de Capgo facilitan el despliegue y testeo rápido de actualizaciones. Así es como se usa:

  1. Configura canales de actualización como dev, staging y production.
  2. Automatiza despliegues con herramientas de CI/CD.
  3. Lanza actualizaciones al instante.
  4. Monitorea el rendimiento y errores vía el Dashboard de Capgo.

Para rollouts graduales, Capgo te permite limitar las actualizaciones a un pequeño porcentaje de usuarios. Por ejemplo, puedes lanzar 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 detectar problemas pronto, aprovechando el feedback de la comunidad antes del release completo.

Proceso de Pull Request

Una vez que hayas probado tus cambios a fondo, sigue estos pasos para enviar tu pull request:

Checklist para enviar el PR

Antes de enviarlo, asegúrate de haber cubierto estos puntos clave:

Categoría Qué revisar
Calidad de Code - Asegúrate de que las implementaciones en Swift/Kotlin coincidan con el API web.
Pruebas - Añade unit tests para cualquier funcionalidad nueva.
- Confirma que los checks del pipeline de CI/CD sean exitosos.
Documentación - Actualiza el README, la documentación interna y el CHANGELOG según sea necesario.

Guías de la comunidad

Al colaborar, sigue estas buenas prácticas:

  • Responde rápido al feedback de los revisores.
  • Mantén las discusiones centradas en detalles técnicos.
  • Usa la función de sugerencias de GitHub para proponer cambios en code.
  • Envía pull requests pequeños y específicos que resuelvan una sola funcionalidad o issue a la vez.

Para cambios grandes, es mejor crear un issue primero y discutir tu enfoque. El equipo de Capacitor depende de GitHub Actions para los checks automáticos, y todos deben pasar antes de revisar tu pull request.

Guía de integración de Capgo

Si tu plugin incluye live updates, asegúrate de que funcione sin problemas con Capgo antes de enviarlo:

  1. Control de versiones
    Usa semantic versioning claro para tu plugin y documenta todos los cambios en el changelog. El sistema de Capgo ayuda a trackear la adopción de versiones en los dispositivos de los usuarios.

  2. Integración CI/CD
    Integra Capgo en tu pipeline de CI/CD para automatizar el despliegue de actualizaciones.

  3. Monitoreo de actualizaciones
    Monitorea la tasa de éxito de los despliegues y asegura el cumplimiento de las guías de las app stores.

Resumen

Para que tu plugin sea una contribución valiosa, es clave seguir el proceso establecido y cumplir con los estándares de la comunidad. Esto incluye respetar las guías de código de Capacitor y probar tu trabajo a fondo.

El checklist de PR destaca la necesidad de envíos de alta calidad. Si tu plugin admite live updates, integrarlo con Capgo (como mencionamos antes) te ayudará a lanzar actualizaciones rápido sin esperar la aprobación de las app stores.

Una vez que se acepte tu PR, mantente activo siguiendo los issues y lanzando nuevas versiones. La interacción constante con la comunidad, el mantenimiento regular y estar al día con las actualizaciones de Capacitor garantizarán que tu plugin siga siendo útil y relevante.

Presta atención al feedback de los usuarios y haz actualizaciones cuando sea necesario. Este esfuerzo continuo ayuda a mantener la calidad general del ecosistema y mantiene tu plugin valioso para los desarrolladores.

Continuar desde la Guía de contribución de plugins de Capacitor

Si estás usando Guía de contribución de plugins de Capacitor para planificar el trabajo con plugins nativos, conéctalo con Directorio de plugins de Capgo para el flujo de trabajo del producto en Capgo Plugin Directory, Plugins de Capacitor por Capgo para el detalle de implementación en los Plugins de Capacitor por Capgo, Añadir o actualizar plugins para el detalle de implementación en Agregar o actualizar plugins, Alternativas a plugins de Ionic Enterprise para el flujo de trabajo en Alternativas a plugins de Ionic Enterprise, y Native Builds de Capgo para el flujo de trabajo del producto en Capgo Native Builds.

Live updates para apps Capacitor

Cuando un bug de la capa web está en producción, publica el fix a través de Capgo en lugar de esperar días a la aprobación de la app store. Los usuarios reciben la actualización en segundo plano mientras los cambios nativos siguen el flujo de revisión habitual.

Lo último de nuestro blog

Capgo te da la información clave que necesitas para crear una app móvil realmente profesional.