# Project setup
This guide covers the recommended project structure and scaffolding for AppKit applications.
## Canonical project layout[](#canonical-project-layout "Direct link to Canonical project layout")
Recommended structure (client/server split):
```text
my-app/
├── server/
│ ├── server.ts # backend entry point (AppKit)
│ └── .env # optional local dev env vars (do not commit)
├── client/
│ ├── index.html
│ ├── vite.config.ts
│ └── src/
│ ├── main.tsx
│ └── App.tsx
├── config/
│ └── queries/
│ └── my_query.sql
├── app.yaml
├── package.json
└── tsconfig.json
```
### Layout rationale[](#layout-rationale "Direct link to Layout rationale")
The AppKit `server()` plugin automatically serves:
* **Dev**: Vite dev server (HMR) from `client/`
* **Prod**: static files from `client/dist` (built by Vite)
## Project scaffolding[](#project-scaffolding "Direct link to Project scaffolding")
### `package.json`[](#packagejson "Direct link to packagejson")
```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`[](#clientindexhtml "Direct link to clientindexhtml")
```html
My App
```
### `client/src/main.tsx`[](#clientsrcmaintsx "Direct link to clientsrcmaintsx")
```tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App";
createRoot(document.getElementById("root")!).render(
,
);
```
### `client/src/App.tsx` (Minimal)[](#clientsrcapptsx-minimal "Direct link to clientsrcapptsx-minimal")
```tsx
export default function App() {
return (
My App
);
}
```
### `client/vite.config.ts`[](#clientviteconfigts "Direct link to clientviteconfigts")
```ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig({
plugins: [react()],
});
```
### `tsconfig.json`[](#tsconfigjson "Direct link to tsconfigjson")
```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`[](#serverserverts "Direct link to serverserverts")
```ts
import { createApp, server } from "@databricks/appkit";
await createApp({
plugins: [server()],
});
```
## Running the app[](#running-the-app "Direct link to Running the app")
```bash
# Install dependencies
npm install
# Development (starts backend + Vite dev server)
npm run dev
# Production build
npm run build
npm start
```
## Integrating into an existing app[](#integrating-into-an-existing-app "Direct link to Integrating into an existing app")
If you already have a React/Vite app and want to add AppKit:
### 1. Install dependencies[](#1-install-dependencies "Direct link to 1. Install dependencies")
```bash
npm install @databricks/appkit @databricks/appkit-ui react react-dom
npm install -D tsx tsdown vite @vitejs/plugin-react typescript
```
If you don't already have a `client/` folder, create one and move your Vite app into it:
* Move `index.html` → `client/index.html`
* Move `vite.config.ts` → `client/vite.config.ts`
* Move `src/` → `client/src/`
### 2. Create `server/server.ts` (New File)[](#2-create-serverserverts-new-file "Direct link to 2-create-serverserverts-new-file")
```ts
import { createApp, server } from "@databricks/appkit";
await createApp({
plugins: [server()],
});
```
### 3. Update `package.json` Scripts[](#3-update-packagejson-scripts "Direct link to 3-update-packagejson-scripts")
```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. Complete setup[](#4-complete-setup "Direct link to 4. Complete setup")
AppKit's server plugin will automatically serve your Vite app in dev mode and `client/dist` in production. If your Vite app must stay at the repo root (no `client/` folder), AppKit can still work, but the recommended layout is `client/` + `server/`.
## Adding analytics to an existing app[](#adding-analytics-to-an-existing-app "Direct link to Adding analytics to an existing app")
To add SQL query execution capabilities:
```ts
// server/server.ts
import { createApp, server, analytics } from "@databricks/appkit";
await createApp({
plugins: [server(), analytics()],
});
```
Then create `config/queries/` and add your `.sql` files.
## See also[](#see-also "Direct link to See also")
* [Local development](./docs/development/local-development.md) - Running the dev server
* [Configuration](./docs/configuration.md) - Environment variables
* [Plugins](./docs/plugins.md) - Plugin configuration