Todas as coleções

Sistema de Arquivos

Quando você clona uma branch do Bubble, o Buildprint grava uma projeção normalizada do sistema de arquivos do app Bubble. Esta projeção foi projetada para agentes e git: arquivos pequenos, JSON determinístico e diffs comuns.

O sistema de arquivos não é uma exportação bruta do Bubble. Campos voláteis são removidos, campos derivados são recomputados e diversos campos do Bubble são representados pela localização no diretório em vez de propriedades JSON.

Layout de nível superior

<app-root>/
  .buildprint/
    app.json
    remote.git/
  <branch>/
    .git
    .gitignore
    app.json
    settings/
    data_types/
    option_sets/
    styles/
    pages/
    element-definitions/
    mobile-views/
    global-elements/
    api/
    tests/
    issues/

A raiz do app é compartilhada por todos os espaços de trabalho de branch de um app Bubble. A pasta da branch é a árvore de trabalho git editável.

Conteúdo da pasta da branch

  • app.json contém escalares de nível superior do app Bubble.

  • settings/client-safe.json contém configurações do Bubble seguras para o cliente que não foram extraídas para outro lugar.

  • settings/api-connector/<plugin-id>/plugin.json e settings/api-connector/<plugin-id>/calls/<call-id>.json contêm configurações do API Connector.

  • data_types/<type-id>/type.json contém um tipo de dado do Bubble. Campos e funções de privacidade permanecem inline.

  • option_sets/<set-id>/option-set.json contém um conjunto de opções (option set). Valores e atributos permanecem inline.

  • styles/<ElementType>/<style-id>.json contém estilos agrupados por tipo de elemento.

  • styles/bp_no_type/ contém estilos cujo JSON de origem não possui o campo type.

  • styles/tokens.json, styles/defaults.json e styles/fonts.json contêm tokens de design extraídos e configurações de estilo padrão.

  • pages/, element-definitions/, mobile-views/ e global-elements/ contêm raízes da tela (canvas).

  • api/ contém workflows de backend e pastas de workflow.

  • tests/ contém definições de teste do projeto Buildprint e componentes de teste reutilizáveis.

  • issues/ é uma projeção somente leitura do resultado do verificador de problemas do Bubble. É ignorada durante assemble/apply.

Raízes da tela (canvas)

Páginas, elementos reutilizáveis, views mobile e elementos globais compartilham a mesma estrutura:

pages/<page-key>/
  page.json
  elements/
    <element-map-key>/
      element.json
      <child-map-key>/
        element.json
  workflows/
    <workflow-key>/
      workflow.json
      actions/
        0.json
        1.json

O nome da pasta do elemento é a chave do mapa de elementos do objeto elements pai. Não é necessariamente o mesmo que o campo id dentro de element.json.

As pastas filhas espelham a contenção do Bubble. O corpo pai contém um array children, e o buildprint check garante que o conjunto de pastas filhas corresponda ao conjunto de entradas em children. A ordem em children é o manifesto local de ordem de exibição.

Não invente properties.order ou properties.zindex. Esses são campos reais do Bubble e são preservados apenas quando o Bubble os emite.

Workflows e ações

Cada pasta de workflow contém workflow.json e uma pasta actions/. Os nomes dos arquivos de ação são chaves inteiras como 0.json, 1.json e 2.json; o nome do arquivo é a ordem de execução. Chaves inteiras esparsas são preservadas quando o Bubble as utiliza.

As pastas de workflow do Bubble são representadas por diretórios com config.json:

api/
  billing/
    config.json
    create-order/
      workflow.json
      actions/0.json
  orphan-workflow/
    workflow.json
    actions/0.json

A mesma estrutura de pastas se aplica abaixo das raízes de workflow da tela, como pages/home/workflows/.

properties.wf_folder é removido dos corpos de workflow. Para mover um workflow entre pastas, mova o diretório do workflow. Para renomear uma pasta, edite seu config.json.

Testes como código

Os testes de projeto do Buildprint ficam em tests/:

tests/<folder-key>/
  config.json
  checkout.json
tests/__ungrouped__/
  login.json

Os testes de projeto são globais para o app, em vez de específicos para uma branch do Bubble. project clone e sync materializam o snapshot de teste atual em cada espaço de trabalho de branch. apply envia definições de teste alteradas de volta ao Buildprint junto com as alterações do app. Se apenas os testes mudarem, o apply pode pular a solicitação de gravação do Bubble e aplicar apenas as alterações de código de teste.

Use buildprint new test e buildprint new test-step para criar arquivos de teste válidos.

JSON Canônico

Cada arquivo JSON gravado pela CLI usa o mesmo formato canônico:

  • UTF-8, finais de linha LF e uma nova linha final.

  • Indentação de dois espaços.

  • Sem tabulações, caracteres CR ou espaços em branco finais.

  • Chaves de objetos não inteiras são ordenadas alfabeticamente.

  • Mapas com chaves inteiras preservam a ordem de inserção.

buildprint check formata os arquivos JSON alterados antes de executar as regras. Se uma edição manual divergir, a regra canonical-form a reportará.

IDs e nomes de arquivos

O Buildprint cria IDs curtos bp para novas entidades. Para edições manuais, gere novos IDs com:

buildprint utils generate-ids 12

A contagem deve estar entre 1 e 1000. O comando imprime um ID por linha em ordem lexicográfica.

Apps Bubble existentes podem conter IDs curtos nativos do Bubble ou IDs no estilo timestamp. Os leitores aceitam ambos. Novas entidades criadas pelo Buildprint devem usar IDs do Buildprint gerados.

O que não editar

  • Não edite o conteúdo interno de .buildprint/ ou .git/.

  • Não adicione campos extraídos de volta aos arquivos de corpo, como properties.wf_folder em workflows ou type em corpos de estilo.

  • Não crie chaves _bp_* ou __bp_* desconhecidas manualmente.

  • Não trate issues/ como uma fonte de verdade editável.

  • Não adicione campos voláteis do Bubble, como last_change, creation_date, screenshot ou uid_counter.

Refs do Git

O espaço de trabalho da branch é uma árvore de trabalho (worktree) normal do git. Refs úteis:

  • refs/heads/<branch> é a sua branch local.

  • refs/bubble/<branch> é o snapshot mais recente sincronizado do Bubble no repositório bare do Buildprint.

  • refs/published/<branch> rastreia o último commit local aplicado com sucesso ao Bubble.

  • refs/remotes/buildprint/<branch> espelha a ref publicada na árvore de trabalho.

Use git status, git diff e git log buildprint/<branch>..HEAD como faria em qualquer outro checkout do git.

Isso foi útil?