Skip to content

Commit 033bcce

Browse files
ditadiditadi
committed
docs: add llms to use client/server structures
1 parent f175080 commit 033bcce

File tree

2 files changed

+75
-62
lines changed

2 files changed

+75
-62
lines changed

‎llms.txt‎

Lines changed: 73 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -25,30 +25,13 @@ This file is designed to work even when you *do not* have access to the AppKit s
2525

2626
## Canonical project layout
2727

28-
Recommended structure:
29-
30-
```
31-
my-app/
32-
├── server.ts # backend entry point (or server/index.ts for complex apps)
33-
├── index.html # Vite entry point
34-
├── vite.config.ts # Vite config
35-
├── src/
36-
│ ├── main.tsx # React entry point
37-
│ └── App.tsx # Root component
38-
├── config/
39-
│ └── queries/
40-
│ └── my_query.sql # SQL queries (optional, if using analytics)
41-
├── app.yaml # Databricks Apps config (warehouse binding)
42-
├── package.json
43-
└── tsconfig.json
44-
```
45-
46-
Alternative structure for larger apps:
28+
Recommended structure (client/server split):
4729

4830
```
4931
my-app/
5032
├── server/
51-
│ └── index.ts # backend entry point
33+
│ ├── index.ts # backend entry point (AppKit)
34+
│ └── .env # optional local dev env vars (do not commit)
5235
├── client/
5336
│ ├── index.html
5437
│ ├── vite.config.ts
@@ -63,6 +46,12 @@ my-app/
6346
└── tsconfig.json
6447
```
6548

49+
Why this layout:
50+
51+
- The AppKit `server()` plugin automatically serves:
52+
- **Dev**: Vite dev server (HMR) from `client/`
53+
- **Prod**: static files from `client/dist` (built by Vite)
54+
6655
## Project scaffolding (start here)
6756

6857
### `package.json`
@@ -74,28 +63,54 @@ my-app/
7463
"version": "0.0.0",
7564
"type": "module",
7665
"scripts": {
77-
"dev": "NODE_ENV=development tsx watch server.ts",
66+
"dev": "NODE_ENV=development tsx watch server/index.ts",
67+
"build": "npm run build:server && npm run build:client",
68+
"build:server": "tsdown --out-dir build server/index.ts",
69+
"build:client": "cd client && npm run build",
70+
"start": "node build/index.mjs"
71+
},
72+
"dependencies": {
73+
"@databricks/appkit": "^0.0.2"
74+
},
75+
"devDependencies": {
76+
"@types/node": "^20.0.0",
77+
"tsdown": "^0.15.7",
78+
"tsx": "^4.19.0",
79+
"typescript": "~5.6.0"
80+
}
81+
}
82+
```
83+
84+
### `client/package.json`
85+
86+
```json
87+
{
88+
"name": "client",
89+
"private": true,
90+
"version": "0.0.0",
91+
"type": "module",
92+
"scripts": {
93+
"dev": "vite",
7894
"build": "vite build",
79-
"start": "NODE_ENV=production tsx server.ts"
95+
"preview": "vite preview"
8096
},
8197
"dependencies": {
82-
"@databricks/appkit": "^0.0.2",
8398
"@databricks/appkit-ui": "^0.0.2",
8499
"react": "^18.0.0",
85-
"react-dom": "^18.0.0"
100+
"react-dom": "^18.0.0",
101+
"recharts": "^3.0.0"
86102
},
87103
"devDependencies": {
88104
"@types/react": "^18.0.0",
89105
"@types/react-dom": "^18.0.0",
90106
"@vitejs/plugin-react": "^5.0.0",
91-
"tsx": "^4.19.0",
92107
"typescript": "~5.6.0",
93108
"vite": "^6.0.0"
94109
}
95110
}
96111
```
97112

98-
### `index.html`
113+
### `client/index.html`
99114

100115
```html
101116
<!doctype html>
@@ -112,7 +127,7 @@ my-app/
112127
</html>
113128
```
114129

115-
### `src/main.tsx`
130+
### `client/src/main.tsx`
116131

117132
```tsx
118133
import { StrictMode } from "react";
@@ -126,7 +141,7 @@ createRoot(document.getElementById("root")!).render(
126141
);
127142
```
128143

129-
### `src/App.tsx` (minimal)
144+
### `client/src/App.tsx` (minimal)
130145

131146
```tsx
132147
export default function App() {
@@ -138,7 +153,7 @@ export default function App() {
138153
}
139154
```
140155

141-
### `vite.config.ts`
156+
### `client/vite.config.ts`
142157

143158
```ts
144159
import { defineConfig } from "vite";
@@ -165,11 +180,11 @@ export default defineConfig({
165180
"allowImportingTsExtensions": true,
166181
"verbatimModuleSyntax": true
167182
},
168-
"include": ["src", "server.ts"]
183+
"include": ["server", "client/src"]
169184
}
170185
```
171186

172-
### `server.ts`
187+
### `server/index.ts`
173188

174189
```ts
175190
import { createApp, server } from "@databricks/appkit";
@@ -184,6 +199,7 @@ await createApp({
184199
```bash
185200
# Install dependencies
186201
npm install
202+
cd client && npm install && cd ..
187203

188204
# Development (starts backend + Vite dev server)
189205
npm run dev
@@ -200,11 +216,22 @@ If you already have a React/Vite app and want to add AppKit:
200216
### 1. Install dependencies
201217

202218
```bash
203-
npm install @databricks/appkit @databricks/appkit-ui
204-
npm install -D tsx
219+
npm install @databricks/appkit
220+
npm install -D tsx tsdown
221+
222+
# If you don't already have a client/ folder, create one and move your Vite app into it:
223+
# - move index.html -> client/index.html
224+
# - move vite.config.ts -> client/vite.config.ts
225+
# - move src/ -> client/src/
226+
#
227+
# Then install client deps:
228+
cd client
229+
npm install @databricks/appkit-ui react react-dom recharts
230+
npm install -D vite @vitejs/plugin-react typescript
231+
cd ..
205232
```
206233

207-
### 2. Create `server.ts` (new file)
234+
### 2. Create `server/index.ts` (new file)
208235

209236
```ts
210237
import { createApp, server } from "@databricks/appkit";
@@ -219,23 +246,24 @@ await createApp({
219246
```json
220247
{
221248
"scripts": {
222-
"dev": "NODE_ENV=development tsx watch server.ts",
223-
"build": "vite build",
224-
"start": "NODE_ENV=production tsx server.ts"
249+
"dev": "NODE_ENV=development tsx watch server/index.ts",
250+
"build": "npm run build:server && npm run build:client",
251+
"build:server": "tsdown --out-dir build server/index.ts",
252+
"build:client": "cd client && npm run build",
253+
"start": "node build/index.mjs"
225254
}
226255
}
227256
```
228257

229258
### 4. That's it
230259

231-
- Your existing `vite.config.ts` stays the same
232-
- Your existing `src/` folder stays the same
233-
- AppKit's server plugin will automatically serve your Vite app in dev mode and the `dist/` folder in production
260+
- AppKit's server plugin will automatically serve your Vite app in dev mode and `client/dist` in production.
261+
- If your Vite app must stay at the repo root (no `client/` folder), AppKit can still work, but the recommended layout is `client/` + `server/`.
234262

235263
### Adding analytics to an existing app
236264

237265
```ts
238-
// server.ts
266+
// server/index.ts
239267
import { createApp, server, analytics } from "@databricks/appkit";
240268

241269
await createApp({
@@ -319,7 +347,7 @@ DATABRICKS_WAREHOUSE_ID=abc123...
319347
The smallest valid AppKit server:
320348

321349
```ts
322-
// server.ts (or server/index.ts)
350+
// server/index.ts
323351
import { createApp, server } from "@databricks/appkit";
324352

325353
await createApp({
@@ -980,8 +1008,9 @@ env:
9801008
- **Project setup**
9811009
- `package.json` has `"type": "module"`
9821010
- `tsx` is in devDependencies for dev server
983-
- `dev` script uses `NODE_ENV=development tsx watch server.ts`
984-
- `index.html` exists with `<div id="root"></div>` and script pointing to `src/main.tsx`
1011+
- `dev` script uses `NODE_ENV=development tsx watch server/index.ts`
1012+
- `client/index.html` exists with `<div id="root"></div>` and script pointing to `client/src/main.tsx`
1013+
- `client/package.json` exists and includes `@databricks/appkit-ui`
9851014

9861015
- **Backend**
9871016
- `await createApp({ plugins: [...] })` is used (or `void createApp` with intent)

‎packages/appkit/src/cache/index.ts‎

Lines changed: 2 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -128,20 +128,14 @@ export class CacheManager {
128128
return new CacheManager(config.storage, config);
129129
}
130130

131-
console.warn("[Cache] Provided storage health check failed");
132-
133131
if (config.strictPersistence) {
134-
console.warn(
135-
"[Cache] strictPersistence enabled but provided storage unhealthy. Cache disabled.",
136-
);
137132
const disabledConfig = { ...config, enabled: false };
138133
return new CacheManager(
139134
new InMemoryStorage(disabledConfig),
140135
disabledConfig,
141136
);
142137
}
143138

144-
console.warn("[Cache] Falling back to in-memory cache.");
145139
return new CacheManager(new InMemoryStorage(config), config);
146140
}
147141

@@ -156,28 +150,18 @@ export class CacheManager {
156150
await persistentStorage.initialize();
157151
return new CacheManager(persistentStorage, config);
158152
}
159-
160-
console.warn(
161-
"[Cache] Lakebase health check failed, default storage unhealthy",
162-
);
163-
} catch (error) {
164-
const errorMessage =
165-
error instanceof Error ? error.message : String(error);
166-
console.warn(`[Cache] Lakebase unavailable: ${errorMessage}`);
153+
} catch {
154+
// lakebase unavailable, continue with in-memory storage
167155
}
168156

169157
if (config.strictPersistence) {
170-
console.warn(
171-
"[Cache] strictPersistence enabled but lakebase unavailable. Cache disabled.",
172-
);
173158
const disabledConfig = { ...config, enabled: false };
174159
return new CacheManager(
175160
new InMemoryStorage(disabledConfig),
176161
disabledConfig,
177162
);
178163
}
179164

180-
console.warn("[Cache] Falling back to in-memory cache.");
181165
return new CacheManager(new InMemoryStorage(config), config);
182166
}
183167

0 commit comments

Comments
 (0)