---
sidebar_position: 4
---
# Project setup
This guide covers the recommended project structure and scaffolding for AppKit applications.
## Canonical project layout
Recommended structure (client/server split):
```
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
The AppKit `server()` plugin automatically serves:
- **Dev**: Vite dev server (HMR) from `client/`
- **Prod**: static files from `client/dist` (built by Vite)
## Project scaffolding
### `package.json`
```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`
```html
My App
```
### `client/src/main.tsx`
```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)
```tsx
export default function App() {
return (
My App
);
}
```
### `client/vite.config.ts`
```ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig({
plugins: [react()],
});
```
### `tsconfig.json`
```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`
```ts
import { createApp, server } from "@databricks/appkit";
await createApp({
plugins: [server()],
});
```
## 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
If you already have a React/Vite app and want to add AppKit:
### 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)
```ts
import { createApp, server } from "@databricks/appkit";
await createApp({
plugins: [server()],
});
```
### 3. Update `package.json` 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
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
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
- [Local development](./local-development.mdx) - Running the dev server
- [Configuration](../configuration.mdx) - Environment variables
- [Plugins](../plugins/index.md) - Plugin configuration