Skeleton

¿Que es Skeleton?

Skeleton es una herramienta de línea de comandos (CLI) diseñada para facilitar el desarrollo de widgets en la plataforma de Kommo. Automatiza el proceso de configuración, despliegue y documentación, generando una estructura básica de proyecto (esqueleto) con React, TypeScript y otras tecnologías modernas.

• Permite crear widgets personalizados de forma rápida.
• Incluye tipado, documentación y opciones de localización.
• Mejora la experiencia del desarrollador al reducir errores y tiempos de desarrollo.

¿Por qué utilizarlo?

Skeleton resuelve los principales problemas que enfrentan los desarrolladores al trabajar con widgets en Kommo:

• Falta de documentación clara sobre frameworks modernos.
• Dificultad para configurar entornos de desarrollo y desplegar widgets.
• Necesidad de personalización y escalabilidad.

Ventajas:

• Acelera el desarrollo.
• Mejora la calidad del código.
• Reduce errores.
• Disminuye la carga del equipo de soporte.

Lógica de funcionamiento

Lista de ubicaciones

Esta tabla muestra todas las ubicaciones donde un widget puede estar disponible dentro de Kommo.

El arreglolocations en manifest.json determina dónde — y cómo — los usuarios verán tu widget.

Propiedades adicionales para el manifest.json

Esta tabla asigna cada ubicación especial al bloque JSON que debes añadir en 'manifest.json':

❗️

Incluye solo los bloques que coincidan con las ubicaciones que seleccionaste — de lo contrario Kommo rechazará el manifest

Estructura del proyecto

Tipado en TypeScript:

• Métodos del ciclo de vida del widget (init(), render(), settings()...)
• Métodos internos (get_settings(), etc.)
• Variable APP para interactuar con la API de Kommo

Estructura mínima

Activar el modo de desarrollo después de subir el archivo del widget

Paso 1: Configurar el entorno

Antes de comenzar a desarollar o a compilar el widget para producción, completa las variables de entorno necesarias. El proyecto incluye dos archivos de entorno predefinidos:

• .dev.env — se utiliza en el desarrollo
• .prod.env — se utiliza durante la compilación para producción

Actualiza estos archivos con los valores correspondientes.

¡Importante Nunca subas estos archivos con secretos reales al control de versiones. Utiliza una gestión de secretos específica por entorno en CI/CD para el despliegue.

Paso 2: Desarrollo

Opción A: Con Docker y Make

Genera un paquete ZIP listo para producción:

make build

Opción B: Localmente con yarn

También puedes compilar sin Docker:

yarn install
yarn run build

Esto creará una carpeta dist con tu script de compilación, el manifest, etc., junto con el archivo ZIP.

Paso 3: Compilar

Opción A: Con Docker

Inicia el servidor de desarrollo con un solo comando:

make run-dev

Opción B: Localmente con Yarn

También puedes ejecutar el servidor de desarrollo sin Docker:

yarn install
yarn run dev

Paso 4: Activar el modo de desarrollo después de subir el archivo del widget

Para activar el modo de desarrollo después de subir el archivo widget.zip, sigue estos pasos:

1. Asegúrate de que el puerto y el código del widget estén correctamente configurados en tus variables de entorno. En los archivos .dev.env y .prod.env, verifica que los siguientes valores estén correctamente definidos:
   1. LOCALHOST_PORT — Debe coincidir con el puerto en el que se ejecuta tu servidor local (por ejemplo, 9000).
   2. INTEGRATION_CODE — Debe ser el código específico de tu widget. Puedes encontrarlo en la pestaña “Claves y alcances” después de crear la integración.
2. Activa el modo de desarrollo añadiendo lo siguiente en el localStorage del navegador del cliente. Puedes hacerlo desde la consola de desarrollador del navegador con el siguiente comando:

localStorage.setItem('your_widget_code_is_dev', '9000');

Utiliza el mismo puerto que LOCALHOST_PORT y el mismo código de widget definido en INTEGRATION_CODE en los archivos .env.

También, puedes añadir manualmente esta entrada en el localStorage desde las herramientas del navegador si es necesario.

Una vez hecho esto, el widget cargará los recursos desde tu servidor local cuando esté en modo de desarrollo, permitiéndote hacer pruebas sin tener que volver a subir el archivo ZIP del widget cada vez que realices un cambio.

Referencia