Guía para LLM

Este documento ofrece orientación prescriptiva para los asistentes de programación con IA que generan código con Databricks AppKit. Adopta deliberadamente un enfoque definido para garantizar una generación de código coherente y lista para producción.

Misión general

Crea aplicaciones full-stack en TypeScript en Databricks con:

• Backend: @databricks/appkit
• Frontend: @databricks/appkit-ui
• Analítica: archivos SQL en config/queries/*.sql ejecutados mediante el Analytics plugin de AppKit

Esta guía está pensada para funcionar incluso si no tienes acceso al repositorio fuente de AppKit. Usa únicamente las APIs públicas de los paquetes y estructuras de proyecto portables.

Reglas estrictas (guardrails para LLM)

• No inventes APIs. Si tienes dudas, cíñete a los patrones que se muestran en la documentación y usa únicamente las exportaciones documentadas de @databricks/appkit y @databricks/appkit-ui.
• createApp() es asíncrona. Es preferible usar await createApp(...) en el nivel superior. Si no es posible, usa void createApp(...) y no ignores el rechazo de la promesa.
• Gestiona siempre los estados de carga, error y vacío en la interfaz (usa Skeleton, texto de error, estado vacío).
• Usa siempre los helpers sql.* para los parámetros de las queries (no pases cadenas ni números en bruto, salvo que la query no espere ninguno).
• Nunca construyas cadenas SQL de forma dinámica. Usa queries parametrizadas con :paramName.
• Nunca uses require(). Usa import/export de ESM.

Reglas de importación en TypeScript

Si tu tsconfig.json usa "verbatimModuleSyntax": true, usa siempre import type para las importaciones exclusivas de tipos (de lo contrario, las compilaciones pueden fallar en configuraciones estrictas):

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

Documentación de la API

Consulta la referencia de la API (solo documentación, NO para hacer scaffolding):

# SOLO para consultar la documentación: NO usar para init/scaffold
npx @databricks/appkit docs <query>

IMPORTANTE: ejecuta SIEMPRE npx @databricks/appkit docs (sin consulta) en PRIMER lugar para ver el índice de la documentación. NO adivines las rutas: usa el índice para localizar las rutas correctas.

Ejemplos:

• Índice de la documentación: npx @databricks/appkit docs
• Ver una sección: npx @databricks/appkit docs "appkit-ui API reference"
• Índice completo (todas las entradas de la API): npx @databricks/appkit docs --full
• Ver un documento concreto: npx @databricks/appkit docs ./docs/plugins/analytics.md

Lista de verificación del LLM (antes de finalizar el código)

Configuración del proyecto

• package.json tiene "type": "module"
• tsx está en devDependencies para el servidor de desarrollo
• El script dev usa NODE_ENV=development tsx watch server/server.ts
• Existe client/index.html con <div id="root"></div> y un script que apunta a client/src/main.tsx

Backend

• Se usa await createApp({ plugins: [...] }) (o void createApp de forma intencionada)
• Se incluye server() (siempre)
• Si se usa SQL: se incluye analytics({}) + existen los archivos config/queries/*.sql
• Las queries usan marcadores :param y los parámetros se pasan desde la UI con sql.*
• Si la query debe acotarse al workspace: usa :workspaceId

Frontend

• useMemo envuelve los objetos de parámetros
• Los estados de carga, error y vacío son explícitos
• Los gráficos usan format="auto" salvo que tengas un motivo para forzar "json"/"arrow"
• Los gráficos usan props (xKey, yKey, colors) y NO children (están basados en ECharts, no en Recharts)
• Si usas tooltips: la raíz está envuelta en <TooltipProvider>

Nunca

• No construyas cadenas SQL manualmente
• No pases parámetros sin tipar en queries anotadas
• No ignores la promesa que devuelve createApp()
• No inventes componentes de UI que no aparezcan en la documentación
• No pases elementos hijos de Recharts (<Bar>, <XAxis>, etc.) a los componentes de gráficos de AppKit