refactor: move generated types into appkit-types/ directory

Consolidate generated .d.ts files into a single src/appkit-types/
directory instead of polluting client/src/ with multiple top-level
type files. TypeScript auto-discovers files via "include": ["src"].

- analytics types: src/appkit-types/analytics.d.ts
- serving types: src/appkit-types/serving.d.ts

Both generators now ensure the parent directory exists before writing.
Directory name and filenames are shared constants in type-generator.

Signed-off-by: Pawel Kosiec <pawel.kosiec@databricks.com>

Author: pkosiec

apps/dev-playground/client/.gitignore

@@ -13,7 +13,7 @@ dist-ssr
 *.local
 
 # Auto-generated types (endpoint-specific, varies per developer)
-src/appKitServingTypes.d.ts
+src/appkit-types/serving.d.ts
 
 # Editor directories and files
 .vscode/*

apps/dev-playground/client/src/appKitServingTypes.d.ts

@@ -8,15 +8,15 @@ AppKit can automatically generate TypeScript types for your SQL queries, providi
 
 ## Goal
 
-Generate `client/src/appKitTypes.d.ts` so query keys, parameters, and result rows are type-safe.
+Generate `client/src/appkit-types/analytics.d.ts` so query keys, parameters, and result rows are type-safe. All generated type files live in the `client/src/appkit-types/` directory (one file per plugin).
 
 ## Vite plugin: `appKitTypesPlugin`
 
 The recommended approach is to use the Vite plugin, which watches your SQL files and regenerates types automatically during development.
 
 ### Configuration
 
-- `outFile?: string` - Output file path (default: `src/appKitTypes.d.ts`)
+- `outFile?: string` - Output file path (default: `src/appkit-types/analytics.d.ts`)
 - `watchFolders?: string[]` - Folders to watch for SQL files (default: `["../config/queries"]`)
 
 ### Example
@@ -31,7 +31,7 @@ export default defineConfig({
   plugins: [
     react(),
     appKitTypesPlugin({
-      outFile: "src/appKitTypes.d.ts",
+      outFile: "src/appkit-types/analytics.d.ts",
       watchFolders: ["../config/queries"],
     }),
   ],
@@ -56,13 +56,13 @@ npx @databricks/appkit generate-types [rootDir] [outFile] [warehouseId]
 - Generate types using warehouse ID from environment
 
   ```bash
-  npx @databricks/appkit generate-types . client/src/appKitTypes.d.ts
+  npx @databricks/appkit generate-types . client/src/appkit-types/analytics.d.ts
   ```
 
 - Generate types using warehouse ID explicitly
 
   ```bash
-  npx @databricks/appkit generate-types . client/src/appKitTypes.d.ts abc123...
+  npx @databricks/appkit generate-types . client/src/appkit-types/analytics.d.ts abc123...
   ```
 
 - Force regeneration (skip cache)

…v-playground/client/src/appKitTypes.d.ts …d/client/src/appkit-types/analytics.d.tsapps/dev-playground/client/src/appKitTypes.d.ts renamed to apps/dev-playground/client/src/appkit-types/analytics.d.ts apps/dev-playground/client/src/appKitTypes.d.ts renamed to apps/dev-playground/client/src/appkit-types/analytics.d.ts

@@ -136,7 +136,7 @@ function SpendTable() {
 Augment the `QueryRegistry` interface to get full type inference on parameters and results:
 
 ```ts
-// config/appKitTypes.d.ts
+// client/src/appkit-types/analytics.d.ts
 declare module "@databricks/appkit-ui/react" {
   interface QueryRegistry {
     spend_summary: {

docs/docs/development/type-generation.md

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import path from "node:path";
 import dotenv from "dotenv";
 import { createLogger } from "../logging/logger";
 import { generateQueriesFromDescribe } from "./query-registry";
@@ -83,6 +84,7 @@ export async function generateFromEntryPoint(options: {
 
   const typeDeclarations = generateTypeDeclarations(queryRegistry);
 
+  await fs.mkdir(path.dirname(outFile), { recursive: true });
   await fs.writeFile(outFile, typeDeclarations, "utf-8");
 
   logger.debug("Type generation complete!");
@@ -92,3 +94,10 @@ export async function generateFromEntryPoint(options: {
 // A local binding ensures the serving vite plugin's import keeps this in the dependency graph,
 // mirroring how generateFromEntryPoint (also defined here) is preserved via the analytics vite plugin.
 export const generateServingTypes = generateServingTypesImpl;
+
+/** Directory name for generated AppKit type declaration files. */
+export const TYPES_DIR = "appkit-types";
+/** Default filename for analytics query type declarations. */
+export const ANALYTICS_TYPES_FILE = "analytics.d.ts";
+/** Default filename for serving endpoint type declarations. */
+export const SERVING_TYPES_FILE = "serving.d.ts";

docs/docs/plugins/analytics.md

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import path from "node:path";
 import { WorkspaceClient } from "@databricks/sdk-experimental";
 import pc from "picocolors";
 import { createLogger } from "../../logging/logger";
@@ -73,6 +74,7 @@ export async function generateServingTypes(
   printLogTable(logEntries, startTime);
 
   const output = generateTypeDeclarations(registryEntries);
+  await fs.mkdir(path.dirname(outFile), { recursive: true });
   await fs.writeFile(outFile, output, "utf-8");
 
   if (registryEntries.length === 0) {

packages/appkit/src/type-generator/index.ts

@@ -91,6 +91,7 @@ describe("generateServingTypes", () => {
   const outFile = "/tmp/test-serving-types.d.ts";
 
   beforeEach(() => {
+    vi.mocked(fs.mkdir).mockResolvedValue(undefined);
     vi.mocked(fs.writeFile).mockResolvedValue();
     process.env.TEST_SERVING_ENDPOINT = "my-endpoint";
   });

packages/appkit/src/type-generator/serving/generator.ts

@@ -79,7 +79,7 @@ describe("appKitServingTypesPlugin", () => {
       expect(mockGenerateServingTypes).toHaveBeenCalledWith(
         expect.objectContaining({
           outFile: expect.stringContaining(
-            "/app/client/src/appKitServingTypes.d.ts",
+            "/app/client/src/appkit-types/serving.d.ts",
           ),
         }),
       );

packages/appkit/src/type-generator/serving/tests/generator.test.ts

@@ -2,7 +2,7 @@ import path from "node:path";
 import type { Plugin } from "vite";
 import { createLogger } from "../../logging/logger";
 import type { EndpointConfig } from "../../plugins/serving/types";
-import { generateServingTypes } from "../index";
+import { generateServingTypes, SERVING_TYPES_FILE, TYPES_DIR } from "../index";
 import {
   extractServingEndpoints,
   findServerFile,
@@ -96,7 +96,7 @@ export function appKitServingTypesPlugin(
       projectRoot = path.resolve(config.root, "..");
       outFile = path.resolve(
         config.root,
-        options?.outFile ?? "src/appKitServingTypes.d.ts",
+        options?.outFile ?? `src/${TYPES_DIR}/${SERVING_TYPES_FILE}`,
       );
     },