Configuración del proyecto

Esta guía describe la estructura de proyecto y el scaffolding recomendados para las aplicaciones de AppKit.

Estructura canónica del proyecto

Estructura recomendada (separación cliente/servidor):

my-app/
├── server/
│   ├── server.ts              # punto de entrada del backend (AppKit)
│   └── .env                  # variables de entorno opcionales para desarrollo local (no subir al repositorio)
├── client/
│   ├── index.html
│   ├── vite.config.ts
│   └── src/
│       ├── main.tsx
│       └── App.tsx
├── config/
│   └── queries/
│       └── my_query.sql
├── app.yaml
├── package.json
└── tsconfig.json

Fundamento de la estructura

El plugin server() de AppKit sirve automáticamente:

Desarrollo: el servidor de desarrollo de Vite (HMR) desde client/
Producción: los archivos estáticos de client/dist (compilados por Vite)

Scaffolding del proyecto

`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` (mínimo)

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()],
});

Ejecutar la aplicación

# Instalar dependencias
npm install

# Desarrollo (inicia el backend + el servidor de desarrollo de Vite)
npm run dev

# Compilación para producción
npm run build
npm start

Integración en una aplicación existente

Si ya tienes una aplicación React/Vite y quieres añadir AppKit:

1. Instalar dependencias

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

Si aún no tienes una carpeta client/, créala y mueve tu aplicación de Vite dentro:

Mueve index.html → client/index.html
Mueve vite.config.ts → client/vite.config.ts
Mueve src/ → client/src/

2. Crear `server/server.ts` (archivo nuevo)

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

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

3. Actualizar los 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. Completar la configuración

El plugin de servidor de AppKit servirá automáticamente tu aplicación Vite en modo de desarrollo y client/dist en producción. Si tu aplicación Vite debe permanecer en la raíz del repositorio (sin carpeta client/), AppKit igualmente puede funcionar, pero la estructura recomendada es client/ + server/.

Añadir analítica a una aplicación existente

Para añadir capacidades de ejecución de consultas SQL:

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

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

Luego crea config/queries/ y añade tus archivos .sql.

Consulte también

Desarrollo local - Ejecutar el servidor de desarrollo
Configuración - Variables de entorno
Plugins - Configuración de plugins

Configuración del proyecto

Estructura canónica del proyecto

Fundamento de la estructura

Scaffolding del proyecto

package.json

client/index.html

client/src/main.tsx

client/src/App.tsx (mínimo)

client/vite.config.ts

tsconfig.json

server/server.ts