Saltar al contenido principal

Resumen

Una vez que tu aplicación esté compilada y probada localmente, tienes dos vías para distribuirla:
  • Desplegar un paquete tar — sube tu aplicación directamente a un servidor Twenty específico para uso interno o privado.
  • Publicar en npm — publica tu paquete, reclámalo en Twenty y completa su configuración para que otros espacios de trabajo puedan descubrirlo e instalarlo.
Ambas rutas comienzan en el mismo paso de build.

Propiedad del registro

La publicación de una aplicación crea un registro de aplicación: la identidad de la aplicación en la instancia, compartida por cada espacio de trabajo que la instala. Contiene la entrada de la aplicación en el marketplace, su cliente OAuth y su estado del lado del servidor: las serverVariables que configura un operador y las entradas con ámbito de server del almacén de pares clave-valor. Un universalIdentifier es único en toda la instancia y un registro pertenece como máximo a un espacio de trabajo (su propietario), o a ninguno hasta que se reclame, por lo que instalar una aplicación y desarrollar una son dos derechos diferentes: Sincronizar código y un manifiesto con un identificador constituye una reivindicación de autoría, por lo que poder instalar una aplicación nunca otorga el derecho a publicar código con su identidad. Se rechaza un espacio de trabajo que no sea el propietario, independientemente de si la aplicación aparece en el marketplace, está preinstalada o es privada. Dos situaciones provocan ese rechazo:
  • El identificador pertenece a otro espacio de trabajo. Cambia el universalIdentifier en la configuración de tu aplicación, que es la respuesta habitual cuando hiciste un fork de la aplicación de otra persona. Si necesitas conservar el identificador, el espacio de trabajo propietario debe transferir el registro al tuyo.
  • El identificador no pertenece a ningún espacio de trabajo. Las aplicaciones importadas por la sincronización del catálogo del marketplace comienzan sin propietario. Reclama el tuyo con GitHub antes de desarrollarlo. La publicación con procedencia de npm proporciona prueba de autoría; no asigna automáticamente un espacio de trabajo propietario en Twenty.

Compilar tu aplicación

Ejecuta el comando de compilación para verificar los tipos y empaquetar tu aplicación:
Esto verifica los tipos y empaqueta la aplicación en una instantánea temporal de la CLI. Usa --json para inspeccionar el manifiesto y los metadatos del artefacto. twenty app publish crea el paquete en sí; no se requiere una compilación de tarball independiente.

Despliegue en un servidor (tarball)

Para aplicaciones que no quieres que estén disponibles públicamente — herramientas propietarias, integraciones solo para empresas o compilaciones experimentales — puedes desplegar un tarball directamente en un servidor de Twenty.

Prerrequisitos

Antes de desplegar, necesitas un remoto configurado que apunte al servidor de destino. Los remotos almacenan la URL del servidor y las credenciales de autenticación localmente en ~/.twenty/config.json. Agrega un remoto:

Despliegue

Compila y sube tu aplicación al servidor en un solo paso:
El uso explícito de --remote production selecciona la conexión guardada anteriormente, aunque otro remoto sea el predeterminado. Guardar un remoto con nombre no cambia un valor predeterminado existente.

Compartir una aplicación desplegada

Las aplicaciones en tarball no se listan en el marketplace público, por lo que otros espacios de trabajo en el mismo servidor no las descubrirán navegando. Para compartir una aplicación desplegada:
  1. Ve a Configuración > Desarrolladores > Aplicaciones y abre tu aplicación en Mis aplicaciones
  2. En la pestaña Distribución, haz clic en Copiar enlace para compartir
  3. Comparte este enlace con usuarios de otros espacios de trabajo — los llevará directamente a la página de instalación de la aplicación
El enlace para compartir usa la URL base del servidor (sin ningún subdominio de espacio de trabajo), por lo que funciona para cualquier espacio de trabajo en el servidor.

Gestión de versiones

Al actualizar una aplicación tarball ya desplegada, el servidor requiere que la version en package.json sea estrictamente mayor (según el orden de semver) que la versión actualmente desplegada. Volver a desplegar la misma versión, o publicar una inferior, se rechaza cuando el servidor registra el archivo tarball cargado, que luego se descarta de nuevo. Verás un error VERSION_ALREADY_EXISTS de la CLI. Para publicar una actualización:
  1. Incrementa el campo version en tu package.json (p. ej., 1.2.3 → 1.2.4, 1.3.0 o 2.0.0)
  2. Ejecuta twenty app publish --private --remote production
  3. Los espacios de trabajo que tienen la aplicación instalada y la actualización automática habilitada (en la pestaña General de la aplicación) se actualizan automáticamente en segundo plano; los demás verán la actualización disponible en su configuración
Las etiquetas de prelanzamiento funcionan como se espera: incrementar 1.0.0-rc.1 → 1.0.0-rc.2 está permitido, y una versión final como 1.0.0 se reconoce correctamente como superior a 1.0.0-rc.5. La versión en package.json debe ser en sí misma una cadena semver válida.

Compatibilidad de la versión del servidor

Si tu app usa una función introducida en una versión específica del servidor Twenty (por ejemplo, proveedores de OAuth agregados en v2.3.0), debes declarar la versión mínima del servidor que tu app requiere usando el campo engines.twenty en package.json:
El valor es un rango semver estándar. Patrones comunes: Qué sucede durante la implementación e instalación:
  • Si engines.twenty está configurado y la versión del servidor de destino no cumple el rango, la implementación (carga del tarball) o la instalación se rechaza con un error SERVER_VERSION_INCOMPATIBLE y un mensaje que indica tanto el rango requerido como la versión real del servidor.
  • Si engines.twenty no está configurado, no se realiza ninguna comprobación de versión y la app se acepta en cualquier versión del servidor (retrocompatible con las apps existentes). Se rechaza un valor en blanco por ser un rango no válido.
  • El marketplace no incluye en la lista una app cuya versión más reciente declare un rango de engines.twenty que el servidor no cumpla, o uno no válido. La app permanece registrada y visible en el panel de administración.
  • Si el servidor no tiene APP_VERSION configurado, se omite la comprobación.
El servidor es la autoridad en la comprobación — valida engines.twenty tanto en la carga del tarball como en la instalación en el espacio de trabajo. Si implementas un tarball fuera de banda o instalas desde el marketplace, el servidor sigue garantizando la compatibilidad.

CI/CD automatizado (flujos de trabajo preconfigurados)

Las aplicaciones generadas con twenty app init incluyen de forma predeterminada tres flujos de trabajo de GitHub Actions, en .github/workflows/. La CI se ejecuta sin configuración, la CD requiere un único secreto y la publicación en npm requiere una configuración por única vez de Trusted Publisher de npm.

CI — ci.yml

Ejecuta pruebas de integración en cada push a main y en cada pull request. Qué hace:
  1. Obtiene el código fuente de tu aplicación.
  2. Inicia una instancia de prueba aislada de Twenty usando la acción compuesta twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main.
  3. Habilita Corepack y configura Node.js a partir de tu .nvmrc.
  4. Instala la CLI independiente fijada en el paso Instalar la CLI de Twenty.
  5. Instala las dependencias con yarn install --immutable y, a continuación, ejecuta lint, la comprobación de tipos y las pruebas unitarias.
  6. Ejecuta yarn test, pasando TWENTY_API_URL y TWENTY_API_KEY de la instancia iniciada para que tus pruebas puedan comunicarse con un servidor real.
Ajustes de configuración:
  • TWENTY_VERSION (variable de entorno; por defecto latest) — fija la versión del servidor de Twenty usada en CI editando esto en ci.yml.
  • La concurrencia se agrupa por github.ref y cancela las ejecuciones en progreso cuando hay nuevos pushes.
No se requieren secretos — la instancia de prueba es efímera y existe solo durante la ejecución del trabajo.

CD — cd.yml

Despliega tu aplicación en un servidor de Twenty configurado en cada push a main y, opcionalmente, desde un pull request cuando se aplica la etiqueta deploy. Qué hace:
  1. Obtiene el head del PR (para PR etiquetados) o el commit enviado.
  2. Ejecuta twentyhq/twenty/.github/actions/deploy-twenty-app@main — el equivalente en CI de twenty app publish --private.
  3. Ejecuta twentyhq/twenty/.github/actions/install-twenty-app@main para que la versión recién desplegada se instale en el espacio de trabajo de destino.
Configuración necesaria:
La TWENTY_DEPLOY_URL predeterminada de http://localhost:2020 es un marcador de posición — no alcanzará nada desde un runner alojado por GitHub. Actualízala a la URL pública de tu servidor (o usa un runner autohospedado con acceso a la red) antes de habilitar CD.
Activar un despliegue de vista previa desde un PR: Añade la etiqueta deploy a un pull request. La condición if: en cd.yml ejecutará el trabajo para ese PR usando el commit head del PR, lo que te permitirá validar un cambio en el servidor de destino antes de hacer merge.

Publicar — publish.yml

Publica tu aplicación en npm con procedencia cuando haces push de una etiqueta de versión (por ejemplo, v1.0.0), o cuando ejecutas el flujo de trabajo manualmente desde la pestaña Actions. Qué hace:
  1. Hace checkout de tu aplicación, configura Node.js y actualiza npm (la publicación de confianza requiere npm 11.5.1 o posterior).
  2. Instala la CLI independiente fijada en el paso Instalar la CLI de Twenty y, a continuación, instala las dependencias de la aplicación con yarn install --immutable.
  3. Ejecuta twenty app publish, que compila y empaqueta una instantánea aislada de la aplicación y, a continuación, la publica en npm. En CI agrega automáticamente --provenance y --access public, por lo que no se necesitan banderas en el flujo de trabajo.
Configuración única: En npmjs.com abre tu paquete > Settings → Trusted Publisher y registra este repositorio con el flujo de trabajo publish.yml (consulta la documentación de publicación de confianza de npm). La publicación con procedencia certifica qué repositorio de GitHub creó el paquete. Después de publicar, reclama la propiedad en Twenty.
npm solo acepta procedencia de repositorios de código fuente públicos. Si publicas desde un repositorio privado, npm rechaza el paquete de procedencia OIDC con un E422 ... Visibilidad del repositorio de origen de GitHub Actions no compatible: "private" error. Para publicar desde un repositorio privado, excluya la procedencia configurando TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true' en el env del paso de publicación (se incluye una sugerencia comentada en el archivo publish.yml generado automáticamente):
Sin procedencia de GitHub, el paquete no se puede reclamar mediante Reclamar con GitHub. Usa un repositorio público con procedencia si necesitas este flujo de propiedad.

Fijar la versión de la CLI

Los tres flujos de trabajo generados fijan la CLI independiente a la versión de twenty que ejecutó twenty app init. Los pasos Instalar la CLI de Twenty en ci.yml y publish.yml usan npm install -g twenty@\<version>. En cd.yml, tanto las acciones de implementación como de instalación reciben la misma versión mediante su entrada cli-version. Para actualizar, actualiza conjuntamente los dos comandos de instalación y ambas entradas cli-version. Estas fijaciones son independientes de la versión del servidor TWENTY_VERSION utilizada en CI y de las referencias a acciones reutilizables que aparecen a continuación.

Fijar las acciones reutilizables

Los flujos de trabajo ci.yml y cd.yml hacen referencia a acciones reutilizables en @main, por lo que las actualizaciones de acciones en el repositorio twentyhq/twenty se aplican automáticamente. Si quieres compilaciones deterministas, reemplaza @main por un SHA de commit o una etiqueta de versión en cada línea uses:.

Publicación en npm

Publicarla en npm hace que tu aplicación sea apta para el marketplace de Twenty. Tras la sincronización del catálogo y cualquier configuración de rutas del servidor necesaria, los espacios de trabajo pueden buscarla, instalarla y actualizarla desde la interfaz de usuario una vez que supere la revisión del marketplace.

Requisitos

  • Una cuenta de npm
  • La palabra clave twenty-app en tu matriz keywords de package.json (agrégala manualmente — no se incluye de forma predeterminada en la plantilla twenty app init)

Metadatos del Marketplace

La configuración de defineApplication() admite campos opcionales que controlan cómo aparece tu aplicación en el marketplace. Usa logo y galleryImages para hacer referencia a imágenes de la carpeta public/:
src/application-config.ts
Consulta el acordeón de defineApplication en la página Building Apps para ver la lista completa de campos del marketplace (author, category, aboutDescription, websiteUrl, termsUrl, etc.).

Dimensiones recomendadas de las imágenes de la galería

El marketplace muestra galleryImages en un contenedor fijo de 8:5 (por ejemplo, 1600×1000 px).
Las imágenes de la galería de cualquier relación de aspecto se muestran completas y nunca se recortan, pero las que sean significativamente más altas o más estrechas que 8:5 mostrarán franjas vacías a los lados.

Límite de tamaño de imagen

El logo y cada archivo de galleryImages no deben superar los 10 MB. Los archivos más grandes se omiten cuando el marketplace vuelve a alojar tus recursos publicados, por lo que no se mostrarán.

Publicar

Para publicar con una dist-tag específica (p. ej., beta o next):

Cómo funciona el descubrimiento en el marketplace

El servidor de Twenty sincroniza su catálogo del marketplace desde el registro de npm cada hora. La CLI independiente no tiene ningún comando de sincronización de catálogo. Espera a la sincronización del catálogo del servidor o usa las herramientas de administración del servidor. Los metadatos que se muestran en el marketplace provienen de tu configuración de defineApplication(); consulta Metadatos del marketplace arriba.
Si tu aplicación no define un aboutDescription en defineApplication(), el marketplace usará automáticamente el README.md de tu paquete en npm como el contenido de la página Acerca de. Esto significa que puedes mantener un único README tanto para npm como para el marketplace de Twenty. Si quieres una descripción diferente en el marketplace, establece explícitamente aboutDescription.La pestaña Acerca de solo muestra texto en markdown. Las imágenes no se muestran, ya sea que utilicen sintaxis de markdown o etiquetas <img>, y el HTML sin procesar, como insignias o bloques \<div align="center">, se muestra como texto sin formato.

Publicación en CI

El flujo de trabajo publish.yml generado automáticamente descrito arriba publica en npm de forma automática en las etiquetas de versión, con provenance. Como twenty app publish añade --provenance y --access public por ti cuando se ejecuta en CI, el flujo de trabajo no necesita indicadores de npm — solo la configuración única del publicador de confianza. Para otros sistemas de CI (GitLab CI, CircleCI, etc.), ejecuta yarn install y luego twenty app publish. La provenance se emite cuando el entorno puede generar un token OIDC y, en caso contrario, se omite automáticamente.
La procedencia de npm añade una insignia de confianza a tu ficha de npm, permitiendo que los usuarios verifiquen que el paquete se compiló a partir de un commit específico en una canalización de CI pública. También es lo que te permite reclamar la propiedad de tu aplicación en un marketplace de Twenty. Consulta la documentación de procedencia de npm para obtener más información.
Después de que el paquete se haya sincronizado con el catálogo, continúa con Reclamar tu aplicación. El flujo de reclamación requiere una procedencia que apunte a un repositorio de GitHub.

Reclamar tu aplicación

La reclamación asigna el registro de tu aplicación al espacio de trabajo de Twenty que la administrará. La reclamación de aplicaciones está disponible para todos los espacios de trabajo. Tu rol necesita los permisos de Workspace Apps y Developers para reclamar mediante la pestaña Apps de Settings > Developers. La propiedad es por instancia de Twenty: reclamar en Twenty Cloud no reclama la aplicación en un servidor autohospedado independiente. Otros espacios de trabajo de la misma instancia instalan tu aplicación sin tener que reclamarla por sí mismos.

Antes de reclamar

  • Publica tu paquete desde un repositorio público de GitHub mediante GitHub Actions y publicación de confianza de npm con procedencia. La versión importada en el catálogo de Twenty debe incluir la certificación de procedencia.
  • Incluye la palabra clave twenty-app en package.json y espera la sincronización del catálogo.
  • Elige el espacio de trabajo que será propietario de la aplicación. Para aplicaciones con rutas de servidor, este espacio de trabajo también ejecuta y paga el resolvedor compartido.
  • Inicia sesión en GitHub como la cuenta personal propietaria del repositorio de origen o como un propietario de la organización que es propietaria de él. El acceso como colaborador del repositorio o como responsable del paquete npm por sí solo no es suficiente.

Reclamar con GitHub

  1. En el espacio de trabajo del propietario previsto, ve a Configuración > Desarrolladores > Aplicaciones (/settings/developers#apps).
  2. En Reclamar una aplicación, introduce el nombre exacto del paquete npm, incluido su ámbito (por ejemplo, @your-org/twenty-app), o el universalIdentifier de la aplicación.
  3. Haz clic en Buscar y comprueba que el resultado sea tu aplicación. Si no se encuentra, haz clic en Sincronizar catálogo si está disponible, espera a que finalice la sincronización y vuelve a buscarla.
  4. Haz clic en Reclamar con GitHub y autoriza a Twenty. Para un repositorio propiedad de una organización, concede acceso a esa organización en la sección Acceso a la organización de GitHub. Los repositorios personales no necesitan una concesión de organización.
  5. Cuando regreses a Twenty, confirma que la aplicación aparezca en Mis aplicaciones con el tipo NPM. Ábrela y comprueba Distribución > Propiedad para ver Reclamada por este espacio de trabajo.
Reclamar la aplicación no la instala. Si expone rutas de servidor, completa la configuración siguiente antes de que otros espacios de trabajo dependan de sus webhooks.

Configurar rutas de servidor

Una ruta de servidor recibe eventos de varios espacios de trabajo en una URL. Su resolvedor se ejecuta en el espacio de trabajo propietario del registro y luego distribuye el trabajo al espacio de trabajo instalado correspondiente.
  1. Abre tu aplicación en Mis aplicaciones y completa las Variables de servidor requeridas en la pestaña Configuración.
  2. En Distribución, haz clic en Ver en el marketplace para abrir la página de la aplicación e instalarla en el espacio de trabajo propietario. Puedes abrir esta página incluso antes de que la aplicación aparezca en la búsqueda del marketplace.
  3. Registra la URL del webhook del servidor con tu proveedor y prueba un evento desde un segundo espacio de trabajo en el que esté instalada la aplicación. Revisa los registros tanto del resolvedor como de la función de destino.
Una aplicación sin reclamar, o una aplicación no instalada en el espacio de trabajo de su propietario, no tiene ningún resolvedor de rutas del servidor que ejecutar. Las solicitudes devuelven 404 (LOGIC_FUNCTION_NOT_FOUND), incluso si la aplicación está instalada en otros espacios de trabajo. Estas aplicaciones no aparecen en las búsquedas del marketplace hasta que se reclaman, se instalan en el espacio de trabajo del propietario y se configuran con todas las variables de servidor requeridas.

Costes y disponibilidad del espacio de trabajo propietario

Consulta cómo se miden las ejecuciones de funciones lógicas para ver el consumo de créditos, los precios y qué espacio de trabajo recibe la facturación. Desinstalar la aplicación del espacio de trabajo propietario o eliminar ese espacio de trabajo elimina el resolvedor compartido e interrumpe los webhooks del servidor de todas las instalaciones de esa instancia.

Propiedad después de mover un repositorio

Mover el repositorio de GitHub a otra cuenta personal u organización no transfiere ni elimina una reclamación existente de Twenty. El registro permanece vinculado a su espacio de trabajo propietario. Mantén el mismo paquete npm y universalIdentifier de la aplicación; cambiar el espacio de trabajo propietario de Twenty requiere una transferencia de propiedad independiente.

Solución de problemas de una reclamación

Si tienes problemas para reclamar tu aplicación, contáctanos en Discord o abre una incidencia en GitHub.
El administrador del servidor configura APP_CLAIM_GITHUB_CLIENT_ID y APP_CLAIM_GITHUB_CLIENT_SECRET con una aplicación OAuth de GitHub. Establece su URL de devolución de llamada de autorización en tu SERVER_URL seguida de /application-registration-claim/github/callback, por ejemplo https://twenty.example.com/application-registration-claim/github/callback. Esta configuración ya está gestionada por ti en Twenty Cloud.

Visibilidad y revisión en Marketplace

Todas las aplicaciones incluidas en Marketplace han superado la revisión de seguridad y calidad de Twenty. Una aplicación recién publicada permanece sin listar hasta que supera la revisión del marketplace; reclamarla establece la propiedad, pero no la incluye en la lista. Una aplicación sin listar aún se puede instalar. En Configuración > Aplicaciones > Marketplace, abre el filtro y activa Mostrar aplicaciones sin listar, o comparte la página de instalación directa de la aplicación mediante Mis aplicaciones > tu aplicación > Distribución > Copiar enlace para compartir. Los espacios de trabajo ven una advertencia de que la aplicación no ha sido revisada por Twenty. Si tu aplicación está incluida en la lista pero aún no aparece en Marketplace, confirma que la sincronización del catálogo se haya completado, que se hayan rellenado todas las variables de servidor necesarias y que se haya completado cualquier configuración de rutas del servidor.

Instalar aplicaciones

Una vez que una aplicación esté publicada (npm) o desplegada (tarball), los espacios de trabajo pueden instalarla a través de la interfaz de usuario. Ve a la página Configuración > Aplicaciones en Twenty, donde se pueden explorar e instalar tanto las aplicaciones del marketplace como las desplegadas mediante tarball. Desde el directorio de la aplicación, instala su versión publicada en el espacio de trabajo de destino:
Usa el nombre del remoto para el espacio de trabajo donde quieres instalar la aplicación. Para instalar sin un proyecto local, pasa --universal-identifier \<id>.
El servidor aplica el versionado semver al instalar, reflejando las reglas del despliegue:
  • Instalar la misma versión que ya está instalada en tu espacio de trabajo se rechaza con un error APP_ALREADY_INSTALLED.
  • Instalar una versión inferior a la que está instalada actualmente se rechaza con un error CANNOT_DOWNGRADE_APPLICATION.
Para instalar una versión más reciente, primero despliégala o publícala y luego vuelve a ejecutar twenty app install --remote production.