@esmx/core 3.0.0-rc.10

package/dist/gez.mjs

@@ -0,0 +1,842 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { cwd } from "node:process";
+import write from "write";
+import serialize from "serialize-javascript";
+import { createApp } from "./app.mjs";
+import { getManifestList } from "./manifest-json.mjs";
+import {
+  parseModuleConfig
+} from "./module-config.mjs";
+import {
+  parsePackConfig
+} from "./pack-config.mjs";
+import { createCache } from "./utils/cache.mjs";
+import { getImportMap } from "./utils/import-map.mjs";
+import { resolvePath } from "./utils/resolve-path.mjs";
+import { getImportPreloadInfo as getStaticImportPaths } from "./utils/static-import-lexer.mjs";
+export var COMMAND = /* @__PURE__ */ ((COMMAND2) => {
+  COMMAND2["dev"] = "dev";
+  COMMAND2["build"] = "build";
+  COMMAND2["preview"] = "preview";
+  COMMAND2["start"] = "start";
+  return COMMAND2;
+})(COMMAND || {});
+export class Esmx {
+  // 基础属性和构造函数
+  _options;
+  _readied = null;
+  _importmapHash = null;
+  get readied() {
+    if (this._readied) {
+      return this._readied;
+    }
+    throw new NotReadyError();
+  }
+  /**
+   * 获取模块名称
+   * @returns {string} 当前模块的名称，来源于模块配置
+   * @throws {NotReadyError} 在框架实例未初始化时抛出错误
+   */
+  get name() {
+    return this.moduleConfig.name;
+  }
+  /**
+   * 获取模块变量名
+   * @returns {string} 基于模块名称生成的合法 JavaScript 变量名
+   * @throws {NotReadyError} 在框架实例未初始化时抛出错误
+   */
+  get varName() {
+    return "__" + this.name.replace(/[^a-zA-Z]/g, "_") + "__";
+  }
+  /**
+   * 获取项目根目录的绝对路径
+   * @returns {string} 项目根目录的绝对路径
+   * 如果配置的 root 为相对路径，则基于当前工作目录解析为绝对路径
+   */
+  get root() {
+    const { root = cwd() } = this._options;
+    if (path.isAbsolute(root)) {
+      return root;
+    }
+    return path.resolve(cwd(), root);
+  }
+  /**
+   * 判断当前是否为生产环境
+   * @returns {boolean} 环境标识
+   * 优先使用配置项中的 isProd，若未配置则根据 process.env.NODE_ENV 判断
+   */
+  get isProd() {
+    return this._options?.isProd ?? process.env.NODE_ENV === "production";
+  }
+  /**
+   * 获取模块的基础路径
+   * @returns {string} 以斜杠开头和结尾的模块基础路径
+   * 用于构建模块资源的访问路径
+   */
+  get basePath() {
+    return `/${this.name}/`;
+  }
+  /**
+   * 获取基础路径占位符
+   * @returns {string} 基础路径占位符或空字符串
+   * 用于运行时动态替换模块的基础路径，可通过配置禁用
+   */
+  get basePathPlaceholder() {
+    const varName = this._options.basePathPlaceholder;
+    if (varName === false) {
+      return "";
+    }
+    return varName ?? "[[[___GEZ_DYNAMIC_BASE___]]]";
+  }
+  /**
+   * 获取当前执行的命令
+   * @returns {COMMAND} 当前正在执行的命令枚举值
+   * @throws {NotReadyError} 在框架实例未初始化时调用此方法会抛出错误
+   */
+  get command() {
+    return this.readied.command;
+  }
+  /**
+   * 获取命令枚举类型
+   * @returns {typeof COMMAND} 命令枚举类型定义
+   */
+  get COMMAND() {
+    return COMMAND;
+  }
+  /**
+   * 获取模块配置信息
+   * @returns {ParsedModuleConfig} 当前模块的完整配置信息
+   */
+  get moduleConfig() {
+    return this.readied.moduleConfig;
+  }
+  /**
+   * 获取打包配置信息
+   * @returns {ParsedPackConfig} 当前模块的打包相关配置
+   */
+  get packConfig() {
+    return this.readied.packConfig;
+  }
+  /**
+   * 获取应用程序的静态资源处理中间件。
+   *
+   * 该中间件负责处理应用程序的静态资源请求，根据运行环境提供不同的实现：
+   * - 开发环境：支持源码的实时编译、热更新，使用 no-cache 缓存策略
+   * - 生产环境：处理构建后的静态资源，支持不可变文件的长期缓存
+   *
+   * @returns {Middleware} 返回静态资源处理中间件函数
+   * @throws {NotReadyError} 在框架实例未初始化时调用此方法会抛出错误
+   *
+   * @example
+   * ```ts
+   * const server = http.createServer((req, res) => {
+   *     // 使用中间件处理静态资源请求
+   *     esmx.middleware(req, res, async () => {
+   *         const rc = await esmx.render({ url: req.url });
+   *         res.end(rc.html);
+   *     });
+   * });
+   * ```
+   */
+  get middleware() {
+    return this.readied.app.middleware;
+  }
+  /**
+   * 获取应用程序的服务端渲染函数。
+   *
+   * 该函数负责执行服务端渲染，根据运行环境提供不同的实现：
+   * - 开发环境：加载源码中的服务端入口文件，支持热更新和实时预览
+   * - 生产环境：加载构建后的服务端入口文件，提供优化的渲染性能
+   *
+   * @returns {(options?: RenderContextOptions) => Promise<RenderContext>} 返回服务端渲染函数
+   * @throws {NotReadyError} 在框架实例未初始化时调用此方法会抛出错误
+   *
+   * @example
+   * ```ts
+   * // 基本用法
+   * const rc = await esmx.render({
+   *     params: { url: req.url }
+   * });
+   * res.end(rc.html);
+   *
+   * // 高级配置
+   * const rc = await esmx.render({
+   *     base: '',           // 设置基础路径
+   *     importmapMode: 'inline',    // 设置导入映射模式
+   *     entryName: 'default',    // 指定渲染入口
+   *     params: {
+   *         url: req.url,
+   *         state: { user: 'admin' }
+   *     }
+   * });
+   * ```
+   */
+  get render() {
+    return this.readied.app.render;
+  }
+  constructor(options = {}) {
+    this._options = options;
+  }
+  /**
+   * 初始化 Esmx 框架实例。
+   *
+   * 该方法执行以下核心初始化流程：
+   * 1. 解析项目配置（package.json、模块配置、打包配置等）
+   * 2. 创建应用实例（开发环境或生产环境）
+   * 3. 根据命令执行相应的生命周期方法
+   *
+   * @param command - 框架运行命令
+   *   - dev: 启动开发服务器，支持热更新
+   *   - build: 构建生产环境产物
+   *   - preview: 预览构建产物
+   *   - start: 启动生产环境服务器
+   *
+   * @returns 初始化成功返回 true
+   * @throws {Error} 重复初始化时抛出错误
+   *
+   * @example
+   * ```ts
+   * // entry.node.ts
+   * import type { EsmxOptions } from '@esmx/core';
+   *
+   * export default {
+   *   // 开发环境配置
+   *   async devApp(esmx) {
+   *     return import('@esmx/rspack').then((m) =>
+   *       m.createRspackHtmlApp(esmx, {
+   *         config(context) {
+   *           // 自定义 Rspack 配置
+   *         }
+   *       })
+   *     );
+   *   },
+   *
+   *   // HTTP 服务器配置
+   *   async server(esmx) {
+   *     const server = http.createServer((req, res) => {
+   *       // 静态文件处理
+   *       esmx.middleware(req, res, async () => {
+   *         // 传入渲染的参数
+   *         const render = await esmx.render({
+   *           params: { url: req.url }
+   *         });
+   *         // 响应 HTML 内容
+   *         res.end(render.html);
+   *       });
+   *     });
+   *
+   *     // 监听端口
+   *     server.listen(3000, () => {
+   *       console.log('http://localhost:3000');
+   *     });
+   *   }
+   * } satisfies EsmxOptions;
+   * ```
+   */
+  async init(command) {
+    if (this._readied) {
+      throw new Error("Cannot be initialized repeatedly");
+    }
+    const { name } = await this.readJson(
+      path.resolve(this.root, "package.json")
+    );
+    const moduleConfig = parseModuleConfig(
+      name,
+      this.root,
+      this._options.modules
+    );
+    const packConfig = parsePackConfig(this._options.packs);
+    this._readied = {
+      command,
+      app: {
+        middleware() {
+          throw new NotReadyError();
+        },
+        async render() {
+          throw new NotReadyError();
+        }
+      },
+      moduleConfig,
+      packConfig,
+      cache: createCache(this.isProd)
+    };
+    const devApp = this._options.devApp || defaultDevApp;
+    const app = ["dev" /* dev */, "build" /* build */].includes(command) ? await devApp(this) : await createApp(this, command);
+    this.readied.app = app;
+    switch (command) {
+      case "dev" /* dev */:
+      case "start" /* start */:
+        await this.server();
+        break;
+      case "build" /* build */:
+        return this.build();
+      case "preview" /* preview */:
+        break;
+    }
+    return true;
+  }
+  /**
+   * 销毁 Esmx 框架实例，执行资源清理和连接关闭等操作。
+   *
+   * 该方法主要用于开发环境下的资源清理，包括：
+   * - 关闭开发服务器（如 Rspack Dev Server）
+   * - 清理临时文件和缓存
+   * - 释放系统资源
+   *
+   * 注意：一般情况下，框架会自动处理资源的释放，用户无需手动调用此方法。
+   * 仅在需要自定义资源清理逻辑时才需要使用。
+   *
+   * @returns 返回一个 Promise，resolve 为 boolean 值
+   *   - true: 清理成功或无需清理
+   *   - false: 清理失败
+   *
+   * @example
+   * ```ts
+   * // 在需要自定义清理逻辑时使用
+   * process.once('SIGTERM', async () => {
+   *   await esmx.destroy(); // 清理资源
+   *   process.exit(0);
+   * });
+   * ```
+   */
+  async destroy() {
+    const { readied } = this;
+    if (readied.app?.destroy) {
+      return readied.app.destroy();
+    }
+    return true;
+  }
+  /**
+   * 执行应用程序的构建流程。
+   *
+   * 该方法负责执行整个应用的构建过程，包括：
+   * - 编译源代码
+   * - 生成生产环境的构建产物
+   * - 优化和压缩代码
+   * - 生成资源清单
+   *
+   * 构建过程会打印开始和结束时间，以及总耗时等信息。
+   *
+   * @returns 返回一个 Promise，resolve 为 boolean 值
+   *   - true: 构建成功或构建方法未实现
+   *   - false: 构建失败
+   *
+   * @throws {NotReadyError} 在框架实例未初始化时调用此方法会抛出错误
+   *
+   * @example
+   * ```ts
+   * // entry.node.ts
+   * import type { EsmxOptions } from '@esmx/core';
+   *
+   * export default {
+   *   // 开发环境配置
+   *   async devApp(esmx) {
+   *     return import('@esmx/rspack').then((m) =>
+   *       m.createRspackHtmlApp(esmx, {
+   *         config(context) {
+   *           // 自定义 Rspack 配置
+   *         }
+   *       })
+   *     );
+   *   },
+   *
+   *   // 构建后处理
+   *   async postBuild(esmx) {
+   *     // 构建完成后生成静态 HTML
+   *     const render = await esmx.render({
+   *       params: { url: '/' }
+   *     });
+   *     esmx.writeSync(
+   *       esmx.resolvePath('dist/client', 'index.html'),
+   *       render.html
+   *     );
+   *   }
+   * } satisfies EsmxOptions;
+   * ```
+   */
+  async build() {
+    const startTime = Date.now();
+    console.log("[esmx]: build start");
+    const successful = await this.readied.app.build?.();
+    const endTime = Date.now();
+    console.log(`[esmx]: build end, cost: ${endTime - startTime}ms`);
+    return successful ?? true;
+  }
+  /**
+   * 启动 HTTP 服务器并配置服务器实例。
+   *
+   * 该方法在框架的以下生命周期中被调用：
+   * - 开发环境（dev）：启动开发服务器，提供热更新等功能
+   * - 生产环境（start）：启动生产服务器，提供生产级性能
+   *
+   * 服务器的具体实现由用户通过 EsmxOptions 的 server 配置函数提供。
+   * 该函数负责：
+   * - 创建 HTTP 服务器实例
+   * - 配置中间件和路由
+   * - 处理请求和响应
+   * - 启动服务器监听
+   *
+   * @returns 返回一个 Promise，在服务器启动完成后 resolve
+   * @throws {NotReadyError} 在框架实例未初始化时调用此方法会抛出错误
+   *
+   * @example
+   * ```ts
+   * // entry.node.ts
+   * import http from 'node:http';
+   * import type { EsmxOptions } from '@esmx/core';
+   *
+   * export default {
+   *   // 服务器配置
+   *   async server(esmx) {
+   *     const server = http.createServer((req, res) => {
+   *       // 处理静态资源
+   *       esmx.middleware(req, res, async () => {
+   *         // 服务端渲染
+   *         const render = await esmx.render({
+   *           params: { url: req.url }
+   *         });
+   *         res.end(render.html);
+   *       });
+   *     });
+   *
+   *     // 启动服务器
+   *     server.listen(3000, () => {
+   *       console.log('Server running at http://localhost:3000');
+   *     });
+   *   }
+   * } satisfies EsmxOptions;
+   * ```
+   */
+  async server() {
+    await this._options?.server?.(this);
+  }
+  /**
+   * 执行构建后的处理逻辑。
+   *
+   * 该方法在应用构建完成后被调用，用于执行额外的资源处理，如：
+   * - 生成静态 HTML 文件
+   * - 处理构建产物
+   * - 执行部署任务
+   * - 发送构建通知
+   *
+   * 方法会自动捕获并处理执行过程中的异常，确保不会影响主构建流程。
+   *
+   * @returns 返回一个 Promise，resolve 为 boolean 值
+   *   - true: 后处理成功或无需处理
+   *   - false: 后处理失败
+   *
+   * @example
+   * ```ts
+   * // entry.node.ts
+   * import type { EsmxOptions } from '@esmx/core';
+   *
+   * export default {
+   *   // 构建后处理
+   *   async postBuild(esmx) {
+   *     // 生成多个页面的静态 HTML
+   *     const pages = ['/', '/about', '/404'];
+   *
+   *     for (const url of pages) {
+   *       const render = await esmx.render({
+   *         params: { url }
+   *       });
+   *
+   *       // 写入静态 HTML 文件
+   *       esmx.writeSync(
+   *         esmx.resolvePath('dist/client', url.substring(1), 'index.html'),
+   *         render.html
+   *       );
+   *     }
+   *   }
+   * } satisfies EsmxOptions;
+   * ```
+   */
+  async postBuild() {
+    try {
+      await this._options.postBuild?.(this);
+      return true;
+    } catch (e) {
+      console.error(e);
+      return false;
+    }
+  }
+  /**
+   * 解析项目相对路径为绝对路径
+   *
+   * @param projectPath - 项目路径类型，如 'dist/client'、'dist/server' 等
+   * @param args - 需要拼接的路径片段
+   * @returns 解析后的绝对路径
+   *
+   * @example
+   * ```ts
+   * // 在 entry.node.ts 中使用
+   * async postBuild(esmx) {
+   *   const outputPath = esmx.resolvePath('dist/client', 'index.html');
+   *   // 输出: /project/root/dist/client/index.html
+   * }
+   * ```
+   */
+  resolvePath(projectPath, ...args) {
+    return resolvePath(this.root, projectPath, ...args);
+  }
+  /**
+   * 同步写入文件内容
+   *
+   * @param filepath - 文件的绝对路径
+   * @param data - 要写入的数据，可以是字符串、Buffer 或对象
+   * @returns 写入是否成功
+   *
+   * @example
+   * ```ts
+   * // 在 entry.node.ts 中使用
+   * async postBuild(esmx) {
+   *   const htmlPath = esmx.resolvePath('dist/client', 'index.html');
+   *   const success = esmx.writeSync(htmlPath, '<html>...</html>');
+   * }
+   * ```
+   */
+  writeSync(filepath, data) {
+    try {
+      write.sync(filepath, data);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * 异步写入文件内容
+   *
+   * @param filepath - 文件的绝对路径
+   * @param data - 要写入的数据，可以是字符串、Buffer 或对象
+   * @returns Promise<boolean> 写入是否成功
+   *
+   * @example
+   * ```ts
+   * // 在 entry.node.ts 中使用
+   * async postBuild(esmx) {
+   *   const htmlPath = esmx.resolvePath('dist/client', 'index.html');
+   *   const success = await esmx.write(htmlPath, '<html>...</html>');
+   * }
+   * ```
+   */
+  async write(filepath, data) {
+    try {
+      await write(filepath, data);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * 同步读取并解析 JSON 文件
+   *
+   * @param filename - JSON 文件的绝对路径
+   * @returns 解析后的 JSON 对象
+   * @throws 当文件不存在或 JSON 格式错误时抛出异常
+   *
+   * @example
+   * ```ts
+   * // 在 entry.node.ts 中使用
+   * async server(esmx) {
+   *   const manifest = esmx.readJsonSync(esmx.resolvePath('dist/client', 'manifest.json'));
+   *   // 使用 manifest 对象
+   * }
+   * ```
+   */
+  readJsonSync(filename) {
+    return JSON.parse(fs.readFileSync(filename, "utf-8"));
+  }
+  /**
+   * 异步读取并解析 JSON 文件
+   *
+   * @param filename - JSON 文件的绝对路径
+   * @returns Promise<any> 解析后的 JSON 对象
+   * @throws 当文件不存在或 JSON 格式错误时抛出异常
+   *
+   * @example
+   * ```ts
+   * // 在 entry.node.ts 中使用
+   * async server(esmx) {
+   *   const manifest = await esmx.readJson(esmx.resolvePath('dist/client', 'manifest.json'));
+   *   // 使用 manifest 对象
+   * }
+   * ```
+   */
+  async readJson(filename) {
+    return JSON.parse(await fsp.readFile(filename, "utf-8"));
+  }
+  /**
+   * 获取构建清单列表
+   *
+   * @description
+   * 该方法用于获取指定目标环境的构建清单列表，包含以下功能：
+   * 1. **缓存管理**
+   *    - 使用内部缓存机制避免重复加载
+   *    - 返回不可变的清单列表
+   *
+   * 2. **环境适配**
+   *    - 支持客户端和服务端两种环境
+   *    - 根据目标环境返回对应的清单信息
+   *
+   * 3. **模块映射**
+   *    - 包含模块导出信息
+   *    - 记录资源依赖关系
+   *
+   * @param target - 目标环境类型
+   *   - 'client': 客户端环境
+   *   - 'server': 服务端环境
+   * @returns 返回只读的构建清单列表
+   * @throws {NotReadyError} 在框架实例未初始化时调用此方法会抛出错误
+   *
+   * @example
+   * ```ts
+   * // 在 entry.node.ts 中使用
+   * async server(esmx) {
+   *   // 获取客户端构建清单
+   *   const manifests = await esmx.getManifestList('client');
+   *
+   *   // 查找特定模块的构建信息
+   *   const appModule = manifests.find(m => m.name === 'my-app');
+   *   if (appModule) {
+   *     console.log('App exports:', appModule.exports);
+   *     console.log('App chunks:', appModule.chunks);
+   *   }
+   * }
+   * ```
+   */
+  async getManifestList(target) {
+    return this.readied.cache(
+      `getManifestList-${target}`,
+      async () => Object.freeze(await getManifestList(target, this.moduleConfig))
+    );
+  }
+  /**
+   * 获取导入映射对象
+   *
+   * @description
+   * 该方法用于生成 ES 模块导入映射（Import Map），具有以下特点：
+   * 1. **模块解析**
+   *    - 基于构建清单生成模块映射
+   *    - 支持客户端和服务端两种环境
+   *    - 自动处理模块路径解析
+   *
+   * 2. **缓存优化**
+   *    - 使用内部缓存机制
+   *    - 返回不可变的映射对象
+   *
+   * 3. **路径处理**
+   *    - 自动处理模块路径
+   *    - 支持动态基础路径
+   *
+   * @param target - 目标环境类型
+   *   - 'client': 生成浏览器环境的导入映射
+   *   - 'server': 生成服务端环境的导入映射
+   * @returns 返回只读的导入映射对象
+   * @throws {NotReadyError} 在框架实例未初始化时调用此方法会抛出错误
+   *
+   * @example
+   * ```ts
+   * // 在 entry.node.ts 中使用
+   * async server(esmx) {
+   *   // 获取客户端导入映射
+   *   const importmap = await esmx.getImportMap('client');
+   *
+   *   // 自定义 HTML 模板
+   *   const html = `
+   *     <!DOCTYPE html>
+   *     <html>
+   *     <head>
+   *       <script type="importmap">
+   *         ${JSON.stringify(importmap)}
+   *       <\/script>
+   *     </head>
+   *     <body>
+   *       <!-- 页面内容 -->
+   *     </body>
+   *     </html>
+   *   `;
+   * }
+   * ```
+   */
+  async getImportMap(target) {
+    return this.readied.cache(`getImportMap-${target}`, async () => {
+      const json = await getImportMap(
+        target,
+        await this.getManifestList(target),
+        this.moduleConfig
+      );
+      return Object.freeze(json);
+    });
+  }
+  /**
+   * 获取客户端导入映射信息
+   *
+   * @description
+   * 该方法用于生成客户端环境的导入映射代码，支持两种模式：
+   * 1. **内联模式 (inline)**
+   *    - 将导入映射直接内联到 HTML 中
+   *    - 减少额外的网络请求
+   *    - 适合导入映射较小的场景
+   *
+   * 2. **JS 文件模式 (js)**
+   *    - 生成独立的 JS 文件
+   *    - 支持浏览器缓存
+   *    - 适合导入映射较大的场景
+   *
+   * 核心功能：
+   * - 自动处理动态基础路径
+   * - 支持模块路径运行时替换
+   * - 优化缓存策略
+   * - 确保模块加载顺序
+   *
+   * @param mode - 导入映射模式
+   *   - 'inline': 内联模式，返回 HTML script 标签
+   *   - 'js': JS 文件模式，返回带有文件路径的信息
+   * @returns 返回导入映射的相关信息
+   *   - src: JS 文件的 URL（仅在 js 模式下）
+   *   - filepath: JS 文件的本地路径（仅在 js 模式下）
+   *   - code: HTML script 标签内容
+   * @throws {NotReadyError} 在框架实例未初始化时调用此方法会抛出错误
+   *
+   * @example
+   * ```ts
+   * // 在 entry.node.ts 中使用
+   * async server(esmx) {
+   *   const server = express();
+   *   server.use(esmx.middleware);
+   *
+   *   server.get('*', async (req, res) => {
+   *     // 使用 JS 文件模式
+   *     const result = await esmx.render({
+   *       importmapMode: 'js',
+   *       params: { url: req.url }
+   *     });
+   *     res.send(result.html);
+   *   });
+   *
+   *   // 或者使用内联模式
+   *   server.get('/inline', async (req, res) => {
+   *     const result = await esmx.render({
+   *       importmapMode: 'inline',
+   *       params: { url: req.url }
+   *     });
+   *     res.send(result.html);
+   *   });
+   * }
+   * ```
+   */
+  async getImportMapClientInfo(mode) {
+    return this.readied.cache(
+      `getImportMap-${mode}`,
+      async () => {
+        const importmap = await this.getImportMap("client");
+        const { basePathPlaceholder } = this;
+        let filepath = null;
+        if (this._importmapHash === null) {
+          let wrote = false;
+          const code = `(() => {
+const base = document.currentScript.getAttribute('data-base');
+const importmap = ${serialize(importmap, { isJSON: true })};
+if (importmap.imports && base) {
+    const imports = importmap.imports;
+    Object.entries(imports).forEach(([k, v]) => {
+        imports[k] = base + v;
+    });
+}
+document.head.appendChild(Object.assign(document.createElement('script'), {
+type: 'importmap',
+innerHTML: JSON.stringify(importmap)
+}));
+})();`;
+          const hash = contentHash(code);
+          filepath = this.resolvePath(
+            "dist/client/importmap",
+            `${hash}.final.js`
+          );
+          try {
+            const existingContent = await fsp.readFile(
+              filepath,
+              "utf-8"
+            );
+            if (existingContent === code) {
+              wrote = true;
+            } else {
+              wrote = await this.write(filepath, code);
+            }
+          } catch {
+            wrote = await this.write(filepath, code);
+          }
+          this._importmapHash = wrote ? hash : "";
+        }
+        if (mode === "js" && this._importmapHash) {
+          const src = `${basePathPlaceholder}${this.basePath}importmap/${this._importmapHash}.final.js`;
+          return {
+            src,
+            filepath,
+            code: `<script data-base="${basePathPlaceholder}" src="${src}"><\/script>`
+          };
+        }
+        if (importmap.imports && basePathPlaceholder) {
+          const imports = importmap.imports;
+          Object.entries(imports).forEach(([k, v]) => {
+            imports[k] = basePathPlaceholder + v;
+          });
+        }
+        return {
+          src: null,
+          filepath: null,
+          code: `<script type="importmap">${serialize(importmap, { isJSON: true })}<\/script>`
+        };
+      }
+    );
+  }
+  /**
+   * 获取模块的静态导入路径列表。
+   *
+   * @param target - 构建目标（'client' | 'server'）
+   * @param specifier - 模块标识符
+   * @returns 返回静态导入路径列表，如果未找到则返回 null
+   * @throws {NotReadyError} 在框架实例未初始化时调用此方法会抛出错误
+   *
+   * @example
+   * ```ts
+   * // 获取客户端入口模块的静态导入路径
+   * const paths = await esmx.getStaticImportPaths(
+   *   'client',
+   *   `your-app-name/src/entry.client`
+   * );
+   * ```
+   */
+  async getStaticImportPaths(target, specifier) {
+    return this.readied.cache(
+      `getStaticImportPaths-${target}-${specifier}`,
+      async () => {
+        const result = await getStaticImportPaths(
+          specifier,
+          await this.getImportMap(target),
+          this.moduleConfig
+        );
+        if (!result) {
+          return null;
+        }
+        return Object.freeze(Object.values(result));
+      }
+    );
+  }
+}
+async function defaultDevApp() {
+  throw new Error("'devApp' function not set");
+}
+class NotReadyError extends Error {
+  constructor() {
+    super(`The Esmx has not been initialized yet`);
+  }
+}
+function contentHash(text) {
+  const hash = crypto.createHash("sha256");
+  hash.update(text);
+  return hash.digest("hex").substring(0, 12);
+}