Primeiros passos

• 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

# 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

# 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

# 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

​

Estrutura do projeto (com scaffold)

• 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

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

• 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

// 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
});

• 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

• URL da API (padrão: http://localhost:3000 ou o perfil do seu espaço de trabalho atual)
• Chave de API

​

Gerenciando espaços de trabalho

# 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

​

Configuração manual (sem o gerador)

yarn add -D twenty-sdk

{
  "scripts": {
    "twenty": "twenty"
  }
}

​

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.