miaoda-expo-devkit 0.1.1-beta.5 → 0.1.1-beta.6

package/dist/metro.d.mts

@@ -1,52 +1,66 @@
 import { MetroConfig } from 'metro-config';
 
 /**
- * miaoda-expo-devkit/metro
+ * withNativeWind / patchNativeWindCachePath — NativeWind 缓存路径修复与 lazy wrapper
  *
- * 提供 Metro 配置增强函数：
- *   - withDevStubs(config)        模块替换：Sentry DSN 覆盖、LogBox 屏蔽
- *   - withEntryInjection(config)  bundle 首部脚本注入
- *   - withRouteEndpoint(config)   添加 /__routes 端点，返回路由树 JSON
- *   - withWorkspaceNodeModules(config)  修复 node_modules 位于项目父级目录时的资源加载 500 问题
+ * patchNativeWindCachePath：
+ *   将 NativeWind 编译缓存从 node_modules/.cache 重定向到项目根目录下的自定义目录。
+ *   ⚠️ 必须在 require('nativewind/metro') 之前调用，否则 outputDirectory 已经固化，patch 无效。
+ *
+ * withNativeWind：
+ *   nativewind/metro 的 lazy wrapper，确保 nativewind 在 patchNativeWindCachePath 之后加载，
+ *   拿到已 patch 的 outputDirectory。用法与 nativewind 官方 withNativeWind 完全相同。
  *
  * 用法（metro.config.js）：
+ *   const { withNativeWind } = require('miaoda-expo-devkit/metro');
+ *   // 不再需要单独 require('nativewind/metro')
+ *   module.exports = withNativeWind(config, { input: './global.css' });
+ */
+
+/** patchNativeWindCachePath 的配置选项 */
+interface PatchNativeWindCacheOptions {
+    /**
+     * 缓存目录，相对于 process.cwd()（Metro 项目根目录），默认 .native-wind-cache。
+     * 与 package.json 同级，避免写入只读的 node_modules。
+     */
+    cacheDir?: string;
+}
+/**
+ * 将 NativeWind 编译缓存从 node_modules/.cache 重定向到项目根目录下的自定义目录。
  *
- *   const { getDefaultConfig } = require('expo/metro-config');
- *   const { withDevStubs, withEntryInjection, withRouteEndpoint } = require('miaoda-expo-devkit/metro');
+ * ⚠️ 必须在 require('nativewind/metro') / require('react-native-css-interop/dist/metro')
+ * 之前调用，否则 outputDirectory 已经固化，patch 无效。
  *
- *   const config = getDefaultConfig(__dirname);
- *   module.exports = withRouteEndpoint(
- *     withEntryInjection(withDevStubs(config)),
- *     { appDir: path.join(__dirname, 'src', 'app') }
- *   );
+ * 原理：react-native-css-interop/dist/metro 在模块顶层用
+ *   const outputDirectory = path.resolve(__dirname, "../../.cache")
+ * 计算缓存路径。通过在 require 前临时替换 path.resolve，可将该值重定向到
+ * 项目根目录下的自定义缓存目录，而无需 fork 或修改 node_modules 源码。
  *
- * 链式用法（与其他 Metro wrapper 组合）：
+ * ⚠️ 已知限制：依赖 react-native-css-interop 使用 path.resolve 计算缓存路径，
+ * 升级该依赖时需确认此假设仍然成立。
  *
- *   module.exports = withNativeWind(withEntryInjection(withDevStubs(config)), { input: './global.css' });
+ * @param options 配置选项
  */
-
+declare function patchNativeWindCachePath(options?: PatchNativeWindCacheOptions): void;
 /**
- * 将开发阶段 stub 注入到 Metro config 中。
- *
- * 注入行为：
- *   1. web 平台：@expo/log-box 及 ErrorOverlayWebControls → no-op-logbox stub（屏蔽全屏错误遮罩）
- *   2. 所有平台：@sentry/react-native → sentry-react-native-stub（替换 DSN，注入内置捕获器）
+ * withNativeWind 的 lazy wrapper。
  *
- * 自动保留并调用已有的 resolveRequest，支持与其他 Metro 配置链式组合。
+ * nativewind/metro 在模块顶层捕获 react-native-css-interop 的 withCssInterop 引用，
+ * 因此必须在 patchNativeWindCachePath() 执行完之后才能加载 nativewind/metro。
+ * 这里使用 lazy require（在函数调用时才加载），确保 nativewind 拿到已 patch 的
+ * outputDirectory，而不需要在 metro.config.js 中手动处理加载顺序。
  *
- * @param config  Metro config 对象（来自 getDefaultConfig 或 getSentryExpoConfig）
- * @returns       注入 resolveRequest 后的新 Metro config
+ * @param config  Metro config 对象
+ * @param options nativewind withNativeWind 选项（与原包 API 完全一致）
  */
-declare function withDevStubs(config: MetroConfig): MetroConfig;
-/** withEntryInjection 的配置选项（预留，供未来支持自定义注入脚本路径扩展） */
-interface InjectOptions {
-}
+declare function withNativeWind(config: MetroConfig, options?: any): MetroConfig;
+
 /**
- * 在 expo-router 启动前注入一段脚本。
+ * withEntryInjection — 在 expo-router 启动前注入脚本
  *
  * 注入原理：
  *   拦截 Metro 对 expo-router/entry-classic 的解析，将其重定向到
- *   dist/stubs/expo-router-entry-stub.js。expo-router-entry-stub.js 先 require entry-inject.js
+ *   dist/stubs/expo-router-entry-stub.js。stub 先 require entry-inject.js
  *   （注入脚本），再 require expo-router/entry-classic（原入口），
  *   从而在 expo-router 启动前执行注入逻辑。
  *
@@ -57,20 +71,46 @@ interface InjectOptions {
  *       这条 import 语句经过 resolveRequest，可以被拦截。
  *
  * 执行顺序（在 bundle 中）：
- *   entry-inject.js（注入脚本：设置 __DEVKIT_INJECTED__ + 安装 HMR 控制器）
- *   → expo-router/entry-classic（原 expo-router 入口）
- *   → renderRootComponent(App)
+ *   entry-inject.js → expo-router/entry-classic → renderRootComponent(App)
  *
  * 注入的脚本经过完整 Babel 编译，支持现代语法，web + native 双平台均有效。
+ * 支持与 withDevStubs 及其他 Metro wrapper 链式组合。
  *
- * 支持与 withDevStubs 及其他 Metro wrapper 链式组合：
+ * 用法（metro.config.js）：
+ *   const { withEntryInjection } = require('miaoda-expo-devkit/metro');
  *   module.exports = withEntryInjection(withDevStubs(config));
+ */
+
+/** withEntryInjection 的配置选项（预留，供未来支持自定义注入脚本路径扩展） */
+interface InjectOptions {
+}
+/**
+ * 在 expo-router 启动前注入一段脚本。
  *
  * @param config  Metro config 对象
  * @param options 注入选项（当前预留，未来支持自定义注入脚本路径）
  * @returns       注入 resolveRequest 后的新 Metro config
  */
 declare function withEntryInjection(config: MetroConfig, options?: InjectOptions): MetroConfig;
+
+/**
+ * withRouteEndpoint — 为 Metro server 添加路由树查询端点
+ *
+ * 端点（默认 /__routes）返回 JSON 格式的路由树：
+ *   {
+ *     "routes": [
+ *       { "title": "首页", "pageId": "/", "pageName": "index", "visible": true, "path": "src/app/index.tsx" },
+ *       { "title": "id", "pageId": "/user/[id]", "pageName": "user-[id]", "visible": false, "path": "src/app/user/[id].tsx" }
+ *     ]
+ *   }
+ *
+ * 用法（metro.config.js）：
+ *   const { withRouteEndpoint } = require('miaoda-expo-devkit/metro');
+ *   module.exports = withRouteEndpoint(config, {
+ *     appDir: path.join(__dirname, 'src', 'app'),
+ *   });
+ */
+
 /** withRouteEndpoint 的配置选项 */
 interface RouteEndpointOptions {
     /** app 目录的绝对路径（包含路由文件的目录） */
@@ -81,100 +121,131 @@ interface RouteEndpointOptions {
 /**
  * 为 Metro server 添加 /__routes 端点，返回路由树 JSON。
  *
- * 端点返回格式：
- *   {
- *     "routes": [
- *       { "title": "首页", "pageId": "/", "pageName": "index", "visible": true, "path": "src/app/index.tsx" },
- *       { "title": "id", "pageId": "/user/[id]", "pageName": "user-[id]", "visible": false, "path": "src/app/user/[id].tsx" }
- *     ]
- *   }
- *
  * @param config  Metro config 对象
  * @param options 配置选项，必须提供 appDir
  * @returns       增强 server.enhanceMiddleware 后的新 Metro config
  */
 declare function withRouteEndpoint(config: MetroConfig, options: RouteEndpointOptions): MetroConfig;
+
 /**
- * 修复沙箱环境中 node_modules 位于项目父级目录时，资源文件（字体、图片等）加载返回 500 的问题。
+ * withDevkit — 一站式 Metro 配置入口
  *
- * 问题根因：
- *   pnpm 在沙箱中将 node_modules 安装到 projectRoot 的上层目录（如 /workspace/node_modules），
- *   而非 projectRoot 内（如 /workspace/app/node_modules）。
- *   Metro 处理 /assets/?unstable_path=./node_modules/.pnpm/... 请求时，会将路径解析为
- *   path.resolve(projectRoot, './node_modules/.pnpm/...')，得到一个不存在的路径，返回 500。
- *   实际文件在父级的 node_modules/.pnpm/ 下。
+ * 将模板 metro.config.js 所需的所有 devkit wrapper 封装为单个函数调用，
+ * 消除模板侧的 boilerplate。内部按固定顺序依次应用：
  *
- * 修复方式：
- *   向上查找实际的 node_modules 目录，将其加入 watchFolders（让 Metro 索引其中的文件）
- *   和 resolver.nodeModulesPaths（让模块解析也能找到包）。
+ *   withWorkspaceNodeModules — 修复沙箱中 node_modules 不在 projectRoot 内的问题
+ *   withCssInterop           — 为 expo-image / expo-camera 注入 NativeWind cssInterop
+ *   withEntryInjection       — 在 expo-router 启动前注入脚本（仅 __DEV__）
+ *   withDevStubs             — 替换 Sentry DSN / 屏蔽 LogBox（仅 __DEV__）
+ *   withRouteEndpoint        — 添加 /__routes 端点（仅 __DEV__）
+ *   withNativeWind           — NativeWind 支持（含缓存路径修复）
  *
- *   如果 node_modules 就在 projectRoot 下，则不做任何修改，直接返回原始 config。
+ * 用法（metro.config.js）：
+ *   const { getDefaultConfig } = require('expo/metro-config');
+ *   const { withDevkit } = require('miaoda-expo-devkit/metro');
+ *
+ *   module.exports = withDevkit(getDefaultConfig(__dirname));
+ */
+
+/** withDevkit 的配置选项 */
+interface DevkitOptions {
+    /**
+     * NativeWind 的 CSS 入口文件路径（相对于 projectRoot）。
+     * 默认：'./src/global.css'
+     */
+    input?: string;
+}
+/**
+ * 一站式应用所有 devkit Metro wrapper。
  *
  * @param config  Metro config 对象（来自 getDefaultConfig）
- * @returns       修正 watchFolders 和 nodeModulesPaths 后的新 Metro config
+ * @param options 配置选项
+ * @returns       完整配置后的 Metro config
  */
-declare function withWorkspaceNodeModules(config: MetroConfig): MetroConfig;
+declare function withDevkit(config: MetroConfig, options?: DevkitOptions): MetroConfig;
+
 /**
- * 为第三方 Expo 组件注入 NativeWind cssInterop，使其支持 className prop。
+ * withDevStubs — Metro resolver 注入开发阶段 stub
  *
- * 注入方式：Metro resolver 层拦截对应包的 import，重定向到 stub 文件。
- * stub 文件透传原包的所有导出，并调用 cssInterop 完成注册。
- * stub 内部 import 原包时，originModulePath 检查避免循环依赖。
+ * 注入行为：
+ *   1. web 平台：@expo/log-box 及 ErrorOverlayWebControls → no-op-logbox stub（屏蔽全屏错误遮罩）
+ *   2. 所有平台：@sentry/react-native → sentry-react-native-stub（替换 DSN，注入内置捕获器）
  *
- * 当前支持的包：
- *   - expo-image：Image 组件（className → style）
- *   - expo-camera：CameraView 组件（className → style）
+ * 自动保留并调用已有的 resolveRequest，支持与其他 Metro 配置链式组合。
  *
- * 此函数在开发和生产环境均需启用（cssInterop 注册与环境无关）。
- * 支持与其他 Metro wrapper 链式组合。
+ * 用法（metro.config.js）：
+ *   const { withDevStubs } = require('miaoda-expo-devkit/metro');
+ *   module.exports = withDevStubs(getDefaultConfig(__dirname));
+ */
+
+/**
+ * 将开发阶段 stub 注入到 Metro config 中。
  *
- * @param config  Metro config 对象
+ * @param config  Metro config 对象（来自 getDefaultConfig 或 getSentryExpoConfig）
  * @returns       注入 resolveRequest 后的新 Metro config
  */
-declare function withCssInterop(config: MetroConfig): MetroConfig;
-/** patchNativeWindCachePath 的配置选项 */
-interface PatchNativeWindCacheOptions {
-    /**
-     * 缓存目录，相对于 process.cwd()（Metro 项目根目录），默认 .native-wind-cache。
-     * 与 package.json 同级，避免写入只读的 node_modules。
-     */
-    cacheDir?: string;
-}
+declare function withDevStubs(config: MetroConfig): MetroConfig;
+
 /**
- * 将 NativeWind 编译缓存从 node_modules/.cache 重定向到项目根目录下的自定义目录。
+ * withWorkspaceNodeModules — 修复沙箱中 node_modules 不在 projectRoot 内时的模块解析问题
  *
- * ⚠️ 必须在 require('nativewind/metro') / require('react-native-css-interop/dist/metro')
- * 之前调用，否则 outputDirectory 已经固化，patch 无效。
+ * 覆盖两种场景：
  *
- * 原理：react-native-css-interop/dist/metro 在模块顶层用
- *   const outputDirectory = path.resolve(__dirname, "../../.cache")
- * 计算缓存路径。通过在 require 前临时替换 path.resolve，可将该值重定向到
- * 项目根目录下的自定义缓存目录，而无需 fork 或修改 node_modules 源码。
+ * 场景 A — node_modules 在 projectRoot 的上层目录（如 /workspace/node_modules）：
+ *   Metro 处理资源请求 /assets/?unstable_path=./node_modules/.pnpm/... 时，将路径解析为
+ *   path.resolve(projectRoot, './node_modules/.pnpm/...')，得到不存在的路径，返回 500。
+ *   修复：将上层的 node_modules 加入 watchFolders 和 resolver.nodeModulesPaths。
  *
- * 所有依赖 outputDirectory 的 NativeWind 行为（文件写入、虚拟模块 Map key、
- * Metro resolver 返回值、haste 事件）都会一致使用新路径，无需额外 Metro 层面的 patch。
+ * 场景 B — node_modules 在与 projectRoot 完全不同的路径（如 /data/expo/node_modules）：
+ *   Expo CLI 将入口文件的绝对路径（/data/expo/node_modules/.../expo-router/entry）
+ *   直接用作 bundle URL 路径。Metro 收到后去掉前导 "/" 并加上 "./"，
+ *   得到 "./data/expo/node_modules/..."，再从 projectRoot 解析，找不到文件。
+ *   修复：在上述两项基础上，追加自定义 resolver，
+ *         将 "./data/expo/..." 还原为 "/data/expo/..." 后直接返回文件路径。
  *
- * ⚠️ 已知限制：依赖 react-native-css-interop 使用 path.resolve 计算缓存路径，
- * 升级该依赖时需确认此假设仍然成立。
+ * node_modules 定位策略（按优先级）：
+ *   1. 从 projectRoot 向上逐级查找 node_modules 目录；
+ *   2. 若未找到，通过 require.resolve 定位当前包所在的 node_modules 根目录
+ *      （适用于 node_modules 位于完全不同路径的情况）。
  *
  * 用法（metro.config.js）：
- *   const { patchNativeWindCachePath } = require('miaoda-expo-devkit/metro');
- *   patchNativeWindCachePath(); // 必须在 require nativewind/metro 之前调用
- *   const { withNativeWind } = require('nativewind/metro');
+ *   const { withWorkspaceNodeModules } = require('miaoda-expo-devkit/metro');
+ *   module.exports = withWorkspaceNodeModules(config);
  */
-declare function patchNativeWindCachePath(options?: PatchNativeWindCacheOptions): void;
+
 /**
- * withNativeWind 的 lazy wrapper。
+ * 修复沙箱环境中 node_modules 不在 projectRoot 内时，Metro 资源和入口模块解析失败的问题。
  *
- * nativewind/metro 在模块顶层捕获 react-native-css-interop 的 withCssInterop 引用，
- * 因此必须在 patchNativeWindCachePath() 执行完之后才能加载 nativewind/metro。
- * 这里使用 lazy require（在函数调用时才加载），确保 nativewind 拿到已 patch 的
- * outputDirectory，而不需要在 metro.config.js 中手动处理加载顺序。
+ * @param config  Metro config 对象（来自 getDefaultConfig）
+ * @returns       修正 watchFolders、nodeModulesPaths（及必要时 resolveRequest）后的新 Metro config
+ */
+declare function withWorkspaceNodeModules(config: MetroConfig): MetroConfig;
+
+/**
+ * withCssInterop — 为第三方 Expo 组件注入 NativeWind cssInterop
+ *
+ * 注入方式：Metro resolver 层拦截对应包的 import，重定向到 stub 文件。
+ * stub 文件透传原包的所有导出，并调用 cssInterop 完成注册。
+ * stub 内部 import 原包时，originModulePath 检查避免循环依赖。
+ *
+ * 当前支持的包：
+ *   - expo-image：Image 组件（className → style）
+ *   - expo-camera：CameraView 组件（className → style）
+ *
+ * 此函数在开发和生产环境均需启用（cssInterop 注册与环境无关）。
+ * 支持与其他 Metro wrapper 链式组合。
  *
  * 用法（metro.config.js）：
- *   const { withNativeWind } = require('miaoda-expo-devkit/metro');
- *   // 不再需要 require('nativewind/metro')
+ *   const { withCssInterop } = require('miaoda-expo-devkit/metro');
+ *   module.exports = withCssInterop(config);
  */
-declare function withNativeWind(config: MetroConfig, options?: any): MetroConfig;
 
-export { type InjectOptions, type PatchNativeWindCacheOptions, type RouteEndpointOptions, patchNativeWindCachePath, withCssInterop, withDevStubs, withEntryInjection, withNativeWind, withRouteEndpoint, withWorkspaceNodeModules };
+/**
+ * 为第三方 Expo 组件注入 NativeWind cssInterop，使其支持 className prop。
+ *
+ * @param config  Metro config 对象
+ * @returns       注入 resolveRequest 后的新 Metro config
+ */
+declare function withCssInterop(config: MetroConfig): MetroConfig;
+
+export { type DevkitOptions, type InjectOptions, type PatchNativeWindCacheOptions, type RouteEndpointOptions, patchNativeWindCachePath, withCssInterop, withDevStubs, withDevkit, withEntryInjection, withNativeWind, withRouteEndpoint, withWorkspaceNodeModules };