Guia de LLM

Este documento fornece orientações prescritivas para assistentes de codificação de IA que geram código com o Databricks AppKit. Ele é intencionalmente opinativo para garantir uma geração de código consistente e pronta para produção.

note

Este arquivo contém apenas uma parte das orientações de LLM. Para obter as orientações completas, consulte o arquivo llms.txt, que traz todas as diretrizes baseadas na documentação do AppKit.

Missão de alto nível

Crie aplicativos full-stack em TypeScript no Databricks usando:

Backend: @databricks/appkit
Frontend: @databricks/appkit-ui
Analytics: arquivos SQL em config/queries/*.sql executados pelo Analytics plugin do AppKit

Este guia foi elaborado para funcionar mesmo que você não tenha acesso ao repositório de código-fonte do AppKit. Dê preferência apenas a APIs públicas dos pacotes e a estruturas de projeto portáveis.

Regras rígidas (guardrails para LLMs)

Não invente APIs. Em caso de dúvida, siga os padrões apresentados na documentação e use apenas os exports documentados de @databricks/appkit e @databricks/appkit-ui.
createApp() é assíncrono. Prefira await createApp(...) no nível superior (top-level). Se não for possível, use void createApp(...) e não ignore a rejeição da promise.
Sempre trate os estados de carregamento/erro/vazio na UI (use Skeleton, texto de erro, estado vazio).
Sempre use os helpers sql.* para parâmetros de query (não passe strings/números brutos, a menos que a query não espere nenhum parâmetro).
Nunca monte strings SQL dinamicamente. Use queries parametrizadas com :paramName.
Nunca use require(). Use import/export do ESM.

Regras de importação do TypeScript

Se o seu tsconfig.json usa "verbatimModuleSyntax": true, use sempre import type para importações somente de tipos (caso contrário, os builds podem falhar em configurações estritas):

import type { ReactNode } from "react";
import { useMemo } from "react";

Documentação da API

Consulte a referência da API (apenas documentação, NÃO para scaffolding):

# APENAS para consultar a documentação — NÃO use para init/scaffold
npx @databricks/appkit docs <query>

IMPORTANTE: SEMPRE execute npx @databricks/appkit docs (sem query) PRIMEIRO para ver o índice da documentação. NÃO adivinhe caminhos — use o índice para encontrar os caminhos corretos.

Exemplos:

Índice da documentação: npx @databricks/appkit docs
Ver uma seção: npx @databricks/appkit docs "appkit-ui API reference"
Índice completo (todas as entradas da API): npx @databricks/appkit docs --full
Ver um documento específico: npx @databricks/appkit docs ./docs/plugins/analytics.md

Checklist do LLM (antes de finalizar o código)

Configuração do projeto

O package.json tem "type": "module"
O tsx está em devDependencies para o servidor de desenvolvimento
O script dev usa NODE_ENV=development tsx watch server/server.ts
O client/index.html existe, com <div id="root"></div> e um script apontando para client/src/main.tsx

Backend

await createApp({ plugins: [...] }) é usado (ou void createApp, de forma intencional)
server() está incluído (sempre)
Se usar SQL: analytics({}) incluído + config/queries/*.sql presente
As queries usam placeholders :param, e os parâmetros são passados pela UI com sql.*
Se a query precisar de escopo por workspace: usa :workspaceId

Frontend

useMemo envolve os objetos de parâmetros
Os estados de carregamento/erro/vazio são explícitos
Os gráficos usam format="auto", a menos que haja um motivo para forçar "json"/"arrow"
Os gráficos usam props (xKey, yKey, colors), e NÃO children (são baseados em ECharts, não em Recharts)
Se usar tooltips: a raiz está envolvida em <TooltipProvider>

Nunca

Não construa strings SQL manualmente
Não passe parâmetros brutos sem tipagem para queries anotadas
Não ignore a promise retornada por createApp()
Não invente UI components que não estejam listados na documentação
Não passe elementos filhos do Recharts (<Bar>, <XAxis>, etc.) para os componentes de gráfico do AppKit