Publicação

Visão Geral

Depois que seu aplicativo estiver compilado e testado localmente, você tem dois caminhos para distribuí-lo:

Implantar um tarball — envie seu aplicativo diretamente para um servidor Twenty específico para uso interno ou privado.
Publicar no npm — liste seu aplicativo no Marketplace da Twenty para que qualquer espaço de trabalho possa descobrir e instalar.

Ambos os caminhos começam na mesma etapa de build.

Compilando seu app

Execute o comando build para compilar seu app e gerar um manifest.json pronto para distribuição:

yarn twenty dev:build

Isso compila seu código-fonte em TypeScript, transpila funções de lógica e componentes de front-end e grava tudo em .twenty/output/. Adicione --tarball para também gerar um pacote .tgz para distribuição manual ou para o comando de publish.

Implantando em um servidor (tarball)

Para aplicativos que você não quer disponibilizar publicamente — ferramentas proprietárias, integrações apenas para empresas ou builds experimentais — você pode implantar um tarball diretamente em um servidor Twenty.

Pré-requisitos

Antes de implantar, você precisa de um remote configurado apontando para o servidor de destino. Os remotes armazenam a URL do servidor e as credenciais de autenticação localmente em ~/.twenty/config.json. Adicionar um remote:

yarn twenty remote:add --url https://your-twenty-server.com --as production

Implantando

Compile e envie seu aplicativo para o servidor em uma única etapa:

yarn twenty app:publish --private
# To deploy to a specific remote:
# yarn twenty app:publish --private --remote production

Compartilhando um aplicativo implantado

Aplicativos em tarball não são listados no marketplace público, então outros espaços de trabalho no mesmo servidor não os descobrirão ao navegar. Para compartilhar um aplicativo implantado:

Vá para Configurações > Aplicações > Registros e abra seu aplicativo
Na guia Distribuição, clique em Copiar link de compartilhamento
Compartilhe esse link com usuários de outros espaços de trabalho — ele os leva diretamente para a página de instalação do aplicativo

O link de compartilhamento usa a URL base do servidor (sem qualquer subdomínio de espaço de trabalho), para funcionar em qualquer espaço de trabalho no servidor.

Gerenciamento de versões

Ao atualizar um aplicativo empacotado como tarball já implantado, o servidor exige que o version no package.json seja estritamente maior (de acordo com a ordenação do semver) do que a versão atualmente implantada. Reimplantar a mesma versão, ou enviar uma inferior, é rejeitado antes que o tarball seja armazenado — você verá um erro VERSION_ALREADY_EXISTS na CLI. Para lançar uma atualização:

Atualize o campo version no seu package.json (por exemplo, 1.2.3 → 1.2.4, 1.3.0 ou 2.0.0)
Execute yarn twenty app:publish --private (ou yarn twenty app:publish --private --remote production)
Espaços de trabalho que têm o app instalado e ativaram a atualização automática para o app (na aba Configurações do app) são atualizados automaticamente em segundo plano; os demais verão a atualização disponível em suas configurações

Tags de pré-lançamento funcionam como esperado: incrementar 1.0.0-rc.1 → 1.0.0-rc.2 é permitido, e uma versão final como 1.0.0 é corretamente reconhecida como superior a 1.0.0-rc.5. A versão em package.json deve ser, ela própria, uma string semver válida.

Compatibilidade da versão do servidor

Se o seu aplicativo usar um recurso introduzido em uma versão específica do servidor Twenty (por exemplo, provedores OAuth adicionados na v2.3.0), você deve declarar a versão mínima do servidor que seu aplicativo requer usando o campo engines.twenty em package.json:

{
  "name": "twenty-my-app",
  "version": "1.0.0",
  "engines": {
    "node": "^24.5.0",
    "twenty": ">=2.3.0"
  }
}

O valor é um intervalo semver padrão. Padrões comuns:

Intervalo	Significado
`>=2.3.0`	Qualquer servidor a partir de 2.3.0
`>=2.3.0 \<3.0.0`	2.3.0 ou posterior, mas abaixo da próxima versão principal
`^2.3.0`	O mesmo que `>=2.3.0 \<3.0.0`

O que acontece no momento da implantação e da instalação:

Se engines.twenty estiver definido e a versão do servidor de destino não satisfizer o intervalo, a implantação (upload do tarball) ou a instalação será rejeitada com o erro SERVER_VERSION_INCOMPATIBLE e uma mensagem indicando tanto o intervalo exigido quanto a versão real do servidor.
Se engines.twenty não estiver definido, o aplicativo é aceito em qualquer versão do servidor (retrocompatível com os aplicativos existentes).
Se o servidor não tiver APP_VERSION configurado, a verificação será ignorada.

O servidor realiza a verificação definitiva — ele valida engines.twenty tanto no upload do tarball quanto na instalação no espaço de trabalho. Se você implantar um tarball fora de banda ou instalar a partir do marketplace, o servidor ainda impõe a compatibilidade.

CI/CD automatizado (fluxos de trabalho pré-configurados)

Os apps gerados com create-twenty-app já vêm com três fluxos de trabalho do GitHub Actions prontos, em .github/workflows/. A CI é executada sem nenhuma configuração, a CD requer um único segredo e a publicação no npm exige uma configuração única de trusted-publisher do npm.

CI — `ci.yml`

Executa testes de integração a cada push para main e a cada pull request. O que faz:

Faz checkout do código-fonte do seu app.
Inicia uma instância de teste do Twenty isolada usando a ação composta twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main (o equivalente em CI de yarn twenty docker:start --test).
Habilita o Corepack, configura o Node.js a partir do seu .nvmrc e instala as dependências com yarn install --immutable.
Executa yarn test, passando TWENTY_API_URL e TWENTY_API_KEY da instância iniciada para que seus testes possam se comunicar com um servidor real.

Opções de configuração:

TWENTY_VERSION (env, padrão latest) — fixe a versão do servidor Twenty usada no CI editando isto em ci.yml.
A concorrência é agrupada por github.ref e cancela execuções em andamento quando há novos pushes.

Nenhum segredo é necessário — a instância de teste é efêmera e existe apenas durante a execução do job.

CD — `cd.yml`

Faz o deploy do seu app para um servidor Twenty configurado a cada push para main e, opcionalmente, a partir de um pull request quando o rótulo deploy é aplicado. O que faz:

Faz checkout do head do PR (para PRs rotulados) ou do commit enviado.
Executa twentyhq/twenty/.github/actions/deploy-twenty-app@main — o equivalente em CI de yarn twenty app:publish --private.
Executa twentyhq/twenty/.github/actions/install-twenty-app@main para que a versão recém-implantada seja instalada no espaço de trabalho de destino.

Configuração obrigatória:

Configuração	Onde	Finalidade
`TWENTY_DEPLOY_URL`	`env` em `cd.yml` (padrão `http://localhost:3000`)	O servidor Twenty para o qual fazer o deploy. Altere isto para a URL real do seu servidor antes do primeiro uso.
`TWENTY_DEPLOY_API_KEY`	Repositório do GitHub Settings → Secrets and variables → Actions	Chave de API com permissão de deploy no servidor de destino.

O TWENTY_DEPLOY_URL padrão de http://localhost:3000 é um placeholder — ele não alcançará nada a partir de um runner hospedado pelo GitHub. Atualize-o para a URL pública do seu servidor (ou use um runner self-hosted com acesso à rede) antes de habilitar o CD.

Acionando um deploy de pré-visualização a partir de um PR: Adicione o rótulo deploy a um pull request. A condição if: em cd.yml executará o job para esse PR usando o commit HEAD do PR, permitindo que você valide uma alteração no servidor de destino antes de fazer o merge.

Publicar — `publish.yml`

Publica seu app no npm com procedência quando você envia uma tag de versão (por exemplo, v1.0.0), ou quando executa o fluxo de trabalho manualmente na aba Actions. O que faz:

Faz o checkout do seu app, configura o Node.js e atualiza o npm (a publicação confiável requer o npm 11.5.1 ou posterior).
Executa yarn twenty app:publish, que compila o app e publica .twenty/output no npm. Em CI, adiciona automaticamente --provenance e --access public, portanto não são necessárias flags no fluxo de trabalho.

Configuração única: Em npmjs.com, abra o seu pacote > Settings → Trusted Publisher e registre este repositório com o fluxo de trabalho publish.yml (consulte a documentação de publicação confiável do npm). Publicar com proveniência certifica qual repositório do GitHub compilou o pacote, o que também é como você reivindica a propriedade do seu app em um marketplace da Twenty.

npm só aceita proveniência de repositórios de código-fonte públicos. Se você publicar a partir de um repositório privado, o npm rejeita o pacote de proveniência OIDC com um E422 ... Erro: Unsupported GitHub Actions source repository visibility: “private”. Para publicar a partir de um repositório privado, desative a proveniência definindo TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: ‘true’noenvda etapa de publicação (uma dica comentada está incluída nopublish.yml` gerado pelo scaffold):

      - name: Publish to npm
        env:
          TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'
        run: yarn twenty app:publish

Fixando as ações reutilizáveis

Os fluxos de trabalho ci.yml e cd.yml fazem referência a ações reutilizáveis em @main, portanto as atualizações de ações no repositório twentyhq/twenty são aplicadas automaticamente. Se você quiser builds determinísticos, substitua @main por um SHA de commit ou uma tag de release em cada linha uses:.

Publicação no npm

Publicar no npm torna seu aplicativo descobrível no Marketplace da Twenty. Qualquer espaço de trabalho da Twenty pode navegar, instalar e atualizar aplicativos do Marketplace diretamente pela UI.

Requisitos

Uma conta no npm
A palavra-chave twenty-app no array keywords do seu package.json (adicione-a manualmente — não é incluída por padrão no template create-twenty-app)

{
  "name": "twenty-app-postcard-sender",
  "version": "1.0.0",
  "keywords": ["twenty-app"]
}

Metadados do Marketplace

A configuração defineApplication() oferece suporte a campos opcionais que controlam como seu app aparece no marketplace. Use logo e galleryImages para referenciar imagens da pasta public/:

src/application-config.ts

export default defineApplication({
  universalIdentifier: '...',
  displayName: 'My App',
  description: 'A great app',
  logo: 'public/logo.png',
  galleryImages: [
    'public/screenshot-1.png',
    'public/screenshot-2.png',
  ],
});

Veja o acordeão de defineApplication na página Building Apps para a lista completa de campos do marketplace (author, category, aboutDescription, websiteUrl, termsUrl, etc.).

Dimensões recomendadas para imagens da galeria

O marketplace renderiza galleryImages em um contêiner fixo de 8:5 (por exemplo, 1600×1000 px).

Imagens da galeria de qualquer proporção são exibidas por completo e nunca são cortadas, mas qualquer coisa significativamente mais alta ou mais estreita que 8:5 exibirá faixas vazias nas laterais.

Limite de tamanho de imagem

O arquivo logo e cada arquivo em galleryImages não devem exceder 10 MB. Arquivos maiores são ignorados quando o marketplace volta a hospedar os seus recursos publicados, portanto eles não serão exibidos.

Publicar

yarn twenty app:publish

Para publicar sob uma dist-tag específica (por exemplo, beta ou next):

yarn twenty app:publish --tag beta

Como funciona a descoberta no marketplace

O servidor Twenty sincroniza seu catálogo do marketplace a partir do registro do npm a cada hora. Você pode acionar a sincronização imediatamente em vez de esperar:

yarn twenty dev:catalog-sync
# To target a specific remote:
# yarn twenty dev:catalog-sync --remote production

Os metadados exibidos no marketplace vêm da sua configuração de defineApplication() — consulte Metadados do marketplace acima.

Se o seu aplicativo não definir um aboutDescription em defineApplication(), o marketplace usará automaticamente o README.md do seu pacote no npm como conteúdo da página Sobre. Isso significa que você pode manter um único README tanto para o npm quanto para o marketplace da Twenty. Se quiser uma descrição diferente no marketplace, defina explicitamente aboutDescription.

Publicação via CI

O fluxo de trabalho publish.yml estruturado conforme descrito acima publica automaticamente no npm em tags de versão, com proveniência. Como yarn twenty app:publish adiciona --provenance e --access public para você quando é executado em CI, o fluxo de trabalho não precisa de flags do npm — apenas da configuração única de trusted publisher. Para outros sistemas de CI (GitLab CI, CircleCI, etc.), execute yarn install e depois yarn twenty app:publish. A proveniência é emitida quando o ambiente pode gerar um token OIDC e é ignorada automaticamente caso contrário.

A proveniência do npm adiciona um selo de confiança à sua listagem no npm, permitindo que os usuários verifiquem que o pacote foi construído a partir de um commit específico em um pipeline de CI público. É também o que permite que você reivindique a propriedade do seu app em um marketplace da Twenty. Consulte a documentação de proveniência do npm para mais detalhes.

Instalando aplicativos

Depois que um app é publicado (npm) ou implantado (tarball), os espaços de trabalho podem instalá-lo pela interface do usuário. Vá para a página Configurações > Aplicações no Twenty, onde é possível navegar e instalar tanto apps do marketplace quanto apps implantados por tarball. Você também pode instalar apps pela linha de comando:

yarn twenty app:install

O servidor impõe o versionamento semver na instalação, espelhando as regras da implantação:

Instalar a mesma versão que já está instalada no seu espaço de trabalho é rejeitado com um erro APP_ALREADY_INSTALLED.
Instalar uma versão inferior à atualmente instalada é rejeitado com um erro CANNOT_DOWNGRADE_APPLICATION.

Para instalar uma versão mais recente, implante ou publique-a primeiro e, em seguida, execute novamente yarn twenty app:install.

Visão Geral

Aplicativos

API

Auto-Anfitrião

Contribuir

Visão Geral

Compilando seu app

Implantando em um servidor (tarball)

Pré-requisitos

Implantando

Compartilhando um aplicativo implantado

Gerenciamento de versões

Compatibilidade da versão do servidor

CI/CD automatizado (fluxos de trabalho pré-configurados)

CI — `ci.yml`

CD — `cd.yml`

Publicar — `publish.yml`

Fixando as ações reutilizáveis

Publicação no npm

Requisitos

Metadados do Marketplace

Dimensões recomendadas para imagens da galeria

Limite de tamanho de imagem

Publicar

Como funciona a descoberta no marketplace

Publicação via CI

Instalando aplicativos

​Visão Geral

​Compilando seu app

​Implantando em um servidor (tarball)

​Pré-requisitos

​Implantando

​Compartilhando um aplicativo implantado

​Gerenciamento de versões

​Compatibilidade da versão do servidor

​CI/CD automatizado (fluxos de trabalho pré-configurados)

​CI — ci.yml

​CD — cd.yml

​Publicar — publish.yml

​Fixando as ações reutilizáveis

​Publicação no npm

​Requisitos

​Metadados do Marketplace

​Dimensões recomendadas para imagens da galeria

​Limite de tamanho de imagem

​Publicar

​Como funciona a descoberta no marketplace

​Publicação via CI

​Instalando aplicativos

Visão Geral

Compilando seu app

Implantando em um servidor (tarball)

Pré-requisitos

Implantando

Compartilhando um aplicativo implantado

Gerenciamento de versões

Compatibilidade da versão do servidor

CI/CD automatizado (fluxos de trabalho pré-configurados)

CI — `ci.yml`

CD — `cd.yml`

Publicar — `publish.yml`

Fixando as ações reutilizáveis

Publicação no npm

Requisitos

Metadados do Marketplace

Dimensões recomendadas para imagens da galeria

Limite de tamanho de imagem

Publicar

Como funciona a descoberta no marketplace

Publicação via CI

Instalando aplicativos