@lark-apaas/devtool-kits 1.2.22-beta.0 → 1.2.23-alpha.0

package/dist/index.d.cts

@@ -245,11 +245,18 @@ declare function getQuery(req: AnyRequest): Record<string, string>;
 declare function getQueryParam(req: AnyRequest, key: string): string | undefined;
 
 /**
- * Register middlewares for Express-compatible servers or Vite
- * @param server - Express app or Vite middleware instance
- * @param middlewares - List of middlewares to register
- * @param options - Optional context configuration
- * @returns Promise that resolves when all middlewares are registered
+ * Register middlewares for Express-compatible servers or Vite.
+ *
+ * MUST stay synchronous (no async/await).
+ *
+ * Why: when called from webpack/rspack-dev-server's `setupMiddlewares` callback,
+ * any `await` here yields a microtask, allowing dev-server to finish registering
+ * its own built-ins (proxy, historyApiFallback, serveStatic, ...) BEFORE our
+ * later iterations run. The first router lands before historyApiFallback while
+ * subsequent routers land after — causing extensionless GETs (e.g. `/dev/openapi/spec`
+ * with a wildcard Accept header) to be rewritten to `/index.html`. All registered work
+ * (`server.use`, `createRouter`, `createHandler`) is sync, so async/await is also
+ * unnecessary.
  *
  * @example
  * ```typescript
@@ -257,31 +264,15 @@ declare function getQueryParam(req: AnyRequest, key: string): string | undefined
  * setupMiddlewares: (middlewares, devServer) => {
  *   if (devServer.app) {
  *     registerMiddlewares(devServer.app, [
- *       // Global middlewares (execute first)
- *       createCorsMiddleware({ origin: '*' }),
- *       createAuthMiddleware(),
- *
- *       // Route middlewares
  *       createDevLogsMiddleware({ logDir: './logs' }),
  *       createOpenapiMiddleware({ openapiFilePath: './openapi.json' })
- *     ], {
- *       basePath: '/api',
- *       isDev: true,
- *       rootDir: __dirname
- *     });
+ *     ], { basePath: '/api', isDev: true, rootDir: __dirname });
  *   }
  *   return middlewares;
  * }
- *
- * // In Vite configureServer
- * configureServer: (server) => {
- *   registerMiddlewares(server.middlewares, [
- *     createDevLogsMiddleware({ logDir: './logs' })
- *   ], { basePath: '/', isDev: true, rootDir: __dirname });
- * }
  * ```
  */
-declare function registerMiddlewares(server: ExpressApp | ViteMiddleware, middlewares: Middleware[], options?: Partial<MiddlewareContext>): Promise<void>;
+declare function registerMiddlewares(server: ExpressApp | ViteMiddleware, middlewares: Middleware[], options?: Partial<MiddlewareContext>): void;
 
 interface PageRouteInfo {
     path?: string;

package/dist/index.d.ts

@@ -245,11 +245,18 @@ declare function getQuery(req: AnyRequest): Record<string, string>;
 declare function getQueryParam(req: AnyRequest, key: string): string | undefined;
 
 /**
- * Register middlewares for Express-compatible servers or Vite
- * @param server - Express app or Vite middleware instance
- * @param middlewares - List of middlewares to register
- * @param options - Optional context configuration
- * @returns Promise that resolves when all middlewares are registered
+ * Register middlewares for Express-compatible servers or Vite.
+ *
+ * MUST stay synchronous (no async/await).
+ *
+ * Why: when called from webpack/rspack-dev-server's `setupMiddlewares` callback,
+ * any `await` here yields a microtask, allowing dev-server to finish registering
+ * its own built-ins (proxy, historyApiFallback, serveStatic, ...) BEFORE our
+ * later iterations run. The first router lands before historyApiFallback while
+ * subsequent routers land after — causing extensionless GETs (e.g. `/dev/openapi/spec`
+ * with a wildcard Accept header) to be rewritten to `/index.html`. All registered work
+ * (`server.use`, `createRouter`, `createHandler`) is sync, so async/await is also
+ * unnecessary.
  *
  * @example
  * ```typescript
@@ -257,31 +264,15 @@ declare function getQueryParam(req: AnyRequest, key: string): string | undefined
  * setupMiddlewares: (middlewares, devServer) => {
  *   if (devServer.app) {
  *     registerMiddlewares(devServer.app, [
- *       // Global middlewares (execute first)
- *       createCorsMiddleware({ origin: '*' }),
- *       createAuthMiddleware(),
- *
- *       // Route middlewares
  *       createDevLogsMiddleware({ logDir: './logs' }),
  *       createOpenapiMiddleware({ openapiFilePath: './openapi.json' })
- *     ], {
- *       basePath: '/api',
- *       isDev: true,
- *       rootDir: __dirname
- *     });
+ *     ], { basePath: '/api', isDev: true, rootDir: __dirname });
  *   }
  *   return middlewares;
  * }
- *
- * // In Vite configureServer
- * configureServer: (server) => {
- *   registerMiddlewares(server.middlewares, [
- *     createDevLogsMiddleware({ logDir: './logs' })
- *   ], { basePath: '/', isDev: true, rootDir: __dirname });
- * }
  * ```
  */
-declare function registerMiddlewares(server: ExpressApp | ViteMiddleware, middlewares: Middleware[], options?: Partial<MiddlewareContext>): Promise<void>;
+declare function registerMiddlewares(server: ExpressApp | ViteMiddleware, middlewares: Middleware[], options?: Partial<MiddlewareContext>): void;
 
 interface PageRouteInfo {
     path?: string;

package/dist/index.js

@@ -3625,7 +3625,7 @@ function logMiddlewareRegistration(middleware, fullMountPath) {
   }
 }
 __name(logMiddlewareRegistration, "logMiddlewareRegistration");
-async function registerRouteMiddleware(server, middleware, context) {
+function registerRouteMiddleware(server, middleware, context) {
   if (!middleware.mountPath) {
     console.error(`[Middleware] ${middleware.name}: Route middleware must have mountPath. Skipping.`);
     return;
@@ -3636,7 +3636,7 @@ async function registerRouteMiddleware(server, middleware, context) {
   logMiddlewareRegistration(middleware, fullMountPath);
 }
 __name(registerRouteMiddleware, "registerRouteMiddleware");
-async function registerGlobalMiddleware(server, middleware, context) {
+function registerGlobalMiddleware(server, middleware, context) {
   if (middleware.mountPath) {
     console.warn(`[Middleware] ${middleware.name}: Global middleware should not have mountPath. Ignoring mountPath "${middleware.mountPath}".`);
   }
@@ -3645,7 +3645,7 @@ async function registerGlobalMiddleware(server, middleware, context) {
   console.log(`[Middleware] Registered global: ${middleware.name}`);
 }
 __name(registerGlobalMiddleware, "registerGlobalMiddleware");
-async function registerMiddlewares(server, middlewares, options) {
+function registerMiddlewares(server, middlewares, options) {
   const context = {
     basePath: "/",
     isDev: process.env.NODE_ENV !== "production",
@@ -3673,9 +3673,9 @@ async function registerMiddlewares(server, middlewares, options) {
         console.warn(`[Middleware] ${middleware.name}: Both createRouter and createHandler provided. Using createRouter and ignoring createHandler.`);
       }
       if (isRouteMiddleware(middleware)) {
-        await registerRouteMiddleware(server, middleware, context);
+        registerRouteMiddleware(server, middleware, context);
       } else if (isGlobalMiddleware(middleware)) {
-        await registerGlobalMiddleware(server, middleware, context);
+        registerGlobalMiddleware(server, middleware, context);
       } else {
         console.error(`[Middleware] ${middleware.name || "unknown"}: Must provide either createRouter or createHandler.`);
       }