github-actions[bot]
ad3291f4b4
Created by Github action <!-- This is an auto-generated description by cubic. --> <a href="https://cubic.dev/pr/twentyhq/twenty/pull/23338?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. --> Co-authored-by: github-actions <github-actions@twenty.com>
124 lines
9.3 KiB
Plaintext
124 lines
9.3 KiB
Plaintext
---
|
||
title: Configuración de la aplicación
|
||
description: Declara la identidad de tu aplicación, el rol predeterminado, las variables y los metadatos del marketplace con defineApplication.
|
||
icon: rocket
|
||
---
|
||
|
||
Cada aplicación debe tener exactamente una llamada a `defineApplication`. Declara:
|
||
|
||
* **Identidad** — identificador universal, nombre para mostrar, descripción.
|
||
* **Permisos** — bajo qué rol se ejecutan sus funciones de lógica y componentes de frontend.
|
||
* **Variables** *(opcionales)* — pares clave–valor expuestos a tu código como variables de entorno.
|
||
* **Hooks de preinstalación / posinstalación / desinstalación** *(opcionales)* — consulta [Funciones de lógica](/l/es/developers/extend/apps/logic/logic-functions).
|
||
|
||
```ts src/application-config.ts
|
||
import { defineApplication } from 'twenty-sdk/define';
|
||
|
||
export default defineApplication({
|
||
universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
|
||
displayName: 'My Twenty App',
|
||
description: 'My first Twenty app',
|
||
applicationVariables: {
|
||
DEFAULT_RECIPIENT_NAME: {
|
||
universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
|
||
description: 'Default recipient name for postcards',
|
||
value: 'Jane Doe',
|
||
isSecret: false,
|
||
},
|
||
},
|
||
});
|
||
```
|
||
|
||
Notas:
|
||
|
||
* Los campos `universalIdentifier` son identificadores deterministas que te pertenecen. Genéralos una vez y mantenlos estables entre sincronizaciones.
|
||
* `applicationVariables` se convierten en variables de entorno para tus funciones y componentes de frontend. En las funciones lógicas (del lado del servidor), están disponibles como `process.env.VARIABLE_NAME`. En los componentes de frontend, usa `getApplicationVariable('VARIABLE_NAME')` de `twenty-sdk/front-component`. Las variables marcadas con `isSecret: true` solo se inyectan en las funciones lógicas. Los componentes de frontend solo reciben variables no secretas.
|
||
* El rol predeterminado se detecta automáticamente a partir del archivo de rol marcado con [`defineApplicationRole()`](/l/es/developers/extend/apps/config/roles); no necesitas hacer referencia a él desde `defineApplication()`.
|
||
* Las funciones de preinstalación, posinstalación y desinstalación se detectan automáticamente durante la compilación del manifiesto; no necesitas referenciarlas en `defineApplication()`.
|
||
* Pasar `defaultRoleUniversalIdentifier` explícitamente sigue siendo compatible por motivos de retrocompatibilidad, pero está en desuso en favor de `defineApplicationRole()`.
|
||
* `serverVariables` son configuraciones y secretos con ámbito de instancia (por ejemplo, claves de API). A diferencia de `applicationVariables`, no declaran ningún valor en el manifiesto: el operador del espacio de trabajo los completa desde la configuración de la aplicación, y se inyectan en las funciones lógicas solo una vez que se han establecido.
|
||
* Para mostrar una interfaz de configuración personalizada dentro de la pestaña **Settings** de la aplicación (en lugar de la sección predeterminada de configuración de variables), declara un componente de frontend con [`defineSettingsFrontComponent()`](/l/es/developers/extend/apps/layout/front-components#custom-settings-component) en su propio archivo. Solo se permite uno por aplicación. Las secciones gestionadas por el sistema (actualización automática, App URL, conexiones) siempre permanecen visibles.
|
||
|
||
## Tipos de variables
|
||
|
||
Tanto `applicationVariables` como `serverVariables` aceptan un `type` opcional (y, para `SELECT` / `MULTI_SELECT`, una lista de `options`). Tipos admitidos: `TEXT` (predeterminado), `BOOLEAN`, `NUMBER`, `NUMERIC`, `DATE`, `DATE_TIME`, `SELECT`, `MULTI_SELECT`, `ARRAY`, `RAW_JSON`, `RICH_TEXT`.
|
||
|
||
```ts src/application-config.ts
|
||
import { defineApplication, FieldType } from 'twenty-sdk/define';
|
||
|
||
export default defineApplication({
|
||
// ...identity, role...
|
||
applicationVariables: {
|
||
MAX_POSTCARDS: {
|
||
universalIdentifier: '5f4497e4-9030-4085-85eb-2c48b8d53713',
|
||
description: 'Maximum postcards per batch',
|
||
type: FieldType.NUMBER,
|
||
value: 10,
|
||
},
|
||
DEFAULT_REGION: {
|
||
universalIdentifier: '76c5c321-b6b6-46eb-b4fc-f9f04bb04227',
|
||
description: 'Default shipping region',
|
||
type: FieldType.SELECT,
|
||
options: [
|
||
{ label: 'Europe', value: 'eu' },
|
||
{ label: 'United States', value: 'us' },
|
||
],
|
||
value: 'eu',
|
||
},
|
||
},
|
||
});
|
||
```
|
||
|
||
El `type` solo afecta a la **presentación y validación**: selecciona la entrada correspondiente en la interfaz de configuración del espacio de trabajo (un interruptor, campo numérico, lista desplegable, selector de fecha, editor JSON, …) y permite que la compilación valide tu configuración (por ejemplo, `SELECT` / `MULTI_SELECT` deben declarar `options` no vacías). **No** cambia cómo el valor llega a tu código.
|
||
|
||
Los valores **siempre se inyectan como cadenas**; esto es inherente a las variables de entorno (`process.env.*` solo admite cadenas). Cuando se ejecuta tu función lógica, el ejecutor serializa cada valor según su `type` declarado al construir `process.env`, por lo que el formato de cadena es coherente independientemente de cómo se haya establecido el valor (valor predeterminado del manifiesto, interfaz de configuración o una versión anterior):
|
||
|
||
| Tipo | Cadena de `process.env` |
|
||
| ------------------------------------- | ---------------------------------------------- |
|
||
| `TEXT`, `SELECT`, `DATE`, `DATE_TIME` | el valor sin procesar (`"eu"`, `"2026-01-01"`) |
|
||
| `BOOLEAN` | `"true"` / `"false"` |
|
||
| `NUMBER`, `NUMERIC` | cadena decimal (`"10"`, `"2.5"`) |
|
||
| `MULTI_SELECT`, `ARRAY` | Array JSON (`'["email","postcard"]'`) |
|
||
| `RAW_JSON`, `RICH_TEXT` | Objeto JSON (`'{"retries":3}'`) |
|
||
|
||
Analiza la cadena para volver al tipo que esperas:
|
||
|
||
```ts
|
||
const maxCards = Number(process.env.MAX_POSTCARDS); // "10" -> 10
|
||
const enabled = process.env.ENABLE_TRACKING === 'true'; // "true" -> true
|
||
const channels = JSON.parse(process.env.ENABLED_CHANNELS ?? '[]'); // '["email"]' -> ["email"]
|
||
const config = JSON.parse(process.env.PROVIDER_CONFIG ?? '{}'); // '{"retries":3}' -> { retries: 3 }
|
||
```
|
||
|
||
Lo mismo se aplica a los componentes de interfaz que leen valores mediante `getApplicationVariable('VARIABLE_NAME')`: el valor devuelto es una cadena; analízalo según sea necesario.
|
||
|
||
## Rol de función predeterminado
|
||
|
||
El rol declarado con [`defineApplicationRole()`](/l/es/developers/extend/apps/config/roles) controla a qué pueden acceder las funciones de lógica y los componentes de interfaz de la aplicación:
|
||
|
||
* El token en tiempo de ejecución inyectado como `TWENTY_APP_ACCESS_TOKEN` se deriva de este rol.
|
||
* El cliente de API tipado está restringido a los permisos otorgados a ese rol.
|
||
* Sigue el principio de mínimo privilegio: declara solo los permisos que necesitan tus funciones.
|
||
|
||
Cuando generas una nueva aplicación, la CLI crea un archivo de rol inicial en `src/roles/default-role.ts`. Consulta [Roles y permisos](/l/es/developers/extend/apps/config/roles) para obtener la referencia completa.
|
||
|
||
## Metadatos del Marketplace
|
||
|
||
Si planeas [publicar tu aplicación](/l/es/developers/extend/apps/operations/publishing), estos campos opcionales controlan cómo aparece en el marketplace:
|
||
|
||
| Campo | Descripción |
|
||
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `author` | Nombre del autor o de la empresa |
|
||
| `category` | Categoría de la aplicación para el filtrado en el marketplace |
|
||
| `logo` | Ruta al logotipo de tu aplicación incluido en `public/` (p. ej., `public/logo.png`) |
|
||
| `galleryImages` | Arreglo de rutas de imágenes de galería incluidas en `public/` (p. ej., `public/screenshot-1.png`) |
|
||
| `aboutDescription` | Descripción en Markdown más extensa para la pestaña "Acerca de". Si se omite, el marketplace utiliza el `README.md` del paquete en npm |
|
||
| `websiteUrl` | Enlace a tu sitio web |
|
||
| `termsUrl` | Enlace a los términos del servicio |
|
||
| `emailSupport` | Dirección de correo electrónico de soporte |
|
||
| `issueReportUrl` | Enlace al rastreador de incidencias |
|
||
|
||
<Note>
|
||
`logoUrl` y `screenshots` son alias obsoletos de `logo` y `galleryImages`. Las URL absolutas externas (`http://` o `https://`) no son compatibles para estos campos: se descartan con una advertencia en tiempo de compilación. En su lugar, incluye las imágenes en la carpeta `public/` de tu aplicación.
|
||
</Note>
|