412 lines
19 KiB
Plaintext
412 lines
19 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.
|
|
|
|
## Pré-requisitos
|
|
|
|
Antes de começar, verifique se o seguinte está instalado na sua máquina:
|
|
|
|
* **Node.js 24+** — [Baixe aqui](https://nodejs.org/)
|
|
* **Yarn 4** — Vem com o Node.js via Corepack. Ative-o executando `corepack enable`
|
|
* **Docker** — [Baixe aqui](https://www.docker.com/products/docker-desktop/). Necessário para executar uma instância local do Twenty. Não é necessário se você já tiver um servidor Twenty em execução.
|
|
|
|
## Passo 1: Gere o scaffold do seu aplicativo
|
|
|
|
Abra um terminal e execute:
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app
|
|
```
|
|
|
|
Será solicitado que você informe um nome e uma descrição para o seu aplicativo. Pressione **Enter** para aceitar os valores padrão.
|
|
|
|
Isso cria uma nova pasta chamada `my-twenty-app` com tudo de que você precisa.
|
|
|
|
<Note>
|
|
O gerador de scaffold oferece suporte a estas flags:
|
|
|
|
* `--minimal` — gera apenas os arquivos essenciais, sem exemplos (padrão)
|
|
* `--exhaustive` — gera todas as entidades de exemplo
|
|
* `--name <name>` — define o nome do aplicativo (pula o prompt)
|
|
* `--display-name <displayName>` — define o nome de exibição (pula o prompt)
|
|
* `--description <description>` — define a descrição (pula o prompt)
|
|
* `--skip-local-instance` — ignora o prompt de configuração do servidor local
|
|
</Note>
|
|
|
|
## Passo 2: Configure uma instância local do Twenty
|
|
|
|
O gerador de scaffold perguntará:
|
|
|
|
> **Você gostaria de configurar uma instância local do Twenty?**
|
|
|
|
* **Digite `yes`** (recomendado) — Isso baixa a imagem Docker `twenty-app-dev` e inicia um servidor Twenty local na porta `2020`. Certifique-se de que o Docker esteja em execução antes de continuar.
|
|
* **Digite `no`** — Escolha esta opção se você já tiver um servidor Twenty em execução localmente.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="Deve iniciar instância local?" />
|
|
</div>
|
|
|
|
## Passo 3: Faça login no seu espaço de trabalho
|
|
|
|
Em seguida, uma janela do navegador será aberta com a página de login do Twenty. Faça login com a conta de demonstração pré-configurada:
|
|
|
|
* **E-mail:** `tim@apple.dev`
|
|
* **Senha:** `tim@apple.dev`
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/login.png" alt="Tela de login do Twenty" />
|
|
</div>
|
|
|
|
## Passo 4: Autorize o aplicativo
|
|
|
|
Após fazer login, você verá uma tela de autorização. Isso permite que seu aplicativo interaja com seu espaço de trabalho.
|
|
|
|
Clique em **Authorize** para continuar.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Tela de autorização da CLI do Twenty" />
|
|
</div>
|
|
|
|
Depois de autorizado, seu terminal confirmará que tudo está configurado.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/scaffolded.png" alt="Scaffold do aplicativo criado com sucesso" />
|
|
</div>
|
|
|
|
## Passo 5: Comece a desenvolver
|
|
|
|
Entre na nova pasta do seu aplicativo e inicie o servidor de desenvolvimento:
|
|
|
|
```bash filename="Terminal"
|
|
cd my-twenty-app
|
|
yarn twenty dev
|
|
```
|
|
|
|
Isso observa seus arquivos-fonte, recompila a cada alteração e sincroniza seu aplicativo com o servidor Twenty local automaticamente. Você deverá ver um painel de status em tempo real no seu terminal.
|
|
|
|
Para uma saída mais detalhada (logs de build, solicitações de sincronização, rastros de erro), use a flag `--verbose`:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty dev --verbose
|
|
```
|
|
|
|
<Warning>
|
|
O modo de desenvolvimento só está disponível em instâncias do Twenty em modo de desenvolvimento (`NODE_ENV=development`). Instâncias de produção rejeitam solicitações de sincronização de desenvolvimento. Use `yarn twenty deploy` para fazer o deploy em servidores de produção — veja [Publicando aplicativos](/l/pt/developers/extend/apps/publishing) para detalhes.
|
|
</Warning>
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/dev.jpg" alt="Saída do terminal no modo de desenvolvimento" />
|
|
</div>
|
|
|
|
## Passo 6: Veja seu aplicativo no Twenty
|
|
|
|
Abra [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer) no seu navegador. Navegue até **Settings > Apps** e selecione a aba **Developer**. Você deverá ver seu aplicativo listado em **Your Apps**:
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Lista Your Apps exibindo My twenty app" />
|
|
</div>
|
|
|
|
Clique em **My twenty app** para abrir o seu **registro do aplicativo**. Um registro é um registro em nível de servidor que descreve seu aplicativo — seu nome, identificador exclusivo, credenciais OAuth e origem (local, npm ou tarball). Ele reside no servidor, não dentro de nenhum espaço de trabalho específico. Quando você instala um aplicativo em um espaço de trabalho, o Twenty cria uma **aplicação** com escopo do espaço de trabalho que aponta para esse registro. Um registro pode ser instalado em vários espaços de trabalho no mesmo servidor.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Detalhes do registro do aplicativo" />
|
|
</div>
|
|
|
|
Clique em **View installed app** para ver o aplicativo instalado. A aba **About** mostra a versão atual e as opções de gerenciamento:
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Aplicativo instalado — aba About" />
|
|
</div>
|
|
|
|
Altere para a aba **Content** para ver tudo o que seu aplicativo oferece — objetos, campos, funções de lógica e agentes:
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-4.png" alt="Aplicativo instalado — aba Content" />
|
|
</div>
|
|
|
|
Tudo pronto! Edite qualquer arquivo em `src/` e as alterações serão detectadas automaticamente.
|
|
|
|
Acesse [Criando aplicativos](/l/pt/developers/extend/apps/building) para um guia detalhado sobre criação de objetos, funções de lógica, componentes de front-end, habilidades e mais.
|
|
|
|
---
|
|
|
|
## Estrutura do projeto
|
|
|
|
O gerador de scaffold cria a seguinte estrutura de arquivos (mostrada com o modo `--exhaustive`, que inclui exemplos para cada tipo de entidade):
|
|
|
|
```text filename="my-twenty-app/"
|
|
my-twenty-app/
|
|
package.json
|
|
yarn.lock
|
|
.gitignore
|
|
.nvmrc
|
|
.yarnrc.yml
|
|
.yarn/
|
|
install-state.gz
|
|
.oxlintrc.json
|
|
tsconfig.json
|
|
tsconfig.spec.json # TypeScript config for tests
|
|
vitest.config.ts # Vitest test runner configuration
|
|
LLMS.md
|
|
README.md
|
|
.github/
|
|
└── workflows/
|
|
└── ci.yml # GitHub Actions CI workflow
|
|
public/ # Public assets (images, fonts, etc.)
|
|
src/
|
|
├── application-config.ts # Required — main application configuration
|
|
├── __tests__/
|
|
│ ├── setup-test.ts # Test setup (server health check, config)
|
|
│ └── app-install.integration-test.ts # Example integration test
|
|
├── 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
|
|
│ ├── create-hello-world-company.ts # Example logic function using CoreApiClient
|
|
│ ├── pre-install.ts # Runs before installation
|
|
│ └── post-install.ts # Runs after installation
|
|
├── front-components/
|
|
│ └── hello-world.tsx # Example front component
|
|
├── page-layouts/
|
|
│ └── example-record-page-layout.ts # Example page layout with 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
|
|
└── agents/
|
|
└── example-agent.ts # Example AI agent definition
|
|
```
|
|
|
|
Por padrão (`--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`. Use `--exhaustive` para incluir todos os arquivos de exemplo mostrados acima.
|
|
|
|
### Arquivos principais
|
|
|
|
| Arquivo / Pasta | Finalidade |
|
|
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `package.json` | Declara o nome, a versão e as dependências do seu aplicativo. Inclui um script `twenty` para que você possa executar `yarn twenty help` e ver todos os comandos. |
|
|
| `src/application-config.ts` | **Obrigatório.** O principal arquivo de configuração do seu aplicativo. |
|
|
| `src/roles/` | Define papéis que controlam o que suas funções de lógica podem acessar. |
|
|
| `src/logic-functions/` | Funções do lado do servidor acionadas por rotas, agendamentos do cron ou eventos de banco de dados. |
|
|
| `src/front-components/` | Componentes React que renderizam dentro da interface do Twenty. |
|
|
| `src/objects/` | Definições de objetos personalizados para estender seu modelo de dados. |
|
|
| `src/fields/` | Campos personalizados adicionados a objetos existentes. |
|
|
| `src/views/` | Configurações de visualizações salvas. |
|
|
| `src/navigation-menu-items/` | Links personalizados na navegação da barra lateral. |
|
|
| `src/skills/` | Habilidades que estendem os agentes de IA do Twenty. |
|
|
| `src/agents/` | Agentes de IA com prompts personalizados. |
|
|
| `src/page-layouts/` | Layouts de página personalizados para visualizações de registros. |
|
|
| `src/__tests__/` | Testes de integração (configuração + teste de exemplo). |
|
|
| `public/` | Recursos estáticos (imagens, fontes) servidos com seu aplicativo. |
|
|
|
|
## Gerenciando remotos
|
|
|
|
Um **remoto** é um servidor Twenty ao qual seu aplicativo se conecta. Durante a configuração, o gerador de scaffold cria um para você automaticamente. Você pode adicionar mais remotos ou alternar entre eles a qualquer momento.
|
|
|
|
```bash filename="Terminal"
|
|
# Add a new remote (opens a browser for OAuth login)
|
|
yarn twenty remote add
|
|
|
|
# Connect to a local Twenty server (auto-detects port 2020 or 3000)
|
|
yarn twenty remote add --local
|
|
|
|
# Add a remote non-interactively (useful for CI)
|
|
yarn twenty remote add --api-url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as my-remote
|
|
|
|
# List all configured remotes
|
|
yarn twenty remote list
|
|
|
|
# Switch the active remote
|
|
yarn twenty remote switch <name>
|
|
```
|
|
|
|
Suas credenciais são armazenadas em `~/.twenty/config.json`.
|
|
|
|
## Servidor de desenvolvimento local (`yarn twenty server`)
|
|
|
|
A CLI pode gerenciar um servidor Twenty local em execução no Docker. Este é o mesmo servidor iniciado automaticamente quando você cria o scaffold de um aplicativo com `create-twenty-app`, mas você também pode gerenciá-lo manualmente.
|
|
|
|
### Iniciando o servidor
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server start
|
|
```
|
|
|
|
Isso baixa a imagem Docker `twentycrm/twenty-app-dev:latest` (se ainda não estiver presente), cria um contêiner chamado `twenty-app-dev` e o inicia na porta **2020**. A CLI aguarda até que o servidor passe na verificação de integridade antes de retornar.
|
|
|
|
Dois volumes do Docker são criados para persistir os dados entre reinicializações:
|
|
|
|
* `twenty-app-dev-data` — banco de dados PostgreSQL
|
|
* `twenty-app-dev-storage` — armazenamento de arquivos
|
|
|
|
Se a porta 2020 já estiver em uso, você pode iniciar em uma porta diferente:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server start --port 3030
|
|
```
|
|
|
|
A CLI configura automaticamente as variáveis internas do contêiner `NODE_PORT` e `SERVER_URL` para corresponderem à porta escolhida, para que as funções de lógica, o OAuth e toda a comunicação interna de rede funcionem corretamente.
|
|
|
|
Depois de iniciado, o servidor é registrado automaticamente como o remoto `local` na configuração da sua CLI.
|
|
|
|
### Verificando o status do servidor
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server status
|
|
```
|
|
|
|
Exibe se o servidor está em execução, sua URL e as credenciais de login padrão (`tim@apple.dev` / `tim@apple.dev`).
|
|
|
|
### Visualizando os logs do servidor
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server logs
|
|
```
|
|
|
|
Transmite os logs do contêiner. Use `--lines` para controlar quantas linhas recentes mostrar:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server logs --lines 100
|
|
```
|
|
|
|
### Parando o servidor
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server stop
|
|
```
|
|
|
|
Interrompe o contêiner. Seus dados são preservados nos volumes do Docker — o próximo `start` continua de onde você parou.
|
|
|
|
### Redefinindo o servidor
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server reset
|
|
```
|
|
|
|
Remove o contêiner **e** exclui os dois volumes do Docker, apagando todos os dados. O próximo `start` cria uma instância nova.
|
|
|
|
<Note>
|
|
O servidor requer que o **Docker** esteja em execução. Se você vir um erro "Docker not running", certifique-se de que o Docker Desktop (ou o daemon do Docker) esteja iniciado.
|
|
</Note>
|
|
|
|
### Referência de comandos
|
|
|
|
| Comando | Descrição |
|
|
| -------------------------------------- | ------------------------------------------------------ |
|
|
| `yarn twenty server start` | Inicia o servidor local (baixa a imagem se necessário) |
|
|
| `yarn twenty server start --port 3030` | Iniciar em uma porta personalizada |
|
|
| `yarn twenty server stop` | Interrompe o servidor (preserva os dados) |
|
|
| `yarn twenty server status` | Mostra o status do servidor, a URL e as credenciais |
|
|
| `yarn twenty server logs` | Transmite os logs do servidor |
|
|
| `yarn twenty server logs --lines 100` | Mostra as últimas 100 linhas de log |
|
|
| `yarn twenty server reset` | Exclui todos os dados e inicia do zero |
|
|
|
|
## CI com GitHub Actions
|
|
|
|
O gerador de scaffold cria um workflow do GitHub Actions pronto para uso em `.github/workflows/ci.yml`. Ele executa seus testes de integração automaticamente a cada push para `main` e em pull requests.
|
|
|
|
O workflow:
|
|
|
|
1. Faz checkout do seu código
|
|
2. Inicializa um servidor Twenty temporário usando a ação `twentyhq/twenty/.github/actions/spawn-twenty-docker-image`
|
|
3. Instala as dependências com `yarn install --immutable`
|
|
4. Executa `yarn test` com `TWENTY_API_URL` e `TWENTY_API_KEY` injetados a partir das saídas da ação
|
|
|
|
```yaml .github/workflows/ci.yml
|
|
name: CI
|
|
|
|
on:
|
|
push:
|
|
branches:
|
|
- main
|
|
pull_request: {}
|
|
|
|
env:
|
|
TWENTY_VERSION: latest
|
|
|
|
jobs:
|
|
test:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- name: Checkout
|
|
uses: actions/checkout@v4
|
|
|
|
- name: Spawn Twenty instance
|
|
id: twenty
|
|
uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main
|
|
with:
|
|
twenty-version: ${{ env.TWENTY_VERSION }}
|
|
github-token: ${{ secrets.GITHUB_TOKEN }}
|
|
|
|
- name: Enable Corepack
|
|
run: corepack enable
|
|
|
|
- name: Setup Node.js
|
|
uses: actions/setup-node@v4
|
|
with:
|
|
node-version-file: '.nvmrc'
|
|
cache: 'yarn'
|
|
|
|
- name: Install dependencies
|
|
run: yarn install --immutable
|
|
|
|
- name: Run integration tests
|
|
run: yarn test
|
|
env:
|
|
TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }}
|
|
TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }}
|
|
```
|
|
|
|
Você não precisa configurar nenhum segredo — a ação `spawn-twenty-docker-image` inicia um servidor Twenty efêmero diretamente no runner e fornece os detalhes de conexão. O segredo `GITHUB_TOKEN` é fornecido automaticamente pelo GitHub.
|
|
|
|
Para fixar uma versão específica do Twenty em vez de `latest`, altere a variável de ambiente `TWENTY_VERSION` no topo do workflow.
|
|
|
|
## Configuração manual (sem o gerador)
|
|
|
|
Se preferir configurar tudo por conta própria em vez de usar `create-twenty-app`, você pode fazer isso em duas etapas.
|
|
|
|
**1. Adicione `twenty-sdk` e `twenty-client-sdk` como dependências:**
|
|
|
|
```bash filename="Terminal"
|
|
yarn add twenty-sdk twenty-client-sdk
|
|
```
|
|
|
|
**2. Adicione um script `twenty` ao seu `package.json`:**
|
|
|
|
```json filename="package.json"
|
|
{
|
|
"scripts": {
|
|
"twenty": "twenty"
|
|
}
|
|
}
|
|
```
|
|
|
|
Agora você pode executar `yarn twenty dev`, `yarn twenty help` e todos os outros comandos.
|
|
|
|
<Note>
|
|
Não instale o `twenty-sdk` globalmente. Use-o sempre como uma dependência local do projeto para que cada projeto possa fixar sua própria versão.
|
|
</Note>
|
|
|
|
## Resolução de Problemas
|
|
|
|
Se você tiver problemas:
|
|
|
|
* Certifique-se de que o **Docker está em execução** antes de iniciar o scaffolder com uma instância local.
|
|
* Certifique-se de que está usando **Node.js 24+** (`node -v` para verificar).
|
|
* Certifique-se de que o **Corepack está ativado** (`corepack enable`) para que o Yarn 4 esteja disponível.
|
|
* Tente excluir `node_modules` e executar `yarn install` novamente se as dependências parecerem corrompidas.
|
|
|
|
Ainda com dificuldades? Peça ajuda no [Discord da Twenty](https://discord.com/channels/1130383047699738754/1130386664812982322).
|