Configuração do projeto

Este guia aborda a estrutura de projeto recomendada e o scaffolding de aplicações AppKit.

Layout canônico do projeto

Estrutura recomendada (separação cliente/servidor):

my-app/
├── server/
│   ├── server.ts              # ponto de entrada do backend (AppKit)
│   └── .env                  # variáveis de ambiente locais opcionais (não versionar)
├── client/
│   ├── index.html
│   ├── vite.config.ts
│   └── src/
│       ├── main.tsx
│       └── App.tsx
├── config/
│   └── queries/
│       └── my_query.sql
├── app.yaml
├── package.json
└── tsconfig.json

Justificativa do layout

O plugin server() do AppKit serve automaticamente:

Dev: servidor de desenvolvimento do Vite (HMR) a partir de client/
Prod: arquivos estáticos de client/dist (gerados pelo Vite)

Scaffolding do projeto

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

Executando o app

# Instalar dependências
npm install

# Desenvolvimento (inicia o backend + o servidor de desenvolvimento do Vite)
npm run dev

# Build de produção
npm run build
npm start

Integrando em um aplicativo existente

Se você já tem um aplicativo React/Vite e quer adicionar o AppKit:

1. Instale as dependências

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

Se você ainda não tiver uma pasta client/, crie uma e mova sua aplicação Vite para dentro dela:

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

2. Crie `server/server.ts` (novo arquivo)

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

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

3. Atualize os scripts do `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. Concluir a configuração

O plugin de servidor do AppKit serve automaticamente seu app Vite em modo de desenvolvimento e o client/dist em produção. Se seu app Vite precisar permanecer na raiz do repositório (sem a pasta client/), o AppKit ainda assim funciona, mas o layout recomendado é client/ + server/.

Adicionar analytics a um app existente

Para adicionar recursos de execução de consultas SQL:

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

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

Em seguida, crie config/queries/ e adicione seus arquivos .sql.

Veja também

Desenvolvimento local - Executar o servidor de desenvolvimento
Configuração - Variáveis de ambiente
Plugins - Configuração de plugins

Configuração do projeto

Layout canônico do projeto

Justificativa do layout

Scaffolding do projeto

package.json

client/index.html

client/src/main.tsx

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

client/vite.config.ts

tsconfig.json

server/server.ts