@databricks/appkit 0.25.1 → 0.26.0

package/dist/errors/server.d.ts

@@ -7,7 +7,6 @@ import { AppKitError } from "./base.js";
  *
  * @example
  * ```typescript
- * throw new ServerError("Cannot get server when autoStart is true");
  * throw new ServerError("Server not started");
  * ```
  */
@@ -15,10 +14,6 @@ declare class ServerError extends AppKitError {
   readonly code = "SERVER_ERROR";
   readonly statusCode = 500;
   readonly isRetryable = false;
-  /**
-   * Create a server error for autoStart conflict
-   */
-  static autoStartConflict(operation: string): ServerError;
   /**
    * Create a server error for server not started
    */

package/dist/errors/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","names":[],"sources":["../../src/errors/server.ts"],"mappings":";;;;;AAYA;;;;;;;;cAAa,WAAA,SAAoB,WAAA;EAAA,SACtB,IAAA;EAAA,SACA,UAAA;EAAA,SACA,WAAA;EADA;;;EAAA,OAMF,iBAAA,CAAkB,SAAA,WAAoB,WAAA;EAAA;;;EAAA,OAStC,UAAA,CAAA,GAAc,WAAA;EASQ;;;EAAA,OAAtB,kBAAA,CAAA,GAAsB,WAAA;EAOuC;;;EAAA,OAA7D,uBAAA,CAAwB,aAAA,aAA0B,WAAA;AAAA"}
+{"version":3,"file":"server.d.ts","names":[],"sources":["../../src/errors/server.ts"],"mappings":";;;;;AAWA;;;;;;;cAAa,WAAA,SAAoB,WAAA;EAAA,SACtB,IAAA;EAAA,SACA,UAAA;EAAA,SACA,WAAA;EADA;;;EAAA,OAMF,UAAA,CAAA,GAAc,WAAA;EASd;;;EAAA,OAAA,kBAAA,CAAA,GAAsB,WAAA;EAO4B;;;EAAA,OAAlD,uBAAA,CAAwB,aAAA,aAA0B,WAAA;AAAA"}

package/dist/errors/server.js

@@ -10,12 +10,6 @@ var init_server = __esmMin((() => {
 		statusCode = 500;
 		isRetryable = false;
 		/**
-		* Create a server error for autoStart conflict
-		*/
-		static autoStartConflict(operation) {
-			return new ServerError(`Cannot ${operation} when autoStart is true`, { context: { operation } });
-		}
-		/**
 		* Create a server error for server not started
 		*/
 		static notStarted() {

package/dist/errors/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","names":[],"sources":["../../src/errors/server.ts"],"sourcesContent":["import { AppKitError } from \"./base\";\n\n/**\n * Error thrown when server lifecycle operations fail.\n * Use for server start/stop issues, configuration conflicts, etc.\n *\n * @example\n * ```typescript\n * throw new ServerError(\"Cannot get server when autoStart is true\");\n * throw new ServerError(\"Server not started\");\n * ```\n */\nexport class ServerError extends AppKitError {\n  readonly code = \"SERVER_ERROR\";\n  readonly statusCode = 500;\n  readonly isRetryable = false;\n\n  /**\n   * Create a server error for autoStart conflict\n   */\n  static autoStartConflict(operation: string): ServerError {\n    return new ServerError(`Cannot ${operation} when autoStart is true`, {\n      context: { operation },\n    });\n  }\n\n  /**\n   * Create a server error for server not started\n   */\n  static notStarted(): ServerError {\n    return new ServerError(\n      \"Server not started. Please start the server first by calling the start() method\",\n    );\n  }\n\n  /**\n   * Create a server error for Vite dev server not initialized\n   */\n  static viteNotInitialized(): ServerError {\n    return new ServerError(\"Vite dev server not initialized\");\n  }\n\n  /**\n   * Create a server error for missing client directory\n   */\n  static clientDirectoryNotFound(searchedPaths: string[]): ServerError {\n    return new ServerError(\n      `Could not find client directory. Searched for vite.config.ts/js + index.html in: ${searchedPaths.join(\", \")}`,\n      { context: { searchedPaths } },\n    );\n  }\n}\n"],"mappings":";;;;;;YAAqC;CAYxB,cAAb,MAAa,oBAAoB,YAAY;EAC3C,AAAS,OAAO;EAChB,AAAS,aAAa;EACtB,AAAS,cAAc;;;;EAKvB,OAAO,kBAAkB,WAAgC;AACvD,UAAO,IAAI,YAAY,UAAU,UAAU,0BAA0B,EACnE,SAAS,EAAE,WAAW,EACvB,CAAC;;;;;EAMJ,OAAO,aAA0B;AAC/B,UAAO,IAAI,YACT,kFACD;;;;;EAMH,OAAO,qBAAkC;AACvC,UAAO,IAAI,YAAY,kCAAkC;;;;;EAM3D,OAAO,wBAAwB,eAAsC;AACnE,UAAO,IAAI,YACT,oFAAoF,cAAc,KAAK,KAAK,IAC5G,EAAE,SAAS,EAAE,eAAe,EAAE,CAC/B"}
+{"version":3,"file":"server.js","names":[],"sources":["../../src/errors/server.ts"],"sourcesContent":["import { AppKitError } from \"./base\";\n\n/**\n * Error thrown when server lifecycle operations fail.\n * Use for server start/stop issues, configuration conflicts, etc.\n *\n * @example\n * ```typescript\n * throw new ServerError(\"Server not started\");\n * ```\n */\nexport class ServerError extends AppKitError {\n  readonly code = \"SERVER_ERROR\";\n  readonly statusCode = 500;\n  readonly isRetryable = false;\n\n  /**\n   * Create a server error for server not started\n   */\n  static notStarted(): ServerError {\n    return new ServerError(\n      \"Server not started. Please start the server first by calling the start() method\",\n    );\n  }\n\n  /**\n   * Create a server error for Vite dev server not initialized\n   */\n  static viteNotInitialized(): ServerError {\n    return new ServerError(\"Vite dev server not initialized\");\n  }\n\n  /**\n   * Create a server error for missing client directory\n   */\n  static clientDirectoryNotFound(searchedPaths: string[]): ServerError {\n    return new ServerError(\n      `Could not find client directory. Searched for vite.config.ts/js + index.html in: ${searchedPaths.join(\", \")}`,\n      { context: { searchedPaths } },\n    );\n  }\n}\n"],"mappings":";;;;;;YAAqC;CAWxB,cAAb,MAAa,oBAAoB,YAAY;EAC3C,AAAS,OAAO;EAChB,AAAS,aAAa;EACtB,AAAS,cAAc;;;;EAKvB,OAAO,aAA0B;AAC/B,UAAO,IAAI,YACT,kFACD;;;;;EAMH,OAAO,qBAAkC;AACvC,UAAO,IAAI,YAAY,kCAAkC;;;;;EAM3D,OAAO,wBAAwB,eAAsC;AACnE,UAAO,IAAI,YACT,oFAAoF,cAAc,KAAK,KAAK,IAC5G,EAAE,SAAS,EAAE,eAAe,EAAE,CAC/B"}

package/dist/plugins/server/index.d.ts

@@ -15,17 +15,23 @@ import express from "express";
  * This plugin is responsible for starting the server and serving the static files.
  * It also handles the remote tunneling for development purposes.
  *
+ * The server is started automatically by `createApp` after all plugins are set up
+ * and the optional `onPluginsReady` callback has run.
+ *
  * @example
  * ```ts
  * createApp({
- *   plugins: [server(), telemetryExamples(), analytics({})],
+ *   plugins: [server(), analytics({})],
+ *   onPluginsReady(appkit) {
+ *     appkit.server.extend((app) => {
+ *       app.get("/custom", (_req, res) => res.json({ ok: true }));
+ *     });
+ *   },
  * });
  * ```
- *
  */
 declare class ServerPlugin extends Plugin {
   static DEFAULT_CONFIG: {
-    autoStart: boolean;
     host: string;
     port: number;
   };
@@ -40,20 +46,16 @@ declare class ServerPlugin extends Plugin {
   private rawBodyPaths;
   static phase: PluginPhase;
   constructor(config: ServerConfig);
-  /** Setup the server plugin. */
   setup(): Promise<void>;
   /** Get the server configuration. */
   getConfig(): {
     [key: string]: unknown;
     port?: number;
     staticPath?: string;
-    autoStart?: boolean;
     host?: string;
     name?: string;
     telemetry?: TelemetryOptions;
   };
-  /** Check if the server should auto start. */
-  shouldAutoStart(): boolean | undefined;
   /**
    * Start the server.
    *
@@ -68,16 +70,18 @@ declare class ServerPlugin extends Plugin {
    *
    * Only use this method if you need to access the server instance for advanced usage like a custom websocket server, etc.
    *
-   * @throws {Error} If the server is not started or autoStart is true.
+   * @throws {Error} If the server has not started yet.
    * @returns {HTTPServer} The server instance.
    */
   getServer(): Server;
   /**
    * Extend the server with custom routes or middleware.
    *
+   * Call this inside the `onPluginsReady` callback of `createApp` to register
+   * custom Express routes or middleware before the server starts listening.
+   *
    * @param fn - A function that receives the express application.
    * @returns The server plugin instance for chaining.
-   * @throws {Error} If autoStart is true.
    */
   extend(fn: (app: express.Application) => void): this;
   /**
@@ -103,18 +107,17 @@ declare class ServerPlugin extends Plugin {
    * Exposes server management methods.
    */
   exports(): {
-    /** Start the server */start: () => Promise<express.Application>; /** Extend the server with custom routes or middleware */
-    extend(fn: (app: express.Application) => void): /*elided*/any; /** Get the underlying HTTP server instance */
+    /** Extend the server with custom routes or middleware */extend(fn: (app: express.Application) => void): /*elided*/any; /** Get the underlying HTTP server instance */
     getServer: () => Server; /** Get the server configuration */
     getConfig: () => {
       [key: string]: unknown;
       port?: number;
       staticPath?: string;
-      autoStart?: boolean;
       host?: string;
       name?: string;
       telemetry?: TelemetryOptions;
-    };
+    }; /** @deprecated Server is now started automatically by createApp. */
+    start(): never;
   };
 }
 /**

package/dist/plugins/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/plugins/server/index.ts"],"mappings":";;;;;;;;;;;;;;;;AAqCA;;;;;;;;;cAAa,YAAA,SAAqB,MAAA;EAAA,OAClB,cAAA;;;;;EAoWO;EAAA,OA7Vd,QAAA,EAAuB,cAAA;EAAA,QACtB,iBAAA;EAAA,QACA,MAAA;EAAA,QACA,aAAA;EAAA,QACA,sBAAA;EAAA,UACU,MAAA,EAAQ,YAAA;EAAA,QAClB,gBAAA;EAAA,QACA,YAAA;EAAA,OACD,KAAA,EAAO,WAAA;cAEF,MAAA,EAAQ,YAAA;EAVb;EAuBD,KAAA,CAAA,GAAK,OAAA;EAtBH;EA6BR,SAAA,CAAA;IAAA;;;;;;gBAPW,gBAAA;EAAA;;EAcX,eAAA,CAAA;EA3BY;;;;;;;;EAuCN,KAAA,CAAA,GAAS,OAAA,CAAQ,OAAA,CAAQ,WAAA;;;;;;;;;EA2D/B,SAAA,CAAA,GAAa,MAAA;EAAA;;;;;;;EAmBb,MAAA,CAAO,EAAA,GAAK,GAAA,EAAK,OAAA,CAAQ,WAAA;EA8HV;;;;;;;EAAA,QA9GD,YAAA;;;;;;;UAkEA,aAAA;EAAA,eA4CC,cAAA;EAAA,QAaP,cAAA;EAAA,QA4BM,iBAAA;;;;;EAiDd,OAAA,CAAA;wCAtSe,OAAA,CAAQ,OAAA,CAAQ,WAAA;gBA4Sf,GAAA,EAAK,OAAA,CAAQ,WAAA,YAiBa,eAAA;qBAlQ7B,MAAA,EAkQI;;;;;;;;kBAlQM,gBAAA;IAAA;EAAA;AAAA;;;;cAkQZ,MAAA,EAAM,QAAA,QAAA,YAAA,EAAA,YAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/plugins/server/index.ts"],"mappings":";;;;;;;;;;;;;;;;AA4CA;;;;;;;;;;;;;;;;cAAa,YAAA,SAAqB,MAAA;EAAA,OAClB,cAAA;;;;;SAMP,QAAA,EAAuB,cAAA;EAAA,QACtB,iBAAA;EAAA,QACA,MAAA;EAAA,QACA,aAAA;EAAA,QACA,sBAAA;EAAA,UACU,MAAA,EAAQ,YAAA;EAAA,QAClB,gBAAA;EAAA,QACA,YAAA;EAAA,OACD,KAAA,EAAO,WAAA;cAEF,MAAA,EAAQ,YAAA;EAmBd,KAAA,CAAA,GAAK,OAAA;EArBJ;EAwBP,SAAA,CAAA;IAAA;;;;;gBAHW,gBAAA;EAAA;;;;;;;;;EAiBL,KAAA,CAAA,GAAS,OAAA,CAAQ,OAAA,CAAQ,WAAA;EAAA;;;;;;;;EA2D/B,SAAA,CAAA,GAAa,MAAA;EA+FC;;;;;;;;;EA9Ed,MAAA,CAAO,EAAA,GAAK,GAAA,EAAK,OAAA,CAAQ,WAAA;;;;;;;;UAYX,YAAA;;;;;;AA0OhB;UAxKgB,aAAA;EAAA,eA4CC,cAAA;EAAA,QAaP,cAAA;EAAA,QA4BM,iBAAA;EAmFG;;;;EAlCjB,OAAA,CAAA;IAkCiB,qEA9BD,GAAA,EAAK,OAAA,CAAQ,WAAA,YA8BZ,eAAA;qBAvQJ,MAAA;;;;;;;kBAAU,gBAAA;IAAA;;;;;;;cAuQZ,MAAA,EAAM,QAAA,QAAA,YAAA,EAAA,YAAA"}

package/dist/plugins/server/index.js

@@ -27,17 +27,23 @@ const logger = createLogger("server");
 * This plugin is responsible for starting the server and serving the static files.
 * It also handles the remote tunneling for development purposes.
 *
+* The server is started automatically by `createApp` after all plugins are set up
+* and the optional `onPluginsReady` callback has run.
+*
 * @example
 * ```ts
 * createApp({
-*   plugins: [server(), telemetryExamples(), analytics({})],
+*   plugins: [server(), analytics({})],
+*   onPluginsReady(appkit) {
+*     appkit.server.extend((app) => {
+*       app.get("/custom", (_req, res) => res.json({ ok: true }));
+*     });
+*   },
 * });
 * ```
-*
 */
 var ServerPlugin = class ServerPlugin extends Plugin {
 	static DEFAULT_CONFIG = {
-		autoStart: true,
 		host: process.env.FLASK_RUN_HOST || "0.0.0.0",
 		port: Number(process.env.DATABRICKS_APP_PORT) || 8e3
 	};
@@ -51,6 +57,7 @@ var ServerPlugin = class ServerPlugin extends Plugin {
 	rawBodyPaths = /* @__PURE__ */ new Set();
 	static phase = "deferred";
 	constructor(config) {
+		if ("autoStart" in config) throw new ServerError("server({ autoStart }) has been removed. The server is now started automatically by createApp.\n\nRun `npx appkit codemod on-plugins-ready --write` to auto-migrate.");
 		super(config);
 		this.config = config;
 		this.serverApplication = express();
@@ -58,19 +65,12 @@ var ServerPlugin = class ServerPlugin extends Plugin {
 		this.serverExtensions = [];
 		this.telemetry.registerInstrumentations([instrumentations.http, instrumentations.express]);
 	}
-	/** Setup the server plugin. */
-	async setup() {
-		if (this.shouldAutoStart()) await this.start();
-	}
+	async setup() {}
 	/** Get the server configuration. */
 	getConfig() {
 		const { plugins: _plugins, ...config } = this.config;
 		return config;
 	}
-	/** Check if the server should auto start. */
-	shouldAutoStart() {
-		return this.config.autoStart;
-	}
 	/**
 	* Start the server.
 	*
@@ -103,23 +103,23 @@ var ServerPlugin = class ServerPlugin extends Plugin {
 	*
 	* Only use this method if you need to access the server instance for advanced usage like a custom websocket server, etc.
 	*
-	* @throws {Error} If the server is not started or autoStart is true.
+	* @throws {Error} If the server has not started yet.
 	* @returns {HTTPServer} The server instance.
 	*/
 	getServer() {
-		if (this.shouldAutoStart()) throw ServerError.autoStartConflict("get server");
 		if (!this.server) throw ServerError.notStarted();
 		return this.server;
 	}
 	/**
 	* Extend the server with custom routes or middleware.
 	*
+	* Call this inside the `onPluginsReady` callback of `createApp` to register
+	* custom Express routes or middleware before the server starts listening.
+	*
 	* @param fn - A function that receives the express application.
 	* @returns The server plugin instance for chaining.
-	* @throws {Error} If autoStart is true.
 	*/
 	extend(fn) {
-		if (this.shouldAutoStart()) throw ServerError.autoStartConflict("extend server");
 		this.serverExtensions.push(fn);
 		return this;
 	}
@@ -245,13 +245,15 @@ var ServerPlugin = class ServerPlugin extends Plugin {
 	exports() {
 		const self = this;
 		return {
-			start: this.start,
 			extend(fn) {
 				self.extend(fn);
 				return this;
 			},
 			getServer: this.getServer,
-			getConfig: this.getConfig
+			getConfig: this.getConfig,
+			start() {
+				throw new ServerError("server.start() has been removed. Use the onPluginsReady callback instead:\n\n  createApp({\n    plugins: [server(), ...],\n    onPluginsReady(appkit) {\n      appkit.server.extend(...);\n    },\n  });\n\nRun `npx appkit codemod on-plugins-ready --write` to auto-migrate.");
+			}
 		};
 	}
 };

package/dist/plugins/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["manifest"],"sources":["../../../src/plugins/server/index.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport type { Server as HTTPServer } from \"node:http\";\nimport path from \"node:path\";\nimport dotenv from \"dotenv\";\nimport express from \"express\";\nimport type { PluginClientConfigs, PluginPhase } from \"shared\";\nimport { ServerError } from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest } from \"../../registry\";\nimport { instrumentations } from \"../../telemetry\";\nimport { sanitizeClientConfig } from \"./client-config-sanitizer\";\nimport manifest from \"./manifest.json\";\nimport { RemoteTunnelController } from \"./remote-tunnel/remote-tunnel-controller\";\nimport { StaticServer } from \"./static-server\";\nimport type { ServerConfig } from \"./types\";\nimport { getRoutes, type PluginEndpoints, printRoutes } from \"./utils\";\nimport { ViteDevServer } from \"./vite-dev-server\";\n\ndotenv.config({ path: path.resolve(process.cwd(), \"./.env\") });\n\nconst logger = createLogger(\"server\");\n\n/**\n * Server plugin for the AppKit.\n *\n * This plugin is responsible for starting the server and serving the static files.\n * It also handles the remote tunneling for development purposes.\n *\n * @example\n * ```ts\n * createApp({\n *   plugins: [server(), telemetryExamples(), analytics({})],\n * });\n * ```\n *\n */\nexport class ServerPlugin extends Plugin {\n  public static DEFAULT_CONFIG = {\n    autoStart: true,\n    host: process.env.FLASK_RUN_HOST || \"0.0.0.0\",\n    port: Number(process.env.DATABRICKS_APP_PORT) || 8000,\n  };\n\n  /** Plugin manifest declaring metadata and resource requirements */\n  static manifest = manifest as PluginManifest<\"server\">;\n  private serverApplication: express.Application;\n  private server: HTTPServer | null;\n  private viteDevServer?: ViteDevServer;\n  private remoteTunnelController?: RemoteTunnelController;\n  protected declare config: ServerConfig;\n  private serverExtensions: ((app: express.Application) => void)[] = [];\n  private rawBodyPaths: Set<string> = new Set();\n  static phase: PluginPhase = \"deferred\";\n\n  constructor(config: ServerConfig) {\n    super(config);\n    this.config = config;\n    this.serverApplication = express();\n    this.server = null;\n    this.serverExtensions = [];\n    this.telemetry.registerInstrumentations([\n      instrumentations.http,\n      instrumentations.express,\n    ]);\n  }\n\n  /** Setup the server plugin. */\n  async setup() {\n    if (this.shouldAutoStart()) {\n      await this.start();\n    }\n  }\n\n  /** Get the server configuration. */\n  getConfig() {\n    const { plugins: _plugins, ...config } = this.config;\n\n    return config;\n  }\n\n  /** Check if the server should auto start. */\n  shouldAutoStart() {\n    return this.config.autoStart;\n  }\n\n  /**\n   * Start the server.\n   *\n   * This method starts the server and sets up the frontend.\n   * It also sets up the remote tunneling if enabled.\n   *\n   * @returns The express application.\n   */\n  async start(): Promise<express.Application> {\n    this.serverApplication.use(\n      express.json({\n        type: (req) => {\n          // Skip JSON parsing for routes that declared skipBodyParsing\n          // (e.g. file uploads where the raw body must flow through).\n          // rawBodyPaths is populated by extendRoutes() below; the type\n          // callback runs per-request so the set is already filled.\n          const urlPath = req.url?.split(\"?\")[0];\n          if (urlPath && this.rawBodyPaths.has(urlPath)) return false;\n          const ct = req.headers[\"content-type\"] ?? \"\";\n          return ct.includes(\"json\");\n        },\n      }),\n    );\n\n    const { endpoints, pluginConfigs } = await this.extendRoutes();\n\n    for (const extension of this.serverExtensions) {\n      extension(this.serverApplication);\n    }\n\n    // register remote tunnel controller (before static/vite)\n    this.remoteTunnelController = new RemoteTunnelController(\n      this.devFileReader,\n    );\n    this.serverApplication.use(this.remoteTunnelController.middleware);\n\n    await this.setupFrontend(endpoints, pluginConfigs);\n\n    const server = this.serverApplication.listen(\n      this.config.port ?? ServerPlugin.DEFAULT_CONFIG.port,\n      this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host,\n      () => this.logStartupInfo(),\n    );\n\n    this.server = server;\n\n    // attach server to remote tunnel controller\n    this.remoteTunnelController.setServer(server);\n\n    process.on(\"SIGTERM\", () => this._gracefulShutdown());\n    process.on(\"SIGINT\", () => this._gracefulShutdown());\n\n    if (process.env.NODE_ENV === \"development\") {\n      const allRoutes = getRoutes(this.serverApplication._router.stack);\n      printRoutes(allRoutes);\n    }\n    return this.serverApplication;\n  }\n\n  /**\n   * Get the low level node.js http server instance.\n   *\n   * Only use this method if you need to access the server instance for advanced usage like a custom websocket server, etc.\n   *\n   * @throws {Error} If the server is not started or autoStart is true.\n   * @returns {HTTPServer} The server instance.\n   */\n  getServer(): HTTPServer {\n    if (this.shouldAutoStart()) {\n      throw ServerError.autoStartConflict(\"get server\");\n    }\n\n    if (!this.server) {\n      throw ServerError.notStarted();\n    }\n\n    return this.server;\n  }\n\n  /**\n   * Extend the server with custom routes or middleware.\n   *\n   * @param fn - A function that receives the express application.\n   * @returns The server plugin instance for chaining.\n   * @throws {Error} If autoStart is true.\n   */\n  extend(fn: (app: express.Application) => void) {\n    if (this.shouldAutoStart()) {\n      throw ServerError.autoStartConflict(\"extend server\");\n    }\n\n    this.serverExtensions.push(fn);\n    return this;\n  }\n\n  /**\n   * Setup the routes with the plugins.\n   *\n   * This method goes through all the plugins and injects the routes into the server application.\n   * Returns a map of plugin names to their registered named endpoints,\n   * and a map of plugin names to their client-exposed configs.\n   */\n  private async extendRoutes(): Promise<{\n    endpoints: PluginEndpoints;\n    pluginConfigs: PluginClientConfigs;\n  }> {\n    const endpoints: PluginEndpoints = {};\n    const pluginConfigs: PluginClientConfigs = {};\n\n    if (!this.config.plugins) return { endpoints, pluginConfigs };\n\n    this.serverApplication.get(\"/health\", (_, res) => {\n      res.status(200).json({ status: \"ok\" });\n    });\n    this.registerEndpoint(\"health\", \"/health\");\n\n    for (const plugin of Object.values(this.config.plugins)) {\n      if (EXCLUDED_PLUGINS.includes(plugin.name)) continue;\n\n      if (plugin?.injectRoutes && typeof plugin.injectRoutes === \"function\") {\n        const router = express.Router();\n\n        plugin.injectRoutes(router);\n\n        const basePath = `/api/${plugin.name}`;\n        this.serverApplication.use(basePath, router);\n\n        endpoints[plugin.name] = plugin.getEndpoints();\n\n        // Collect paths that should skip body parsing\n        if (\n          plugin.getSkipBodyParsingPaths &&\n          typeof plugin.getSkipBodyParsingPaths === \"function\"\n        ) {\n          for (const p of plugin.getSkipBodyParsingPaths()) {\n            this.rawBodyPaths.add(p);\n          }\n        }\n      }\n\n      if (typeof plugin.clientConfig === \"function\") {\n        try {\n          const raw = plugin.clientConfig();\n          if (raw != null) {\n            const sanitized = sanitizeClientConfig(plugin.name, raw);\n            if (Object.keys(sanitized).length > 0) {\n              pluginConfigs[plugin.name] = sanitized;\n            }\n          }\n        } catch (error) {\n          logger.error(\n            \"Plugin '%s' clientConfig() failed, skipping its config: %O\",\n            plugin.name,\n            error,\n          );\n        }\n      }\n    }\n\n    return { endpoints, pluginConfigs };\n  }\n\n  /**\n   * Setup frontend serving based on environment:\n   * - If staticPath is explicitly provided: use static server\n   * - Dev mode (no staticPath): Vite for HMR\n   * - Production (no staticPath): Static files auto-detected\n   */\n  private async setupFrontend(\n    endpoints: PluginEndpoints,\n    pluginConfigs: PluginClientConfigs,\n  ) {\n    const isDev = process.env.NODE_ENV === \"development\";\n    const hasExplicitStaticPath = this.config.staticPath !== undefined;\n\n    // explict static path provided\n    if (hasExplicitStaticPath) {\n      const staticServer = new StaticServer(\n        this.serverApplication,\n        this.config.staticPath as string,\n        endpoints,\n        pluginConfigs,\n      );\n      staticServer.setup();\n      return;\n    }\n\n    // auto-detection based on environment\n    if (isDev) {\n      this.viteDevServer = new ViteDevServer(\n        this.serverApplication,\n        endpoints,\n        pluginConfigs,\n      );\n      await this.viteDevServer.setup();\n      return;\n    }\n\n    // auto-detection based on static path\n    const staticPath = ServerPlugin.findStaticPath();\n    if (staticPath) {\n      const staticServer = new StaticServer(\n        this.serverApplication,\n        staticPath,\n        endpoints,\n        pluginConfigs,\n      );\n\n      staticServer.setup();\n    }\n  }\n\n  private static findStaticPath() {\n    const staticPaths = [\"dist\", \"client/dist\", \"build\", \"public\", \"out\"];\n    const cwd = process.cwd();\n    for (const p of staticPaths) {\n      const fullPath = path.resolve(cwd, p);\n      if (fs.existsSync(path.resolve(fullPath, \"index.html\"))) {\n        logger.debug(\"Static files: serving from %s\", fullPath);\n        return fullPath;\n      }\n    }\n    return undefined;\n  }\n\n  private logStartupInfo() {\n    const isDev = process.env.NODE_ENV === \"development\";\n    const hasExplicitStaticPath = this.config.staticPath !== undefined;\n    const port = this.config.port ?? ServerPlugin.DEFAULT_CONFIG.port;\n    const host = this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host;\n\n    logger.info(\"Server running on http://%s:%d\", host, port);\n\n    if (hasExplicitStaticPath) {\n      logger.info(\"Mode: static (%s)\", this.config.staticPath);\n    } else if (isDev) {\n      logger.info(\"Mode: development (Vite HMR)\");\n    } else {\n      logger.info(\"Mode: production (static)\");\n    }\n\n    const remoteServerController = this.remoteTunnelController;\n    if (!remoteServerController) {\n      logger.debug(\"Remote tunnel: disabled (controller not initialized)\");\n    } else {\n      logger.debug(\n        \"Remote tunnel: %s; %s\",\n        remoteServerController.isAllowedByEnv() ? \"allowed\" : \"blocked\",\n        remoteServerController.isActive() ? \"active\" : \"inactive\",\n      );\n    }\n  }\n\n  private async _gracefulShutdown() {\n    logger.info(\"Starting graceful shutdown...\");\n\n    if (this.viteDevServer) {\n      await this.viteDevServer.close();\n    }\n\n    if (this.remoteTunnelController) {\n      this.remoteTunnelController.cleanup();\n    }\n\n    // 1. abort active operations from plugins\n    if (this.config.plugins) {\n      for (const plugin of Object.values(this.config.plugins)) {\n        if (plugin.abortActiveOperations) {\n          try {\n            plugin.abortActiveOperations();\n          } catch (err) {\n            logger.error(\n              \"Error aborting operations for plugin %s: %O\",\n              plugin.name,\n              err,\n            );\n          }\n        }\n      }\n    }\n\n    // 2. close the server\n    if (this.server) {\n      this.server.close(() => {\n        logger.debug(\"Server closed gracefully\");\n        process.exit(0);\n      });\n\n      // 3. timeout to force shutdown after 15 seconds\n      setTimeout(() => {\n        logger.debug(\"Force shutdown after timeout\");\n        process.exit(1);\n      }, 15000);\n    } else {\n      process.exit(0);\n    }\n  }\n\n  /**\n   * Returns the public exports for the server plugin.\n   * Exposes server management methods.\n   */\n  exports() {\n    const self = this;\n    return {\n      /** Start the server */\n      start: this.start,\n      /** Extend the server with custom routes or middleware */\n      extend(fn: (app: express.Application) => void) {\n        self.extend(fn);\n        return this;\n      },\n      /** Get the underlying HTTP server instance */\n      getServer: this.getServer,\n      /** Get the server configuration */\n      getConfig: this.getConfig,\n    };\n  }\n}\n\nconst EXCLUDED_PLUGINS: string[] = [ServerPlugin.manifest.name];\n\n/**\n * @internal\n */\nexport const server = toPlugin(ServerPlugin);\n// Export manifest and types\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["manifest"],"sources":["../../../src/plugins/server/index.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport type { Server as HTTPServer } from \"node:http\";\nimport path from \"node:path\";\nimport dotenv from \"dotenv\";\nimport express from \"express\";\nimport type { PluginClientConfigs, PluginPhase } from \"shared\";\nimport { ServerError } from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest } from \"../../registry\";\nimport { instrumentations } from \"../../telemetry\";\nimport { sanitizeClientConfig } from \"./client-config-sanitizer\";\nimport manifest from \"./manifest.json\";\nimport { RemoteTunnelController } from \"./remote-tunnel/remote-tunnel-controller\";\nimport { StaticServer } from \"./static-server\";\nimport type { ServerConfig } from \"./types\";\nimport { getRoutes, type PluginEndpoints, printRoutes } from \"./utils\";\nimport { ViteDevServer } from \"./vite-dev-server\";\n\ndotenv.config({ path: path.resolve(process.cwd(), \"./.env\") });\n\nconst logger = createLogger(\"server\");\n\n/**\n * Server plugin for the AppKit.\n *\n * This plugin is responsible for starting the server and serving the static files.\n * It also handles the remote tunneling for development purposes.\n *\n * The server is started automatically by `createApp` after all plugins are set up\n * and the optional `onPluginsReady` callback has run.\n *\n * @example\n * ```ts\n * createApp({\n *   plugins: [server(), analytics({})],\n *   onPluginsReady(appkit) {\n *     appkit.server.extend((app) => {\n *       app.get(\"/custom\", (_req, res) => res.json({ ok: true }));\n *     });\n *   },\n * });\n * ```\n */\nexport class ServerPlugin extends Plugin {\n  public static DEFAULT_CONFIG = {\n    host: process.env.FLASK_RUN_HOST || \"0.0.0.0\",\n    port: Number(process.env.DATABRICKS_APP_PORT) || 8000,\n  };\n\n  /** Plugin manifest declaring metadata and resource requirements */\n  static manifest = manifest as PluginManifest<\"server\">;\n  private serverApplication: express.Application;\n  private server: HTTPServer | null;\n  private viteDevServer?: ViteDevServer;\n  private remoteTunnelController?: RemoteTunnelController;\n  protected declare config: ServerConfig;\n  private serverExtensions: ((app: express.Application) => void)[] = [];\n  private rawBodyPaths: Set<string> = new Set();\n  static phase: PluginPhase = \"deferred\";\n\n  constructor(config: ServerConfig) {\n    if (\"autoStart\" in config) {\n      throw new ServerError(\n        \"server({ autoStart }) has been removed. \" +\n          \"The server is now started automatically by createApp.\\n\\n\" +\n          \"Run `npx appkit codemod on-plugins-ready --write` to auto-migrate.\",\n      );\n    }\n    super(config);\n    this.config = config;\n    this.serverApplication = express();\n    this.server = null;\n    this.serverExtensions = [];\n    this.telemetry.registerInstrumentations([\n      instrumentations.http,\n      instrumentations.express,\n    ]);\n  }\n\n  async setup() {}\n\n  /** Get the server configuration. */\n  getConfig() {\n    const { plugins: _plugins, ...config } = this.config;\n\n    return config;\n  }\n\n  /**\n   * Start the server.\n   *\n   * This method starts the server and sets up the frontend.\n   * It also sets up the remote tunneling if enabled.\n   *\n   * @returns The express application.\n   */\n  async start(): Promise<express.Application> {\n    this.serverApplication.use(\n      express.json({\n        type: (req) => {\n          // Skip JSON parsing for routes that declared skipBodyParsing\n          // (e.g. file uploads where the raw body must flow through).\n          // rawBodyPaths is populated by extendRoutes() below; the type\n          // callback runs per-request so the set is already filled.\n          const urlPath = req.url?.split(\"?\")[0];\n          if (urlPath && this.rawBodyPaths.has(urlPath)) return false;\n          const ct = req.headers[\"content-type\"] ?? \"\";\n          return ct.includes(\"json\");\n        },\n      }),\n    );\n\n    const { endpoints, pluginConfigs } = await this.extendRoutes();\n\n    for (const extension of this.serverExtensions) {\n      extension(this.serverApplication);\n    }\n\n    // register remote tunnel controller (before static/vite)\n    this.remoteTunnelController = new RemoteTunnelController(\n      this.devFileReader,\n    );\n    this.serverApplication.use(this.remoteTunnelController.middleware);\n\n    await this.setupFrontend(endpoints, pluginConfigs);\n\n    const server = this.serverApplication.listen(\n      this.config.port ?? ServerPlugin.DEFAULT_CONFIG.port,\n      this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host,\n      () => this.logStartupInfo(),\n    );\n\n    this.server = server;\n\n    // attach server to remote tunnel controller\n    this.remoteTunnelController.setServer(server);\n\n    process.on(\"SIGTERM\", () => this._gracefulShutdown());\n    process.on(\"SIGINT\", () => this._gracefulShutdown());\n\n    if (process.env.NODE_ENV === \"development\") {\n      const allRoutes = getRoutes(this.serverApplication._router.stack);\n      printRoutes(allRoutes);\n    }\n    return this.serverApplication;\n  }\n\n  /**\n   * Get the low level node.js http server instance.\n   *\n   * Only use this method if you need to access the server instance for advanced usage like a custom websocket server, etc.\n   *\n   * @throws {Error} If the server has not started yet.\n   * @returns {HTTPServer} The server instance.\n   */\n  getServer(): HTTPServer {\n    if (!this.server) {\n      throw ServerError.notStarted();\n    }\n\n    return this.server;\n  }\n\n  /**\n   * Extend the server with custom routes or middleware.\n   *\n   * Call this inside the `onPluginsReady` callback of `createApp` to register\n   * custom Express routes or middleware before the server starts listening.\n   *\n   * @param fn - A function that receives the express application.\n   * @returns The server plugin instance for chaining.\n   */\n  extend(fn: (app: express.Application) => void) {\n    this.serverExtensions.push(fn);\n    return this;\n  }\n\n  /**\n   * Setup the routes with the plugins.\n   *\n   * This method goes through all the plugins and injects the routes into the server application.\n   * Returns a map of plugin names to their registered named endpoints,\n   * and a map of plugin names to their client-exposed configs.\n   */\n  private async extendRoutes(): Promise<{\n    endpoints: PluginEndpoints;\n    pluginConfigs: PluginClientConfigs;\n  }> {\n    const endpoints: PluginEndpoints = {};\n    const pluginConfigs: PluginClientConfigs = {};\n\n    if (!this.config.plugins) return { endpoints, pluginConfigs };\n\n    this.serverApplication.get(\"/health\", (_, res) => {\n      res.status(200).json({ status: \"ok\" });\n    });\n    this.registerEndpoint(\"health\", \"/health\");\n\n    for (const plugin of Object.values(this.config.plugins)) {\n      if (EXCLUDED_PLUGINS.includes(plugin.name)) continue;\n\n      if (plugin?.injectRoutes && typeof plugin.injectRoutes === \"function\") {\n        const router = express.Router();\n\n        plugin.injectRoutes(router);\n\n        const basePath = `/api/${plugin.name}`;\n        this.serverApplication.use(basePath, router);\n\n        endpoints[plugin.name] = plugin.getEndpoints();\n\n        // Collect paths that should skip body parsing\n        if (\n          plugin.getSkipBodyParsingPaths &&\n          typeof plugin.getSkipBodyParsingPaths === \"function\"\n        ) {\n          for (const p of plugin.getSkipBodyParsingPaths()) {\n            this.rawBodyPaths.add(p);\n          }\n        }\n      }\n\n      if (typeof plugin.clientConfig === \"function\") {\n        try {\n          const raw = plugin.clientConfig();\n          if (raw != null) {\n            const sanitized = sanitizeClientConfig(plugin.name, raw);\n            if (Object.keys(sanitized).length > 0) {\n              pluginConfigs[plugin.name] = sanitized;\n            }\n          }\n        } catch (error) {\n          logger.error(\n            \"Plugin '%s' clientConfig() failed, skipping its config: %O\",\n            plugin.name,\n            error,\n          );\n        }\n      }\n    }\n\n    return { endpoints, pluginConfigs };\n  }\n\n  /**\n   * Setup frontend serving based on environment:\n   * - If staticPath is explicitly provided: use static server\n   * - Dev mode (no staticPath): Vite for HMR\n   * - Production (no staticPath): Static files auto-detected\n   */\n  private async setupFrontend(\n    endpoints: PluginEndpoints,\n    pluginConfigs: PluginClientConfigs,\n  ) {\n    const isDev = process.env.NODE_ENV === \"development\";\n    const hasExplicitStaticPath = this.config.staticPath !== undefined;\n\n    // explict static path provided\n    if (hasExplicitStaticPath) {\n      const staticServer = new StaticServer(\n        this.serverApplication,\n        this.config.staticPath as string,\n        endpoints,\n        pluginConfigs,\n      );\n      staticServer.setup();\n      return;\n    }\n\n    // auto-detection based on environment\n    if (isDev) {\n      this.viteDevServer = new ViteDevServer(\n        this.serverApplication,\n        endpoints,\n        pluginConfigs,\n      );\n      await this.viteDevServer.setup();\n      return;\n    }\n\n    // auto-detection based on static path\n    const staticPath = ServerPlugin.findStaticPath();\n    if (staticPath) {\n      const staticServer = new StaticServer(\n        this.serverApplication,\n        staticPath,\n        endpoints,\n        pluginConfigs,\n      );\n\n      staticServer.setup();\n    }\n  }\n\n  private static findStaticPath() {\n    const staticPaths = [\"dist\", \"client/dist\", \"build\", \"public\", \"out\"];\n    const cwd = process.cwd();\n    for (const p of staticPaths) {\n      const fullPath = path.resolve(cwd, p);\n      if (fs.existsSync(path.resolve(fullPath, \"index.html\"))) {\n        logger.debug(\"Static files: serving from %s\", fullPath);\n        return fullPath;\n      }\n    }\n    return undefined;\n  }\n\n  private logStartupInfo() {\n    const isDev = process.env.NODE_ENV === \"development\";\n    const hasExplicitStaticPath = this.config.staticPath !== undefined;\n    const port = this.config.port ?? ServerPlugin.DEFAULT_CONFIG.port;\n    const host = this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host;\n\n    logger.info(\"Server running on http://%s:%d\", host, port);\n\n    if (hasExplicitStaticPath) {\n      logger.info(\"Mode: static (%s)\", this.config.staticPath);\n    } else if (isDev) {\n      logger.info(\"Mode: development (Vite HMR)\");\n    } else {\n      logger.info(\"Mode: production (static)\");\n    }\n\n    const remoteServerController = this.remoteTunnelController;\n    if (!remoteServerController) {\n      logger.debug(\"Remote tunnel: disabled (controller not initialized)\");\n    } else {\n      logger.debug(\n        \"Remote tunnel: %s; %s\",\n        remoteServerController.isAllowedByEnv() ? \"allowed\" : \"blocked\",\n        remoteServerController.isActive() ? \"active\" : \"inactive\",\n      );\n    }\n  }\n\n  private async _gracefulShutdown() {\n    logger.info(\"Starting graceful shutdown...\");\n\n    if (this.viteDevServer) {\n      await this.viteDevServer.close();\n    }\n\n    if (this.remoteTunnelController) {\n      this.remoteTunnelController.cleanup();\n    }\n\n    // 1. abort active operations from plugins\n    if (this.config.plugins) {\n      for (const plugin of Object.values(this.config.plugins)) {\n        if (plugin.abortActiveOperations) {\n          try {\n            plugin.abortActiveOperations();\n          } catch (err) {\n            logger.error(\n              \"Error aborting operations for plugin %s: %O\",\n              plugin.name,\n              err,\n            );\n          }\n        }\n      }\n    }\n\n    // 2. close the server\n    if (this.server) {\n      this.server.close(() => {\n        logger.debug(\"Server closed gracefully\");\n        process.exit(0);\n      });\n\n      // 3. timeout to force shutdown after 15 seconds\n      setTimeout(() => {\n        logger.debug(\"Force shutdown after timeout\");\n        process.exit(1);\n      }, 15000);\n    } else {\n      process.exit(0);\n    }\n  }\n\n  /**\n   * Returns the public exports for the server plugin.\n   * Exposes server management methods.\n   */\n  exports() {\n    const self = this;\n    return {\n      /** Extend the server with custom routes or middleware */\n      extend(fn: (app: express.Application) => void) {\n        self.extend(fn);\n        return this;\n      },\n      /** Get the underlying HTTP server instance */\n      getServer: this.getServer,\n      /** Get the server configuration */\n      getConfig: this.getConfig,\n      /** @deprecated Server is now started automatically by createApp. */\n      start() {\n        throw new ServerError(\n          \"server.start() has been removed. Use the onPluginsReady callback instead:\\n\\n\" +\n            \"  createApp({\\n\" +\n            \"    plugins: [server(), ...],\\n\" +\n            \"    onPluginsReady(appkit) {\\n\" +\n            \"      appkit.server.extend(...);\\n\" +\n            \"    },\\n\" +\n            \"  });\\n\\n\" +\n            \"Run `npx appkit codemod on-plugins-ready --write` to auto-migrate.\",\n        );\n      },\n    };\n  }\n}\n\nconst EXCLUDED_PLUGINS: string[] = [ServerPlugin.manifest.name];\n\n/**\n * @internal\n */\nexport const server = toPlugin(ServerPlugin);\n// Export manifest and types\n"],"mappings":"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"}

package/dist/plugins/server/manifest.js

@@ -11,11 +11,6 @@ var manifest_default = {
 	config: { "schema": {
 		"type": "object",
 		"properties": {
-			"autoStart": {
-				"type": "boolean",
-				"default": true,
-				"description": "Automatically start the server on plugin setup"
-			},
 			"host": {
 				"type": "string",
 				"default": "0.0.0.0",

package/dist/plugins/server/types.d.ts

@@ -8,7 +8,6 @@ interface ServerConfig extends BasePluginConfig {
   port?: number;
   plugins?: Record<string, Plugin>;
   staticPath?: string;
-  autoStart?: boolean;
   host?: string;
 }
 //#endregion

package/dist/plugins/server/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/plugins/server/types.ts"],"mappings":";;;;;;UAGiB,YAAA,SAAqB,gBAAA;EACpC,IAAA;EACA,OAAA,GAAU,MAAA,SAAe,MAAA;EACzB,UAAA;EACA,SAAA;EACA,IAAA;AAAA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/plugins/server/types.ts"],"mappings":";;;;;;UAGiB,YAAA,SAAqB,gBAAA;EACpC,IAAA;EACA,OAAA,GAAU,MAAA,SAAe,MAAA;EACzB,UAAA;EACA,IAAA;AAAA"}

package/dist/registry/manifest-loader.d.ts

@@ -35,11 +35,11 @@ declare function getPluginManifest(plugin: PluginConstructor): PluginManifest;
 declare function getResourceRequirements(plugin: PluginConstructor): {
   required: boolean;
   description: string;
-  type: ResourceType;
-  permission: ResourcePermission;
   fields: Record<string, ResourceFieldEntry>;
+  type: ResourceType;
   alias: string;
   resourceKey: string;
+  permission: ResourcePermission;
 }[];
 //#endregion
 export { getPluginManifest, getResourceRequirements };

package/dist/registry/manifest-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-loader.d.ts","names":[],"sources":["../../src/registry/manifest-loader.ts"],"mappings":";;;;;;;;;;;AA4DA;;;;iBAAgB,iBAAA,CAAkB,MAAA,EAAQ,iBAAA,GAAoB,cAAA;;;;;AA4F9D;;;;;;;;;;;;;;iBAAgB,uBAAA,CAAwB,MAAA,EAAQ,iBAAA"}
+{"version":3,"file":"manifest-loader.d.ts","names":[],"sources":["../../src/registry/manifest-loader.ts"],"mappings":";;;;;;;;;;;AA4DA;;;;iBAAgB,iBAAA,CAAkB,MAAA,EAAQ,iBAAA,GAAoB,cAAA;;;;;AA4F9D;;;;;;;;;;;;;;iBAAgB,uBAAA,CAAwB,MAAA,EAAQ,iBAAA;;;yBAAiB,kBAAA"}

package/docs/api/appkit/Class.ServerError.md

@@ -5,7 +5,6 @@ Error thrown when server lifecycle operations fail. Use for server start/stop is
 ## Example[​](#example "Direct link to Example")
 
 ```typescript
-throw new ServerError("Cannot get server when autoStart is true");
 throw new ServerError("Server not started");
 
 ```
@@ -158,27 +157,6 @@ Create a human-readable string representation
 
 ***
 
-### autoStartConflict()[​](#autostartconflict "Direct link to autoStartConflict()")
-
-```ts
-static autoStartConflict(operation: string): ServerError;
-
-```
-
-Create a server error for autoStart conflict
-
-#### Parameters[​](#parameters-1 "Direct link to Parameters")
-
-| Parameter   | Type     |
-| ----------- | -------- |
-| `operation` | `string` |
-
-#### Returns[​](#returns-3 "Direct link to Returns")
-
-`ServerError`
-
-***
-
 ### clientDirectoryNotFound()[​](#clientdirectorynotfound "Direct link to clientDirectoryNotFound()")
 
 ```ts
@@ -188,13 +166,13 @@ static clientDirectoryNotFound(searchedPaths: string[]): ServerError;
 
 Create a server error for missing client directory
 
-#### Parameters[​](#parameters-2 "Direct link to Parameters")
+#### Parameters[​](#parameters-1 "Direct link to Parameters")
 
 | Parameter       | Type        |
 | --------------- | ----------- |
 | `searchedPaths` | `string`\[] |
 
-#### Returns[​](#returns-4 "Direct link to Returns")
+#### Returns[​](#returns-3 "Direct link to Returns")
 
 `ServerError`
 
@@ -209,7 +187,7 @@ static notStarted(): ServerError;
 
 Create a server error for server not started
 
-#### Returns[​](#returns-5 "Direct link to Returns")
+#### Returns[​](#returns-4 "Direct link to Returns")
 
 `ServerError`
 
@@ -224,6 +202,6 @@ static viteNotInitialized(): ServerError;
 
 Create a server error for Vite dev server not initialized
 
-#### Returns[​](#returns-6 "Direct link to Returns")
+#### Returns[​](#returns-5 "Direct link to Returns")
 
 `ServerError`

package/docs/api/appkit/Function.createApp.md

@@ -4,6 +4,7 @@
 function createApp<T>(config: {
   cache?: CacheConfig;
   client?: WorkspaceClient;
+  onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;
   plugins?: T;
   telemetry?: TelemetryConfig;
 }): Promise<PluginMap<T>>;
@@ -12,7 +13,7 @@ function createApp<T>(config: {
 
 Bootstraps AppKit with the provided configuration.
 
-Initializes telemetry, cache, and service context, then registers plugins in phase order (core, normal, deferred) and awaits their setup. The returned object maps each plugin name to its `exports()` API, with an `asUser(req)` method for user-scoped execution.
+Initializes telemetry, cache, and service context, then registers plugins in phase order (core, normal, deferred) and awaits their setup. If a `onPluginsReady` callback is provided it runs after plugin setup but before the server starts, giving you access to the full appkit handle for registering custom routes or performing async setup. The returned object maps each plugin name to its `exports()` API, with an `asUser(req)` method for user-scoped execution.
 
 ## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
 
@@ -22,13 +23,14 @@ Initializes telemetry, cache, and service context, then registers plugins in pha
 
 ## Parameters[​](#parameters "Direct link to Parameters")
 
-| Parameter           | Type                                                                                                                                                                                                                     |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `config`            | { `cache?`: [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md); `client?`: `WorkspaceClient`; `plugins?`: `T`; `telemetry?`: [`TelemetryConfig`](./docs/api/appkit/Interface.TelemetryConfig.md); } |
-| `config.cache?`     | [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md)                                                                                                                                                        |
-| `config.client?`    | `WorkspaceClient`                                                                                                                                                                                                        |
-| `config.plugins?`   | `T`                                                                                                                                                                                                                      |
-| `config.telemetry?` | [`TelemetryConfig`](./docs/api/appkit/Interface.TelemetryConfig.md)                                                                                                                                                |
+| Parameter                | Type                                                                                                                                                                                                                                                                                                     |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `config`                 | { `cache?`: [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md); `client?`: `WorkspaceClient`; `onPluginsReady?`: (`appkit`: `PluginMap`<`T`>) => `void` \| `Promise`<`void`>; `plugins?`: `T`; `telemetry?`: [`TelemetryConfig`](./docs/api/appkit/Interface.TelemetryConfig.md); } |
+| `config.cache?`          | [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md)                                                                                                                                                                                                                                        |
+| `config.client?`         | `WorkspaceClient`                                                                                                                                                                                                                                                                                        |
+| `config.onPluginsReady?` | (`appkit`: `PluginMap`<`T`>) => `void` \| `Promise`<`void`>                                                                                                                                                                                                                                              |
+| `config.plugins?`        | `T`                                                                                                                                                                                                                                                                                                      |
+| `config.telemetry?`      | [`TelemetryConfig`](./docs/api/appkit/Interface.TelemetryConfig.md)                                                                                                                                                                                                                                |
 
 ## Returns[​](#returns "Direct link to Returns")
 
@@ -50,13 +52,13 @@ await createApp({
 ```ts
 import { createApp, server, analytics } from "@databricks/appkit";
 
-const appkit = await createApp({
-  plugins: [server({ autoStart: false }), analytics({})],
-});
-
-appkit.server.extend((app) => {
-  app.get("/custom", (_req, res) => res.json({ ok: true }));
+await createApp({
+  plugins: [server(), analytics({})],
+  onPluginsReady(appkit) {
+    appkit.server.extend((app) => {
+      app.get("/custom", (_req, res) => res.json({ ok: true }));
+    });
+  },
 });
-await appkit.server.start();
 
 ```

package/docs/plugins/server.md

@@ -40,22 +40,39 @@ await createApp({
 
 ```
 
-## Manual server start example[​](#manual-server-start-example "Direct link to Manual server start example")
+## Custom routes example[​](#custom-routes-example "Direct link to Custom routes example")
 
-When you need to extend Express with custom routes:
+Use the `onPluginsReady` callback to extend Express with custom routes before the server starts:
 
 ```ts
 import { createApp, server } from "@databricks/appkit";
 
-const appkit = await createApp({
-  plugins: [server({ autoStart: false })],
+await createApp({
+  plugins: [server()],
+  onPluginsReady(appkit) {
+    appkit.server.extend((app) => {
+      app.get("/custom", (_req, res) => res.json({ ok: true }));
+    });
+  },
 });
 
-appkit.server.extend((app) => {
-  app.get("/custom", (_req, res) => res.json({ ok: true }));
-});
+```
+
+The `onPluginsReady` callback also supports async operations:
 
-await appkit.server.start();
+```ts
+await createApp({
+  plugins: [server()],
+  async onPluginsReady(appkit) {
+    const pool = await initializeDatabase();
+    appkit.server.extend((app) => {
+      app.get("/data", async (_req, res) => {
+        const result = await pool.query("SELECT 1");
+        res.json(result);
+      });
+    });
+  },
+});
 
 ```
 
@@ -69,7 +86,6 @@ await createApp({
     server({
       port: 8000,          // default: Number(process.env.DATABRICKS_APP_PORT) || 8000
       host: "0.0.0.0",     // default: process.env.FLASK_RUN_HOST || "0.0.0.0"
-      autoStart: true,     // default: true
       staticPath: "dist",  // optional: force a specific static directory
     }),
   ],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit",
   "type": "module",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "packageManager": "pnpm@10.21.0",