Plugins

Buildprint pode funcionar com plugins do Bubble, não apenas com apps. Um plugin é seu próprio tipo de projeto: você o clona para um workspace local, edita os arquivos triturados como código, envia os arquivos de assets compilados, salva o rascunho no Bubble com buildprint apply e então repassa o rascunho ao proprietário do plugin para publicar uma versão no editor do Bubble.

Tudo nesta página passa pelo grupo de comandos plugin:

buildprint plugin clone <pluginId>
buildprint plugin upload ./dist/widget.js
buildprint plugin publish -m "Release notes" --patch
buildprint plugin versions

Pré-requisitos

• Você precisa estar autenticado e vinculado.

• Você precisa do ID do plugin no Bubble. Este é o ID que o Bubble usa para o plugin na URL do editor (https://bubble.io/plugin_editor?id=<pluginId>). Ele também pode ser encontrado com buildprint project list --json.

Clonar um plugin

buildprint plugin clone <pluginId>
buildprint plugin clone <pluginId> --dir ./my-plugin

clone busca o rascunho atual do plugin no Bubble, o tritura em uma árvore do sistema de arquivos e inicializa um workspace local do plugin.

• <pluginId> (obrigatório) - o ID do plugin no Bubble a ser clonado.

• --dir <path> - substitui o diretório raiz do plugin. O padrão é <pluginId>.

O diretório de destino precisa estar vazio (ou ainda não existir). Se o diretório já for um workspace de app do Buildprint, ou já for um workspace de um plugin diferente, o clone é interrompido e você recebe a orientação para usar --dir para clonar em outro lugar.

Layout do workspace

A raiz de um plugin é um workspace do Buildprint assim como a raiz de um app: ela contém a configuração .buildprint/ e o repositório git vazio, e os arquivos editáveis ficam em uma única worktree irmã chamada plugin:

<plugin-root>/
  .buildprint/          # workspace config and bare Bubble repo
  plugin/               # the editable plugin worktree
    plugin.json         # top-level plugin scalars (includes editor_counter)
    meta.json           # plugin metadata (name, description, license, ...)
    elements/           # plugin element definitions
    actions/            # plugin action definitions
    api/                # plugin API calls
    assets.json         # uploaded asset references (see upload)

refs/bubble/plugin acompanha o último snapshot sincronizado do Bubble e refs/published/plugin acompanha o último commit aplicado ao Bubble, espelhando o modelo de branch do app.

Depois de um clone bem-sucedido, use cd para entrar na worktree plugin/ e trabalhar:

cd <plugin-root>/plugin

Editar e verificar

Edite os arquivos triturados como código e, depois, valide antes de aplicar:

buildprint check

check entende o tipo de workspace de plugin e executa o conjunto de regras do plugin (incluindo verificações de prontidão para publicação). Se mudanças no editor do Bubble aconteceram fora do fluxo normal, puxe-as com buildprint sync antes de continuar - edições diretas no editor ficam invisíveis até você ressicronizar e serão sobrescritas pela próxima aplicação.

Enviar um asset

buildprint plugin upload ./dist/widget.js
buildprint plugin upload ./logo.svg --name "logo.svg" --type image/svg+xml

upload envia um único arquivo local ao Bubble como um asset do plugin e registra uma referência a ele em assets.json. Execute-o de dentro da worktree do plugin.

• <file> (obrigatório) - o arquivo local a ser enviado.

• --name <asset name> - o nome do asset a ser armazenado em assets.json. O padrão é o nome base do arquivo enviado. Deve ser um nome de arquivo simples, não um caminho.

• --type <mime> - o tipo MIME a ser enviado ao Bubble. Se omitido, ele é inferido pela extensão do arquivo, com fallback para application/octet-stream.

Antes de enviar, o comando formata o JSON alterado, executa as verificações do plugin e confirma que a base local está atualizada em relação ao Bubble. O arquivo deve existir, não pode estar vazio e deve ter menos de 5 MB. A chave do asset gerada é um espaço reservado new_<slug> derivado do nome do asset; se assets.json já contiver essa chave, escolha um --name diferente.

O upload registra o asset apenas localmente. Para realmente salvá-lo no rascunho do plugin no Bubble, aplique suas alterações:

buildprint apply

Se o Bubble informar divergência (plugin_drift), execute buildprint sync e tente novamente.

Salvar rascunho vs publicar

Os dois estados são distintos, e isso importa:

• Salvar rascunho - buildprint apply compila suas edições locais (alterações de elementos/ações/API, assets enviados) em mudanças Bubble /write e as salva no rascunho do plugin. Isso é tudo o que o apply faz para plugins.

• Publicar uma versão - uma etapa separada e explícita. O Bubble só permite que o proprietário do plugin envie uma nova versão publicada a partir do editor do plugin, então buildprint plugin publish não publica por você. Ele valida se o rascunho está pronto e imprime as instruções exatas de repasse ao proprietário (link do editor e mensagem de release).

Preparar uma publicação

buildprint plugin publish -m "Release notes"
buildprint plugin publish -m "Fix rendering bug" --patch
buildprint plugin publish -m "Generate owner handoff despite warnings" --force

Execute de dentro da worktree do plugin. publish verifica a prontidão e depois imprime as instruções para o proprietário do plugin enviar uma nova versão no editor do Bubble.

• -m, --description <description> (obrigatório) - a descrição/mensagem da release. Deve ter 120 caracteres ou menos.

• --major - prepara uma versão major.

• --minor - prepara uma versão minor.

• --patch - prepara uma versão patch.

• --force - imprime o repasse ao proprietário mesmo quando houver avisos de prontidão para publicação. O Bubble pode modificar ou rejeitar o plugin.

Escolha no máximo um entre --major, --minor ou --patch. Se o plugin já tiver uma versão publicada, um tipo de atualização é obrigatório; para a primeira publicação de um plugin, o tipo é opcional.

publish se recusa a executar se a worktree tiver alterações não commitadas ou não aplicadas - aplique primeiro com buildprint apply. Ele também se recusa se as verificações do plugin reportarem erros e, a menos que use --force, se houver avisos de prontidão para publicação. Em caso de sucesso, ele imprime o link do editor do plugin (https://bubble.io/plugin_editor?id=<pluginId>&tab=tabs-6) e os passos para o proprietário: abrir o editor, clicar em "Submit a new version", escolher o tipo de release e colar sua mensagem de release. Nenhuma versão pode ser publicada pela própria CLI.