982f0c4a4d
Created by Github action --------- Co-authored-by: github-actions <github-actions@twenty.com> Co-authored-by: Charles Bochet <charles@twenty.com>
234 lines
11 KiB
Plaintext
234 lines
11 KiB
Plaintext
---
|
|
title: Primeiros passos
|
|
description: Crie seu primeiro app do Twenty em minutos.
|
|
---
|
|
|
|
<Warning>
|
|
Os aplicativos estão atualmente em testes alfa. O recurso é funcional, mas ainda está evoluindo.
|
|
</Warning>
|
|
|
|
Os apps permitem que você estenda o Twenty com objetos, campos, funções de lógica, habilidades de IA e componentes de UI personalizados — tudo gerenciado como código.
|
|
|
|
**O que você pode fazer hoje:**
|
|
|
|
* Defina objetos e campos personalizados como código (modelo de dados gerenciado)
|
|
* Crie funções de lógica com gatilhos personalizados (rotas HTTP, cron, eventos de banco de dados)
|
|
* Defina habilidades para agentes de IA
|
|
* Crie componentes de front-end que renderizam dentro da UI do Twenty
|
|
* Implemente o mesmo aplicativo em vários espaços de trabalho
|
|
|
|
## Pré-requisitos
|
|
|
|
* Node.js 24+ e Yarn 4
|
|
* Um espaço de trabalho do Twenty e uma chave de API (crie uma em https://app.twenty.com/settings/api-webhooks)
|
|
|
|
## Primeiros passos
|
|
|
|
Crie um novo aplicativo usando o gerador oficial, depois autentique-se e comece a desenvolver:
|
|
|
|
```bash filename="Terminal"
|
|
# Scaffold a new app (includes all examples by default)
|
|
npx create-twenty-app@latest my-twenty-app
|
|
cd my-twenty-app
|
|
|
|
# Start dev mode: automatically syncs local changes to your workspace
|
|
yarn twenty app:dev
|
|
```
|
|
|
|
O gerador de estrutura oferece suporte a dois modos para controlar quais arquivos de exemplo são incluídos:
|
|
|
|
```bash filename="Terminal"
|
|
# Default (exhaustive): all examples (object, field, logic function, front component, view, navigation menu item, skill)
|
|
npx create-twenty-app@latest my-app
|
|
|
|
# Minimal: only core files (application-config.ts and default-role.ts)
|
|
npx create-twenty-app@latest my-app --minimal
|
|
```
|
|
|
|
A partir daqui você pode:
|
|
|
|
```bash filename="Terminal"
|
|
# Add a new entity to your application (guided)
|
|
yarn twenty entity:add
|
|
|
|
# Watch your application's function logs
|
|
yarn twenty function:logs
|
|
|
|
# Execute a function by name
|
|
yarn twenty function:execute -n my-function -p '{"name": "test"}'
|
|
|
|
# Execute the pre-install function
|
|
yarn twenty function:execute --preInstall
|
|
|
|
# Execute the post-install function
|
|
yarn twenty function:execute --postInstall
|
|
|
|
# Uninstall the application from the current workspace
|
|
yarn twenty app:uninstall
|
|
|
|
# Display commands' help
|
|
yarn twenty help
|
|
```
|
|
|
|
Veja também: as páginas de referência da CLI para [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) e [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
|
|
|
|
## Estrutura do projeto (com scaffold)
|
|
|
|
Ao executar `npx create-twenty-app@latest my-twenty-app`, o gerador:
|
|
|
|
* Copia um aplicativo base mínimo para `my-twenty-app/`
|
|
* Adiciona uma dependência local `twenty-sdk` e a configuração do Yarn 4
|
|
* Cria arquivos de configuração e scripts conectados à CLI `twenty`
|
|
* Gera arquivos principais (configuração da aplicação, papel padrão para funções de lógica, funções de pré-instalação e pós-instalação) além de arquivos de exemplo com base no modo de geração de estrutura
|
|
|
|
Um app recém-criado com o modo padrão `--exhaustive` fica assim:
|
|
|
|
```text filename="my-twenty-app/"
|
|
my-twenty-app/
|
|
package.json
|
|
yarn.lock
|
|
.gitignore
|
|
.nvmrc
|
|
.yarnrc.yml
|
|
.yarn/
|
|
install-state.gz
|
|
.oxlintrc.json
|
|
tsconfig.json
|
|
README.md
|
|
public/ # Public assets folder (images, fonts, etc.)
|
|
src/
|
|
├── application-config.ts # Required - main application configuration
|
|
├── roles/
|
|
│ └── default-role.ts # Default role for logic functions
|
|
├── objects/
|
|
│ └── example-object.ts # Example custom object definition
|
|
├── fields/
|
|
│ └── example-field.ts # Example standalone field definition
|
|
├── logic-functions/
|
|
│ ├── hello-world.ts # Example logic function
|
|
│ ├── pre-install.ts # Pre-install logic function
|
|
│ └── post-install.ts # Post-install logic function
|
|
├── front-components/
|
|
│ └── hello-world.tsx # Example front component
|
|
├── views/
|
|
│ └── example-view.ts # Example saved view definition
|
|
├── navigation-menu-items/
|
|
│ └── example-navigation-menu-item.ts # Example sidebar navigation link
|
|
└── skills/
|
|
└── example-skill.ts # Example AI agent skill definition
|
|
```
|
|
|
|
Com `--minimal`, apenas os arquivos principais são criados (`application-config.ts`, `roles/default-role.ts`, `logic-functions/pre-install.ts` e `logic-functions/post-install.ts`).
|
|
|
|
Em alto nível:
|
|
|
|
* **package.json**: Declara o nome do app, versão, engines (Node 24+, Yarn 4), e adiciona `twenty-sdk` além de um script `twenty` que delega para a CLI `twenty` local. Execute `yarn twenty help` para listar todos os comandos disponíveis.
|
|
* **.gitignore**: Ignora artefatos comuns como `node_modules`, `.yarn`, `generated/` (cliente tipado), `dist/`, `build/`, pastas de cobertura, arquivos de log e arquivos `.env*`.
|
|
* **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Bloqueiam e configuram a ferramenta Yarn 4 usada pelo projeto.
|
|
* **.nvmrc**: Fixa a versão do Node.js esperada pelo projeto.
|
|
* **.oxlintrc.json** e **tsconfig.json**: Fornecem lint e configuração do TypeScript para os fontes TypeScript do seu aplicativo.
|
|
* **README.md**: Um README curto na raiz do aplicativo com instruções básicas.
|
|
* **public/**: Uma pasta para armazenar recursos públicos (imagens, fontes, arquivos estáticos) que serão servidos com sua aplicação. Os arquivos colocados aqui são enviados durante a sincronização e ficam acessíveis em tempo de execução.
|
|
* **src/**: O local principal onde você define seu aplicativo como código
|
|
|
|
### Detecção de entidades
|
|
|
|
O SDK detecta entidades analisando seus arquivos TypeScript em busca de chamadas **`export default define<Entity>({...})`**. Cada tipo de entidade tem uma função utilitária correspondente exportada de `twenty-sdk`:
|
|
|
|
| Função utilitária | Tipo de entidade |
|
|
| -------------------------------- | -------------------------------------------------------------------- |
|
|
| `defineObject` | Definições de objetos personalizados |
|
|
| `defineLogicFunction` | Definições de funções de lógica |
|
|
| `definePreInstallLogicFunction` | Função de lógica de pré-instalação (é executada antes da instalação) |
|
|
| `definePostInstallLogicFunction` | Função de lógica de pós-instalação (é executada após a instalação) |
|
|
| `defineFrontComponent` | Definições de componentes de front-end |
|
|
| `defineRole` | Definições de papéis |
|
|
| `defineField` | Extensões de campos para objetos existentes |
|
|
| `defineView` | Definições de visualizações salvas |
|
|
| `defineNavigationMenuItem` | Definições de itens do menu de navegação |
|
|
| `defineSkill` | Definições de habilidades de agente de IA |
|
|
|
|
<Note>
|
|
**A nomeação de arquivos é flexível.** A detecção de entidades é baseada em AST — o SDK varre seus arquivos fonte em busca do padrão `export default define<Entity>({...})`. Você pode organizar seus arquivos e pastas como quiser. Agrupar por tipo de entidade (por exemplo, `logic-functions/`, `roles/`) é apenas uma convenção para organização do código, não um requisito.
|
|
</Note>
|
|
|
|
Exemplo de uma entidade detectada:
|
|
|
|
```typescript
|
|
// This file can be named anything and placed anywhere in src/
|
|
import { defineObject, FieldType } from 'twenty-sdk';
|
|
|
|
export default defineObject({
|
|
universalIdentifier: '...',
|
|
nameSingular: 'postCard',
|
|
// ... rest of config
|
|
});
|
|
```
|
|
|
|
Comandos posteriores adicionarão mais arquivos e pastas:
|
|
|
|
* `yarn twenty app:dev` irá gerar automaticamente dois clientes de API tipados em `node_modules/twenty-sdk/generated`: `CoreApiClient` (para dados do espaço de trabalho via `/graphql`) e `MetadataApiClient` (para configuração do espaço de trabalho e envio de arquivos via `/metadata`).
|
|
* `yarn twenty entity:add` adicionará arquivos de definição de entidade em `src/` para seus objetos, funções, componentes de front-end, papéis e habilidades personalizados, entre outros.
|
|
|
|
## Autenticação
|
|
|
|
Na primeira vez que você executar `yarn twenty auth:login`, será solicitado o seguinte:
|
|
|
|
* URL da API (padrão: http://localhost:3000 ou o perfil do seu espaço de trabalho atual)
|
|
* Chave de API
|
|
|
|
Suas credenciais são armazenadas por usuário em `~/.twenty/config.json`. Você pode manter vários perfis e alternar entre eles.
|
|
|
|
### Gerenciando espaços de trabalho
|
|
|
|
```bash filename="Terminal"
|
|
# Login interactively (recommended)
|
|
yarn twenty auth:login
|
|
|
|
# Login to a specific workspace profile
|
|
yarn twenty auth:login --workspace my-custom-workspace
|
|
|
|
# List all configured workspaces
|
|
yarn twenty auth:list
|
|
|
|
# Switch the default workspace (interactive)
|
|
yarn twenty auth:switch
|
|
|
|
# Switch to a specific workspace
|
|
yarn twenty auth:switch production
|
|
|
|
# Check current authentication status
|
|
yarn twenty auth:status
|
|
```
|
|
|
|
Depois que você alternar os espaços de trabalho com `yarn twenty auth:switch`, todos os comandos subsequentes usarão esse espaço de trabalho por padrão. Você ainda pode substituí-lo temporariamente com `--workspace <name>`.
|
|
|
|
## Configuração manual (sem o gerador)
|
|
|
|
Embora recomendemos usar `create-twenty-app` para a melhor experiência inicial, você também pode configurar um projeto manualmente. Não instale a CLI globalmente. Em vez disso, adicione `twenty-sdk` como uma dependência local e configure um único script no seu package.json:
|
|
|
|
```bash filename="Terminal"
|
|
yarn add -D twenty-sdk
|
|
```
|
|
|
|
Em seguida, adicione um script `twenty`:
|
|
|
|
```json filename="package.json"
|
|
{
|
|
"scripts": {
|
|
"twenty": "twenty"
|
|
}
|
|
}
|
|
```
|
|
|
|
Agora você pode executar todos os comandos via `yarn twenty <command>`, por exemplo, `yarn twenty app:dev`, `yarn twenty help`, etc.
|
|
|
|
## Resolução de Problemas
|
|
|
|
* Erros de autenticação: execute `yarn twenty auth:login` e certifique-se de que sua chave de API tenha as permissões necessárias.
|
|
* Não é possível conectar ao servidor: verifique a URL da API e se o servidor do Twenty está acessível.
|
|
* Tipos ou cliente ausentes/desatualizados: reinicie `yarn twenty app:dev` — ele gera automaticamente o cliente tipado.
|
|
* Modo de desenvolvimento não sincronizando: certifique-se de que `yarn twenty app:dev` esteja em execução e de que as alterações não estejam sendo ignoradas pelo seu ambiente.
|
|
|
|
Canal de ajuda no Discord: https://discord.com/channels/1130383047699738754/1130386664812982322
|