Configuration du projet

Ce guide présente la structure de projet recommandée ainsi que générer l’ossature des applications AppKit.

Structure canonique du projet

Structure recommandée (séparation client/serveur) :

my-app/
├── server/
│   ├── server.ts              # point d'entrée du backend (AppKit)
│   └── .env                  # variables d'env locales facultatives (ne pas committer)
├── client/
│   ├── index.html
│   ├── vite.config.ts
│   └── src/
│       ├── main.tsx
│       └── App.tsx
├── config/
│   └── queries/
│       └── my_query.sql
├── app.yaml
├── package.json
└── tsconfig.json

Justification de la structure

Le plugin server() d'AppKit sert automatiquement :

Dev : le serveur de développement Vite (HMR) depuis client/
Prod : les fichiers statiques depuis client/dist (générés par Vite)

Générer l’ossature du projet

`package.json`

{
  "name": "my-app",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "NODE_ENV=development tsx watch server/server.ts",
    "build": "npm run build:server && npm run build:client",
    "build:server": "tsdown --out-dir build server/server.ts",
    "build:client": "tsc -b && vite build --config client/vite.config.ts",
    "start": "node build/index.mjs"
  },
  "dependencies": {
    "@databricks/appkit": "^0.1.2",
    "@databricks/appkit-ui": "^0.1.2",
    "react": "^19.2.3",
    "react-dom": "^19.2.3"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "@types/react": "^19.0.0",
    "@types/react-dom": "^19.0.0",
    "@vitejs/plugin-react": "^5.1.1",
    "tsdown": "^0.20.3",
    "tsx": "^4.19.0",
    "typescript": "~5.6.0",
    "vite": "^7.2.4"
  }
}

`client/index.html`

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My App</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

`client/src/main.tsx`

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

`client/src/App.tsx` (version minimale)

export default function App() {
  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold">My App</h1>
    </div>
  );
}

`client/vite.config.ts`

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
});

`tsconfig.json`

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true
  },
  "include": ["server", "client/src"]
}

`server/server.ts`

import { createApp, server } from "@databricks/appkit";

await createApp({
  plugins: [server()],
});

Exécuter l'application

# Installer les dépendances
npm install

# Développement (démarre le backend + le serveur de développement Vite)
npm run dev

# Build de production
npm run build
npm start

Intégration dans une application existante

Si vous disposez déjà d'une application React/Vite et souhaitez y ajouter AppKit :

1. Installer les dépendances

npm install @databricks/appkit @databricks/appkit-ui react react-dom
npm install -D tsx tsdown vite @vitejs/plugin-react typescript

Si vous n'avez pas encore de dossier client/, créez-en un et déplacez-y votre application Vite :

Déplacez index.html → client/index.html
Déplacez vite.config.ts → client/vite.config.ts
Déplacez src/ → client/src/

2. Créer `server/server.ts` (nouveau fichier)

import { createApp, server } from "@databricks/appkit";

await createApp({
  plugins: [server()],
});

3. Mettre à jour les scripts de `package.json`

{
  "scripts": {
    "dev": "NODE_ENV=development tsx watch server/server.ts",
    "build": "npm run build:server && npm run build:client",
    "build:server": "tsdown --out-dir build server/server.ts",
    "build:client": "tsc -b && vite build --config client/vite.config.ts",
    "start": "node build/index.mjs"
  }
}

4. Finaliser la configuration

Le plugin serveur d'AppKit sert automatiquement votre application Vite en mode développement, et client/dist en production. Si votre application Vite doit rester à la racine du dépôt (sans dossier client/), AppKit fonctionne tout de même, mais la structure recommandée reste client/ + server/.

Ajouter l'analytique à une application existante

Pour ajouter des fonctionnalités d'exécution de requêtes SQL :

// server/server.ts
import { createApp, server, analytics } from "@databricks/appkit";

await createApp({
  plugins: [server(), analytics()],
});

Créez ensuite config/queries/ et ajoutez-y vos fichiers .sql.

Voir aussi

Développement local - Lancer le serveur de développement
Configuration - Variables d'environnement
Plugins - Configuration des plugins

Configuration du projet

Structure canonique du projet

Justification de la structure

Générer l’ossature du projet

package.json

client/index.html

client/src/main.tsx

client/src/App.tsx (version minimale)

client/vite.config.ts

tsconfig.json

server/server.ts