Guide LLM

Ce document fournit des recommandations prescriptives aux assistants de codage IA qui génèrent du code avec Databricks AppKit. Il est volontairement directif afin de garantir une génération de code cohérente et prête pour la production.

Mission globale

Créez des applications TypeScript full-stack sur Databricks avec :

• Backend : @databricks/appkit
• Frontend : @databricks/appkit-ui
• Analytics : des fichiers SQL dans config/queries/*.sql exécutés via le plugin Analytics d'AppKit

Ce guide est conçu pour fonctionner même si vous n'avez pas accès au dépôt source d'AppKit. Privilégiez uniquement les API publiques des packages et des structures de projet portables.

Règles strictes (garde-fous LLM)

• N'inventez pas d'API. En cas de doute, tenez-vous-en aux modèles présentés dans la documentation et n'utilisez que les exports documentés de @databricks/appkit et @databricks/appkit-ui.
• createApp() est asynchrone. Privilégiez un await createApp(...) de premier niveau. Si ce n'est pas possible, utilisez void createApp(...) et n'ignorez pas le rejet de la promesse.
• Gérez toujours les états de chargement, d'erreur et vides dans l'interface (utilisez Skeleton, un texte d'erreur, un état vide).
• Utilisez toujours les utilitaires sql.* pour les paramètres de query (ne passez pas de chaînes ou de nombres bruts, sauf si la query n'en attend aucun).
• Ne construisez jamais de chaînes SQL de façon dynamique. Utilisez des queries paramétrées avec :paramName.
• N'utilisez jamais require(). Utilisez import/export ESM.

Règles d'import TypeScript

Si votre tsconfig.json utilise "verbatimModuleSyntax": true, utilisez toujours import type pour les imports de types (sans quoi la compilation peut échouer dans les configurations strictes) :

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

Documentation de l'API

Consulter la référence de l'API (documentation uniquement, PAS pour générer l'ossature) :

# UNIQUEMENT pour consulter la documentation — NE PAS utiliser pour init/générer l'ossature
npx @databricks/appkit docs <query>

IMPORTANT : exécutez TOUJOURS npx @databricks/appkit docs (sans requête) EN PREMIER pour consulter l'index de la documentation. NE DEVINEZ PAS les chemins — utilisez l'index pour trouver les chemins corrects.

Exemples :

• Index de la documentation : npx @databricks/appkit docs
• Afficher une section : npx @databricks/appkit docs "appkit-ui API reference"
• Index complet (toutes les entrées d'API) : npx @databricks/appkit docs --full
• Afficher un document précis : npx @databricks/appkit docs ./docs/plugins/analytics.md

Checklist LLM (avant de finaliser le code)

Configuration du projet

• package.json contient "type": "module"
• tsx figure dans les devDependencies pour le serveur de développement
• Le script dev utilise NODE_ENV=development tsx watch server/server.ts
• client/index.html existe, avec <div id="root"></div> et un script pointant vers client/src/main.tsx

Backend

• await createApp({ plugins: [...] }) est utilisé (ou void createApp de façon intentionnelle)
• server() est inclus (toujours)
• En cas d'utilisation de SQL : analytics({}) inclus + config/queries/*.sql présent
• Les queries utilisent des paramètres substituables :param, et les paramètres sont transmis depuis l'interface via sql.*
• Si la query doit être limitée à un workspace : utiliser :workspaceId

Frontend

• useMemo encapsule les objets de paramètres
• Les états de chargement, d'erreur et vide sont explicites
• Les graphiques utilisent format="auto", sauf si vous avez une raison d'imposer "json"/"arrow"
• Les graphiques utilisent des propriétés (xKey, yKey, colors) et NON des enfants (ils reposent sur ECharts, pas sur Recharts)
• En cas d'utilisation d'infobulles : la racine est encapsulée dans <TooltipProvider>

À ne jamais faire

• Ne construisez pas de chaînes SQL à la main
• Ne transmettez pas de paramètres bruts non typés aux queries annotées
• N'ignorez pas la promesse renvoyée par createApp()
• N'inventez pas de composants d'interface absents de la documentation
• Ne passez pas d'enfants Recharts (<Bar>, <XAxis>, etc.) aux composants de graphique AppKit