github-actions[bot]
0b8421a45a
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
256 lines
13 KiB
Plaintext
256 lines
13 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>
|
|
|
|
## O que são aplicativos?
|
|
|
|
Os aplicativos permitem que você estenda o Twenty com objetos e campos personalizados, funções lógicas, componentes de front-end, habilidades de IA e mais — tudo gerenciado como código. Em vez de configurar tudo pela UI, você define seu modelo de dados e a lógica em TypeScript e implanta em um ou mais workspaces.
|
|
|
|
## 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.
|
|
|
|
## Create your first app
|
|
|
|
### Scaffold your app
|
|
|
|
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.
|
|
|
|
### Set up a local Twenty instance
|
|
|
|
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>
|
|
|
|
### Sign in to your workspace
|
|
|
|
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>
|
|
|
|
### Authorize the app
|
|
|
|
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>
|
|
|
|
### Start developing
|
|
|
|
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>
|
|
|
|
### See your app in 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.
|
|
|
|
---
|
|
|
|
## O que você pode criar
|
|
|
|
Apps are composed of **entities** — each defined as a TypeScript file with a single `export default`:
|
|
|
|
| Entity | What it does |
|
|
| ---------------------------- | --------------------------------------------------------------------------------------------- |
|
|
| **Objects & Fields** | Define custom data models (like Post Card, Invoice) with typed fields |
|
|
| **Funções lógicas** | Server-side TypeScript functions triggered by HTTP routes, cron schedules, or database events |
|
|
| **Componentes de front-end** | React components that render inside Twenty's UI (side panel, widgets, command menu) |
|
|
| **Skills & Agents** | AI capabilities — reusable instructions and autonomous assistants |
|
|
| **Views & Navigation** | Pre-configured list views and sidebar menu items for your objects |
|
|
| **Layouts de página** | Custom record detail pages with tabs and widgets |
|
|
|
|
Head over to [Building Apps](/l/pt/developers/extend/apps/building) for a detailed guide on each entity type.
|
|
|
|
---
|
|
|
|
## Estrutura do projeto
|
|
|
|
The scaffolder generates the following file structure:
|
|
|
|
```text filename="my-twenty-app/"
|
|
my-twenty-app/
|
|
package.json
|
|
yarn.lock
|
|
.gitignore
|
|
.nvmrc
|
|
.yarnrc.yml
|
|
.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
|
|
├── default-role.ts # Default role for logic functions
|
|
├── constants/
|
|
│ └── universal-identifiers.ts # Auto-generated UUIDs and app metadata
|
|
└── __tests__/
|
|
├── setup-test.ts # Test setup (server health check, config)
|
|
└── app-install.integration-test.ts # Integration test
|
|
```
|
|
|
|
### Starting from an example
|
|
|
|
To start from a more complete example with custom objects, fields, logic functions, front components, and more, use the `--example` flag:
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app --example postcard
|
|
```
|
|
|
|
Examples are sourced from the [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples) directory on GitHub. You can also scaffold individual entities into an existing project with `yarn twenty add` (see [Building Apps](/l/pt/developers/extend/apps/building#scaffolding-entities-with-yarn-twenty-add)).
|
|
|
|
### 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/default-role.ts` | Default role that controls what your logic functions can access. |
|
|
| `src/constants/universal-identifiers.ts` | Auto-generated UUIDs and app metadata (display name, description). |
|
|
| `src/__tests__/` | Testes de integração (configuração + teste de exemplo). |
|
|
| `public/` | Recursos estáticos (imagens, fontes) servidos com seu aplicativo. |
|
|
|
|
## Local development server
|
|
|
|
The scaffolder already started a local Twenty server for you. To manage it later, use `yarn twenty server`:
|
|
|
|
| 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 |
|
|
|
|
Data is persisted across restarts in two Docker volumes (`twenty-app-dev-data` for PostgreSQL, `twenty-app-dev-storage` for files). Use `reset` to wipe everything and start fresh.
|
|
|
|
<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>
|
|
|
|
## 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).
|