Remote Bridge

Prerequisites

• Node.js v22+ environment with npm
• Databricks CLI (v1.0.0 or higher): install and configure it according to the official tutorial.
• A new Databricks app with AppKit installed. See Bootstrap a new Databricks app for more details.

O remote bridge permite desenvolver sobre um backend já implantado, mantendo a UI e as queries localmente. Isso é útil para testar com dados de produção ou depurar o código de backend implantado sem precisar fazer o deploy do app novamente.

Quando usar o Remote Bridge

Use o remote bridge quando precisar:

• Testar com dados de produção
• Depurar código de backend já implantado
• Desenvolver a UI sem executar o backend localmente
• Colaborar com membros da equipe no mesmo backend

Iniciar e parar o Remote Bridge

Para iniciar o remote bridge, execute o seguinte comando:

databricks apps dev-remote

O comando irá:

1. Obter o nome do app a partir do contexto (do arquivo app.yml ou da entrada do usuário na CLI)
2. Iniciar um servidor de desenvolvimento Vite local
3. Estabelecer uma ponte WebSocket com o app implantado
4. Fornecer duas URLs:
   • URL do app: link direto para uso próprio (<app-url>?dev=true)
   • URL compartilhável: link com ID do túnel para compartilhar com os membros da equipe (<app-url>?dev=<tunnelId>)

databricks apps dev-remote --help

Para interromper o remote bridge, pressione Ctrl+C no terminal.

Aprovação de conexão

Ao iniciar o remote bridge, sempre que você abrir a URL no navegador de um novo dispositivo, será solicitado que aprove a conexão.

Você pode compartilhar a URL com os membros da sua equipe para que eles vejam o app no navegador. Mesmo assim, a conexão precisará ser aprovada por você.

Como funciona

O remote bridge cria uma ponte WebSocket entre o servidor de desenvolvimento local do Vite e o backend implantado, permitindo desenvolver a UI localmente enquanto usa o backend implantado.

Detalhes

• O Navegador conecta-se ao backend do app implantado usando o parâmetro de consulta ?dev=true ou ?dev=<tunnelId>
• O Backend implantado encaminha as requisições da UI por um túnel WebSocket (/dev-tunnel) até a sua máquina local
• A ponte WebSocket (em execução local) recebe do backend as requisições de fetch e de leitura de arquivos
• O servidor de desenvolvimento Vite local serve os arquivos da UI e oferece substituição de módulos a quente (HMR)
• A ponte envia as respostas de volta pelo WebSocket ao backend, que as entrega ao navegador

O que tem hot-reload

Com o remote bridge, você tem hot-reload instantâneo para:

• Mudanças de UI — Qualquer alteração nos seus arquivos React/TypeScript/CSS no diretório client/
• Arquivos de queries — Arquivos SQL no diretório config/queries/ (somente arquivos .sql)

O código de backend não tem hot-reload. É preciso fazer o deploy do app novamente para ver as alterações no código de backend.