github-actions[bot]
2b3b2362db
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
177 lines
11 KiB
Plaintext
177 lines
11 KiB
Plaintext
---
|
|
title: Inicio rápido
|
|
icon: rocket
|
|
description: Crea tu primera aplicación de Twenty en minutos.
|
|
---
|
|
|
|
## Prerrequisitos
|
|
|
|
* **Node.js 24+** — [Descargar](https://nodejs.org/)
|
|
* **Yarn 4** — incluido con Node.js a través de Corepack. Actívalo: `corepack enable`
|
|
* **Docker** — [Descargar](https://www.docker.com/products/docker-desktop/). Necesario para ejecutar un servidor local de Twenty. Omítelo si ya tienes Twenty ejecutándose en otro lugar.
|
|
|
|
La creación de una app de Twenty tiene tres fases. El generador las combina en un único comando de ruta ideal, pero cada fase es un concepto independiente — cuando algo falla, saber en qué fase estás te indica qué debes corregir.
|
|
|
|
| Fase | Qué haces | Herramienta | Resultado |
|
|
| --------------------------- | --------------------------------------------------- | ----------------------------- | ------------------------------------ |
|
|
| **1. Generar estructura** | Genera el código fuente de la app | `npx create-twenty-app` | Un proyecto de TypeScript en disco |
|
|
| **2. Ejecutar un servidor** | Inicia un servidor de Twenty con el que sincronizar | Docker + `yarn twenty server` | Una instancia de Twenty en ejecución |
|
|
| **3. Sincronizar** | Sincroniza en vivo tu código con el servidor | `yarn twenty dev` | Tus cambios aparecen en la UI |
|
|
|
|
---
|
|
|
|
## Fase 1 — Genera la estructura de tu proyecto
|
|
|
|
Crea una app nueva a partir de la plantilla:
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app
|
|
```
|
|
|
|
Se te pedirá un nombre y una descripción — pulsa **Enter** para usar los valores predeterminados. Esto genera un proyecto de TypeScript en `my-twenty-app/` con un `application-config.ts` inicial, un rol predeterminado, un flujo de trabajo de CI y una prueba de integración.
|
|
|
|
**Después de esta fase:** tienes el código fuente de tu app en tu máquina. Aún no se está ejecutando — esa es la Fase 2.
|
|
|
|
---
|
|
|
|
## Fase 2 — Ejecuta un servidor local de Twenty
|
|
|
|
Tu app necesita un servidor de Twenty con el que sincronizar. El servidor es una instancia completa de Twenty — UI, API GraphQL, PostgreSQL — ejecutándose localmente en Docker. Tu código local sube sus definiciones a ese servidor, lo que hace que aparezcan en la UI.
|
|
|
|
El generador ofrece iniciar uno por ti:
|
|
|
|
> **¿Te gustaría configurar una instancia local de Twenty?**
|
|
|
|
* **Sí (recomendado)** — descarga la imagen de Docker `twentycrm/twenty-app-dev` y la inicia en el puerto `2020`. Asegúrate de que Docker esté en ejecución antes.
|
|
* **No** — elige esto si ya tienes un servidor de Twenty al que te quieres conectar. Puedes conectarlo más tarde con `yarn twenty remote:add`.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="¿Debería iniciar una instancia local?" />
|
|
</div>
|
|
|
|
Una vez que el servidor esté en marcha, se abrirá un navegador para iniciar sesión. Inicia sesión con la cuenta de demostración precargada:
|
|
|
|
* **Correo electrónico:** `tim@apple.dev`
|
|
* **Contraseña:** `tim@apple.dev`
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/login.png" alt="Pantalla de inicio de sesión de Twenty" />
|
|
</div>
|
|
|
|
Haz clic en **Authorize** en la siguiente pantalla — esto le da a la CLI acceso a tu espacio de trabajo.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Pantalla de autorización de la CLI de Twenty" />
|
|
</div>
|
|
|
|
Tu terminal confirmará que todo está configurado.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/scaffolded.png" alt="Aplicación generada correctamente" />
|
|
</div>
|
|
|
|
**Después de esta fase:** tienes un servidor de Twenty en ejecución en [http://localhost:2020](http://localhost:2020) con tu CLI autorizada para sincronizar con él.
|
|
|
|
<Note>
|
|
Si Docker no está instalado o en ejecución, el generador te indicará el comando de inicio correcto para tu sistema operativo. Una vez que Docker esté en marcha, puedes reanudar con `yarn twenty docker:start` — no es necesario volver a generar la estructura.
|
|
</Note>
|
|
|
|
---
|
|
|
|
## Fase 3 — Sincroniza tus cambios
|
|
|
|
Este es el ciclo interno en el que pasarás la mayor parte del tiempo.
|
|
|
|
```bash filename="Terminal"
|
|
cd my-twenty-app
|
|
yarn twenty dev
|
|
```
|
|
|
|
Esto observa `src/`, recompila en cada cambio y sincroniza el resultado con el servidor. Edita un archivo, guarda y, en cuestión de unos segundos, el servidor reflejará el cambio. Verás un panel de estado en vivo en tu terminal.
|
|
|
|
Para una salida más detallada (registros de compilación, solicitudes de sincronización, trazas de errores), añade `--verbose`.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/dev.png" alt="Salida del modo de desarrollo en la terminal" />
|
|
</div>
|
|
|
|
Abre [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer) en tu navegador. Deberías ver tu app listada en **Your Apps**.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Lista de Your Apps que muestra My twenty app" />
|
|
</div>
|
|
|
|
Haz clic en **My twenty app** para ver su **registro de la aplicación** — un registro a nivel de servidor que describe tu app (nombre, identificador, credenciales de OAuth, origen). Un único registro puede instalarse en varios espacios de trabajo del mismo servidor.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Detalles del registro de la aplicación" />
|
|
</div>
|
|
|
|
Haz clic en **View installed app** para ver la instalación en el espacio de trabajo. La pestaña **About** muestra la versión actual y las opciones de gestión.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Aplicación instalada" />
|
|
</div>
|
|
|
|
**Después de esta fase:** tienes un ciclo de desarrollo en vivo. Edita cualquier archivo en `src/` y aparecerá en la UI.
|
|
|
|
### Sincronización de una sola vez para CI y scripts
|
|
|
|
Pasa `--once` para ejecutar una sola compilación + sincronización y salir — mismo pipeline, sin watcher:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty dev --once
|
|
```
|
|
|
|
| Comando | Comportamiento | Cuándo usarlo |
|
|
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
|
|
| `yarn twenty dev` | Supervisa tus archivos fuente y vuelve a sincronizar en cada cambio. Se ejecuta hasta que lo detengas. | Desarrollo local interactivo. |
|
|
| `yarn twenty dev --once` | Realiza una sola compilación + sincronización y luego sale con el código `0` si tiene éxito o `1` si falla. | CI, hooks de pre-commit, agentes de IA, flujos de trabajo con scripts. |
|
|
| `yarn twenty dev --once --dry-run` | Genera y muestra los cambios de metadatos **sin aplicarlos**. | Inspeccionar qué cambiaría una sincronización antes de confirmarla. |
|
|
|
|
Ambos modos necesitan un remoto autenticado. Consulta [Sincronización y recuperación](/l/es/developers/extend/apps/operations/sync-and-recovery#previewing-changes-dry-run) para obtener más información sobre `--dry-run`.
|
|
|
|
### Opciones del modo de desarrollo
|
|
|
|
| Opción | Descripción |
|
|
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
| `--once` | Compila y sincroniza una vez y luego finaliza. |
|
|
| `--dry-run` | Con `--once`, obtén una vista previa de los cambios de metadatos sin aplicarlos. No escribe nada. |
|
|
| `--debounceMs \<ms>` | Establece el tiempo de antirrebote para los cambios de archivo en milisegundos (valor predeterminado: `2000`). |
|
|
| `--verbose` / `--debug` | Muestra registros de compilación detallados, solicitudes de sincronización y seguimientos de errores. |
|
|
|
|
## Lo que puedes crear
|
|
|
|
Las apps se componen de **entidades** — cada una definida como un archivo de TypeScript con un único `export default`:
|
|
|
|
| Entidad | Qué hace |
|
|
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
| **Objetos y campos** | Modelos de datos personalizados (Post Card, Invoice, etc.). con campos tipados |
|
|
| **Funciones de lógica** | Funciones de TypeScript del lado del servidor activadas por rutas HTTP, programaciones de cron o eventos de base de datos |
|
|
| **Componentes de frontend** | Componentes de React que se renderizan dentro de la interfaz de Twenty (panel lateral, widgets, menú de comandos) |
|
|
| **Habilidades y agentes** | Capacidades de IA — instrucciones reutilizables y asistentes autónomos |
|
|
| **Vistas y navegación** | Vistas de lista preconfiguradas y elementos del menú lateral |
|
|
| **Diseños de página** | Páginas de detalle de registros personalizadas con pestañas y widgets |
|
|
|
|
Referencia completa: [Conceptos](/l/es/developers/extend/apps/getting-started/concepts).
|
|
|
|
## Próximos pasos
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Configuración" icon="screwdriver-wrench" href="/l/es/developers/extend/apps/config/overview">
|
|
Identidad de la aplicación, rol predeterminado, hooks de instalación y recursos públicos.
|
|
</Card>
|
|
<Card title="Datos" icon="database" href="/l/es/developers/extend/apps/data/overview">
|
|
Objetos, campos y relaciones bidireccionales.
|
|
</Card>
|
|
<Card title="Lógica" icon="bolt" href="/l/es/developers/extend/apps/logic/overview">
|
|
Funciones de lógica, habilidades, agentes y conexiones OAuth.
|
|
</Card>
|
|
<Card title="Diseño" icon="table-columns" href="/l/es/developers/extend/apps/layout/overview">
|
|
Vistas, navegación, diseños de página y componentes de frontend.
|
|
</Card>
|
|
<Card title="Operaciones" icon="rocket" href="/l/es/developers/extend/apps/operations/overview">
|
|
CLI, pruebas, remotos, CI y publicación de tu aplicación.
|
|
</Card>
|
|
</CardGroup>
|