---
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).
