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

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 --api-url https://your-twenty-server.com --as production

Implantando

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

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

Compartilhando um aplicativo implantado

Compartilhar aplicativos privados (tarball) entre espaços de trabalho é um recurso do plano Enterprise. A guia Distribution exibirá um aviso de atualização em vez dos controles de compartilhamento até que seu espaço de trabalho tenha uma chave Enterprise válida. Vá para Configurações > Painel de Administração > Enterprise para ativá-lo.

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. Assim que o seu espaço de trabalho estiver no plano Enterprise, você pode compartilhar um app implantado desta forma:

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 deploy (ou yarn twenty deploy --remote production)
Os espaços de trabalho que têm o aplicativo instalado 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.

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

Os apps gerados com create-twenty-app já vêm com dois fluxos de trabalho do GitHub Actions prontos, em .github/workflows/. Eles estão prontos para executar assim que você fizer push do repositório para o GitHub — nenhuma configuração extra é necessária para CI, e CD requer apenas um único segredo.

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 server 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 deploy.
Executa twentyhq/twenty/.github/actions/install-twenty-app@main para que a versão recém-implantada seja instalada no workspace 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.

Fixando as ações reutilizáveis

Ambos os fluxos de trabalho 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 logoUrl e screenshots para referenciar imagens da pasta public/:

src/application-config.ts

export default defineApplication({
  universalIdentifier: '...',
  displayName: 'My App',
  description: 'A great app',
  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
  logoUrl: 'public/logo.png',
  screenshots: [
    '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.).

Publicar

yarn twenty publish

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

yarn twenty 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 catalog-sync
# To target a specific remote:
# yarn twenty catalog-sync --remote production

Os metadados exibidos no marketplace vêm da sua configuração defineApplication() — campos como displayName, description, author, category, logoUrl, screenshots, aboutDescription, websiteUrl e termsUrl.

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

Use este workflow do GitHub Actions para publicar automaticamente a cada release (usa OIDC):

name: Publish
on:
  release:
    types: [published]

permissions:
  contents: read
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24"
          registry-url: https://registry.npmjs.org
      - run: yarn install --immutable
      - run: npx twenty build
      - run: npm publish --provenance --access public
        working-directory: .twenty/output

Para outros sistemas de CI (GitLab CI, CircleCI etc.), aplicam-se os mesmos três comandos: yarn install, yarn twenty build e, em seguida, npm publish a partir de .twenty/output.

Proveniência do npm é opcional, mas recomendada. Publicar com --provenance 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. Consulte a documentação de proveniência do npm para instruções de configuração.

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

Visão Geral

Aplicativos

API

Self-Host

Contribute

Visão Geral

Compilando seu app

Implantando em um servidor (tarball)

Pré-requisitos

Implantando

Compartilhando um aplicativo implantado

Gerenciamento de versões

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

CI — `ci.yml`

CD — `cd.yml`

Fixando as ações reutilizáveis

Publicação no npm

Requisitos

Metadados do Marketplace

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

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

​CI — ci.yml

​CD — cd.yml

​Fixando as ações reutilizáveis

​Publicação no npm

​Requisitos

​Metadados do Marketplace

​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

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

CI — `ci.yml`

CD — `cd.yml`

Fixando as ações reutilizáveis

Publicação no npm

Requisitos

Metadados do Marketplace

Publicar

Como funciona a descoberta no marketplace

Publicação via CI

Instalando aplicativos