192 lines
7.5 KiB
Plaintext
192 lines
7.5 KiB
Plaintext
---
|
|
title: Publicação
|
|
description: Distribua seu aplicativo Twenty no Marketplace ou implante-o internamente.
|
|
---
|
|
|
|
<Warning>
|
|
Os aplicativos estão atualmente em testes alfa. O recurso é funcional, mas ainda está evoluindo.
|
|
</Warning>
|
|
|
|
## Visão Geral
|
|
|
|
Depois que seu aplicativo estiver [compilado e testado localmente](/l/pt/developers/extend/apps/building), 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:
|
|
|
|
```bash filename="Terminal"
|
|
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:
|
|
|
|
```bash filename="Terminal"
|
|
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:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty deploy
|
|
# To deploy to a specific remote:
|
|
# yarn twenty deploy --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:
|
|
|
|
1. Vá para **Configurações > Aplicações > Registros** e abra seu aplicativo
|
|
2. Na guia **Distribuição**, clique em **Copiar link de compartilhamento**
|
|
3. 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.
|
|
|
|
<Warning>
|
|
Compartilhar apps privados é um recurso do plano Enterprise. Vá para [Configurações > Painel de Administração > Enterprise](/settings/admin-panel#enterprise) para ativá-lo.
|
|
</Warning>
|
|
|
|
### Gerenciamento de versões
|
|
|
|
Para lançar uma atualização:
|
|
|
|
1. Atualize o campo `version` no seu `package.json`
|
|
2. Execute `yarn twenty deploy` (ou `yarn twenty deploy --remote production`)
|
|
3. Os espaços de trabalho que têm o aplicativo instalado verão a atualização disponível em suas configurações
|
|
|
|
{/* TODO: add screenshot of the Upgrade button */}
|
|
|
|
## 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](https://www.npmjs.com)
|
|
* A palavra-chave `twenty-app` no array `keywords` do seu `package.json` (já incluída quando você cria o projeto com `create-twenty-app`)
|
|
|
|
```json filename="package.json"
|
|
{
|
|
"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/`:
|
|
|
|
```ts 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](/l/pt/developers/extend/apps/building#defineentity-functions) na página Building Apps para a lista completa de campos do marketplace (`author`, `category`, `aboutDescription`, `websiteUrl`, `termsUrl`, etc.).
|
|
|
|
### Publicar
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty publish
|
|
```
|
|
|
|
Para publicar sob uma dist-tag específica (por exemplo, `beta` ou `next`):
|
|
|
|
```bash filename="Terminal"
|
|
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:
|
|
|
|
```bash filename="Terminal"
|
|
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`.
|
|
|
|
<Note>
|
|
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`.
|
|
</Note>
|
|
|
|
### Publicação via CI
|
|
|
|
Use este workflow do GitHub Actions para publicar automaticamente a cada release (usa [OIDC](https://docs.npmjs.com/trusted-publishers)):
|
|
|
|
```yaml filename=".github/workflows/publish.yml"
|
|
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`.
|
|
|
|
<Note>
|
|
**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](https://docs.npmjs.com/generating-provenance-statements) para instruções de configuração.
|
|
</Note>
|
|
|
|
## 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.
|
|
|
|
{/* TODO: add screenshot of the UI when the app is registered */}
|
|
|
|
Você também pode instalar apps pela linha de comando:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty install
|
|
```
|