Skip to content

The open alternative to Salesforce, designed for AI.

10.7 KB
Raw Blame
---
title: Estructura del proyecto
description: Qué hay dentro de una app de Twenty generada mediante scaffolding — archivos, carpetas y lo que hace cada uno.
---

import { PageBanner } from "/snippets/page-banner.mdx"

## Resumen

Una nueva app generada por `twenty app init` se ve así:

```text filename="my-twenty-app/"
my-twenty-app/
  package.json
  yarn.lock                                 # Created by app init; used by yarn install
  src/
    application-config.ts                   # Required — your app's entry point
    default-role.ts                         # Permissions for logic functions
    constants/
      universal-identifiers.ts              # Auto-generated UUIDs and metadata
    front-components/
      main-page.tsx                         # Welcome page component
    logic-functions/
      health-check.ts                       # Reports whether the app can run
    navigation-menu-items/
      main-page.navigation-menu-item.ts     # Sidebar entry for the welcome page
    page-layouts/
      main-page.page-layout.ts              # Standalone page hosting the component
    __tests__/
      application-config.test.ts            # Unit test
      global-setup.ts                       # Integration test setup (sync + uninstall)
      run-twenty.ts                         # CLI subprocess helper for tests
      schema.integration-test.ts            # Integration test against a live server
  .github/workflows/
    ci.yml                                  # Lint, typecheck, unit + integration tests
    cd.yml                                  # Deploy + install on push to main
    publish.yml                             # Publish to npm on version tags (with provenance)
  public/
    logo.svg                                # Static assets
  locales/
    en.json                                 # Source catalog; add <locale>.json files next to it
  vitest.config.ts                          # Integration test runner config
  vitest.unit.config.ts                     # Unit test runner config
  tsconfig.json, tsconfig.spec.json
  .nvmrc, .yarnrc.yml, .oxlintrc.json
  README.md, AGENTS.md, CLAUDE.md, CHANGELOG.md, SETUP.md
```

## Archivos clave

| Archivo / Carpeta                                                          | Propósito                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `src/application-config.ts`                                                | **Obligatorio.** El archivo de configuración principal de tu app.                                                                                                                                                                                                                                                                                                                                                                                        |
| `src/default-role.ts`                                                      | Rol predeterminado que controla a qué pueden acceder tus funciones lógicas.                                                                                                                                                                                                                                                                                                                                                                              |
| `src/constants/universal-identifiers.ts`                                   | UUIDs generados automáticamente y metadatos de la app (nombre para mostrar, descripción).                                                                                                                                                                                                                                                                                                                                                                |
| `src/front-components/`, `src/navigation-menu-items/`, `src/page-layouts/` | Una página de bienvenida inicial: un front component renderizado por un page layout independiente, accesible desde la barra lateral.                                                                                                                                                                                                                                                                                                                     |
| `src/logic-functions/health-check.ts`                                      | Una [comprobación de estado](/es/developers/extend/apps/logic/logic-functions#health-check) inicial que informa `ok`. Complétala para mostrar problemas de configuración que solo tu aplicación puede detectar.                                                                                                                                                                                                                                             |
| `src/__tests__/`                                                           | Una prueba unitaria más una prueba de integración (con su configuración global) que sincroniza la aplicación contra un servidor real.                                                                                                                                                                                                                                                                                                                    |
| `public/`                                                                  | Recursos estáticos (imágenes, fuentes) servidos con tu app.                                                                                                                                                                                                                                                                                                                                                                                              |
| `locales/`                                                                 | Catálogos de traducción. `en.json` es el catálogo fuente que completa `twenty app translations extract`; el conjunto de archivos aquí es lo que publica una sincronización, por lo que una carpeta vacía declara que no hay traducciones. `locales/compiled/` es escrito por `twenty app pull` para las entradas cuyas cadenas fuente aún no están en el árbol, también es publicado por una sincronización y no está pensado para editarse manualmente. |
| `AGENTS.md` / `CLAUDE.md`                                                  | Guía para agentes de IA para programación que trabajan en la aplicación.                                                                                                                                                                                                                                                                                                                                                                                 |
| `CHANGELOG.md` / `SETUP.md`                                                | Registro de cambios destacados e instrucciones de configuración para el desarrollo local.                                                                                                                                                                                                                                                                                                                                                                |

<Note>
  **La organización de archivos depende de ti.** Las carpetas anteriores son convenciones — el
  CLI detecta entidades mediante análisis AST en llamadas a `export default defineEntity(...)`
  sin importar dónde se encuentre el archivo.
</Note>

## Dependencias

`twenty app init` coloca `twenty-sdk`, `twenty-client-sdk` y `twenty-ui` en `devDependencies`, fijados a la versión del SDK seleccionada por esa versión de la CLI. Conserva las versiones generadas para una aplicación nueva y mantén los tres paquetes sincronizados al actualizar. La CLI puede recibir versiones de parche de forma independiente, por lo que su versión no tiene por qué coincidir con la de estos paquetes.

El `engines.twenty` generado establece la versión mínima del servidor en la versión principal y secundaria de ese SDK. Los Workflows generados de GitHub Actions fijan la CLI por separado.

* **`twenty-sdk`** proporciona definiciones de apps, asistentes de tiempo de ejecución e integración del renderizador. Usa el paquete **`twenty`** instalado por separado para los comandos de CLI y las herramientas de compilación/generación de estructura.
* **`twenty-client-sdk`** *sí* es importado por el código de tu app (`CoreApiClient`, `MetadataApiClient`, `RestApiClient`), pero Twenty lo proporciona en tiempo de ejecución: las funciones lógicas lo obtienen de una capa SDK generada y los componentes de front lo resuelven desde módulos servidos por el servidor. Tu copia instalada solo se utiliza para la comprobación de tipos y el build en tiempo de despliegue, por lo que nunca necesita incluirse en el bundle desplegado.

Mantener cualquiera de los paquetes bajo `dependencies` lo introduce en el bundle de runtime de la app instalada, donde es peso muerto. `twenty app build` emite una advertencia cuando cualquiera de los dos sigue listado en `dependencies`.

Añade las dependencias de runtime propias de tu app (las bibliotecas que tus funciones lógicas realmente importan en tiempo de ejecución) bajo `dependencies` como de costumbre. Mantén el árbol ligero: las `dependencies` se instalan en una capa de tiempo de ejecución con un límite de 250 MB sin comprimir, y una sincronización o instalación falla con un error de tamaño de dependencias si se supera ese límite — las bibliotecas de UI y las herramientas de desarrollo pertenecen a `devDependencies`.

<PageBanner illustration="card-page-frontend-architecture" />