---
title: Início rápido
icon: rocket
description: Crie seu primeiro app do Twenty em minutos.
---

## Pré-requisitos

* **Node.js 24.5+** — [Baixar](https://nodejs.org/)
* **Yarn 4** — Vem com o Node.js via Corepack. Ative-o: `corepack enable`
* **Docker** — [Baixar](https://www.docker.com/products/docker-desktop/). Necessário para executar um servidor Twenty local. Ignore se você já tiver o Twenty em execução em outro lugar.

A criação de um aplicativo Twenty tem três fases. A ferramenta de scaffolding as reúne em um único comando do fluxo ideal, mas cada fase é um conceito separado — quando algo falha, saber em que fase você está indica o que corrigir.

| Fase                        | O que você faz                                     | Ferramenta                          | Resultado                             |
| --------------------------- | -------------------------------------------------- | ----------------------------------- | ------------------------------------- |
| **1. Criar scaffolding**    | Gerar o código-fonte do aplicativo                 | `npx create-twenty-app`             | Um projeto TypeScript em disco        |
| **2. Executar um servidor** | Iniciar um servidor Twenty para o qual sincronizar | Docker + `yarn twenty docker:start` | Uma instância Twenty em execução      |
| **3. Sincronizar**          | Sincronize seu código em tempo real com o servidor | `yarn twenty dev`                   | Suas alterações aparecem na interface |

---

## Fase 1 — Fazer scaffolding do seu projeto

Crie um novo aplicativo a partir do modelo:

```bash filename="Terminal"
npx create-twenty-app@latest my-twenty-app
```

O gerador não é interativo: o nome do diretório se torna o nome do app. Passe `--display-name` e `--description` para personalizar os metadados gerados (você também pode editá-los depois em `src/constants/universal-identifiers.ts`). Isso gera um projeto TypeScript em `my-twenty-app/` com um `application-config.ts` inicial, um papel padrão, fluxos de trabalho de CI/CD e um teste de integração.

**Após esta fase:** você tem o código-fonte de um aplicativo na sua máquina. Ele ainda não está em execução — isso é a Fase 2.

---

## Fase 2 — Executar um servidor Twenty local

Seu aplicativo precisa de um servidor Twenty para o qual sincronizar. O servidor é uma instância completa do Twenty — interface, API GraphQL, PostgreSQL — executando localmente no Docker. Seu código local envia suas definições para esse servidor, o que faz com que elas apareçam na interface.

O scaffolder inicia uma instância para você: com o Docker em execução, ele baixa a imagem `twentycrm/twenty-app-dev`, inicia-a na porta `2020` e autentica a CLI no workspace de demonstração pré-preenchido (`tim@apple.dev`) — sem necessidade de login.

Para se conectar a um servidor Twenty existente em vez disso, passe `--url \<your-server-url>`. Servidores remotos se autenticam com OAuth: um navegador é aberto para que você faça login e clique em **Authorize**, o que dá à CLI acesso ao seu workspace. (Você também pode optar por usar OAuth localmente com `--authentication-method oauth` — faça login com `tim@apple.dev` / `tim@apple.dev`.)

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/login.png" alt="Tela de login do Twenty" />
</div>

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/authorize.png" alt="Tela de autorização da CLI do Twenty" />
</div>

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>

**Após esta fase:** você tem um servidor Twenty em execução em [http://localhost:2020](http://localhost:2020) com sua CLI autorizada a sincronizar com ele.

<Note>
Se o Docker não estiver instalado ou em execução, a ferramenta de scaffolding informará o comando de inicialização correto para o seu sistema operacional. Quando o Docker estiver ativo, você pode retomar com `yarn twenty docker:start` — sem necessidade de recriar o scaffolding.
</Note>

---

## Fase 3 — Sincronizar suas alterações

Este é o ciclo interno no qual você passará a maior parte do tempo.

```bash filename="Terminal"
cd my-twenty-app
yarn twenty dev
```

Isso monitora `src/`, recompila a cada alteração e sincroniza o resultado com o servidor. Edite um arquivo, salve e, em alguns segundos, o servidor refletirá a alteração. Você 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), adicione `--verbose`.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/dev.png" alt="Saída do terminal no modo de desenvolvimento" />
</div>

Abra [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Você deverá ver seu aplicativo 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 ver seu **registro do aplicativo** — um registro em nível de servidor que descreve seu aplicativo (nome, identificador, credenciais OAuth, origem). 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 a instalação no espaço de trabalho. A aba **About** mostra a versão e as opções de gerenciamento.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Aplicação instalada" />
</div>

**Após esta fase:** você tem um ciclo de desenvolvimento em tempo real. Edite qualquer arquivo em `src/` e ele aparecerá na interface.

### Sincronização única para CI e scripts

Use `plan` e `apply` para executar o mesmo pipeline uma vez, sem watcher:

```bash filename="Terminal"
yarn twenty plan   # preview the metadata changes without applying them
yarn twenty apply  # show the plan, then apply it
```

| Comando             | Comportamento                                                                                                                                                                                               | Quando usar                                                                      |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `yarn twenty dev`   | Monitora e ressincroniza a cada alteração. Fica em execução até você interrompê-lo.                                                                                                                         | Desenvolvimento local interativo.                                                |
| `yarn twenty apply` | Executa uma única compilação + sincronização e, em seguida, encerra com o código `0` em caso de sucesso ou `1` em caso de falha. Pede confirmação para alterações destrutivas (passe `--force` para pular). | Scripts, CI, hooks de pre-commit, agentes de IA e fluxos de trabalho com script. |
| `yarn twenty plan`  | Compila e imprime as alterações de metadados **sem aplicá-las**.                                                                                                                                            | Inspecionar o que uma sincronização mudaria antes de confirmá-la.                |

Todos os modos precisam de um remoto autenticado. Veja [Sincronização e recuperação](/l/pt/developers/extend/apps/operations/sync-and-recovery#previewing-changes-plan) para mais detalhes sobre `plan`.

<Note>
`yarn twenty dev --once` e `yarn twenty dev --once --dry-run` são aliases obsoletos para `yarn twenty apply` e `yarn twenty plan`.
</Note>

### Opções do modo de desenvolvimento

| Opção                                 | Descrição                                                                                         |
| ------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `--force`                             | Aplicar alterações destrutivas (exclusões) sem confirmação.                                       |
| `--debounceMs \<ms>` | Define o atraso de debounce para alterações de arquivo em milissegundos (padrão: `1000`).         |
| `--verbose` / `--debug`               | Mostra registros detalhados de compilação, solicitações de sincronização e rastreamentos de erro. |

## O que você pode criar

Os aplicativos são compostos por **entidades** — cada uma definida como um arquivo TypeScript com um único `export default`:

| Entidade                     | O que faz                                                                                                          |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Objetos e campos**         | Modelos de dados personalizados (Cartão postal, Fatura etc.) com campos tipados                                    |
| **Funções lógicas**          | Funções TypeScript do lado do servidor acionadas por rotas HTTP, agendamentos do cron ou eventos de banco de dados |
| **Componentes de front-end** | Componentes React que são renderizados na UI do Twenty (painel lateral, widgets, menu de comandos)                 |
| **Habilidades e agentes**    | Recursos de IA — instruções reutilizáveis e assistentes autônomos                                                  |
| **Exibições e navegação**    | Exibições de lista pré-configuradas e itens de menu da barra lateral                                               |
| **Layouts de página**        | Páginas de detalhes de registros personalizadas com abas e widgets                                                 |

Referência completa: [Conceitos](/l/pt/developers/extend/apps/getting-started/concepts).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Configuração" icon="screwdriver-wrench" href="/l/pt/developers/extend/apps/config/overview">
    Identidade do aplicativo, função padrão, hooks de instalação e desinstalação, recursos públicos.
  </Card>
  <Card title="Data" icon="database" href="/l/pt/developers/extend/apps/data/overview">
    Objetos, campos e relações bidirecionais.
  </Card>
  <Card title="Lógica" icon="bolt" href="/l/pt/developers/extend/apps/logic/overview">
    Funções lógicas, habilidades, agentes e conexões OAuth.
  </Card>
  <Card title="Layout" icon="table-columns" href="/l/pt/developers/extend/apps/layout/overview">
    Exibições, navegação, layouts de página, componentes de front-end.
  </Card>
  <Card title="Operações" icon="rocket" href="/l/pt/developers/extend/apps/operations/overview">
    CLI, testes, remotos, CI e publicação do seu aplicativo.
  </Card>
</CardGroup>
