miaoda-expo-devkit 0.1.1-beta.2 → 0.1.1-beta.21

package/dist/metro.d.ts

@@ -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 中。
+ * withNativeWind 的 lazy wrapper。
  *
- * 注入行为：
- *   1. web 平台：@expo/log-box 及 ErrorOverlayWebControls → no-op-logbox stub（屏蔽全屏错误遮罩）
- *   2. 所有平台：@sentry/react-native → sentry-react-native-stub（替换 DSN，注入内置捕获器）
+ * nativewind/metro 在模块顶层捕获 react-native-css-interop 的 withCssInterop 引用，
+ * 因此必须在 patchNativeWindCachePath() 执行完之后才能加载 nativewind/metro。
+ * 这里使用 lazy require（在函数调用时才加载），确保 nativewind 拿到已 patch 的
+ * outputDirectory，而不需要在 metro.config.js 中手动处理加载顺序。
  *
- * 自动保留并调用已有的 resolveRequest，支持与其他 Metro 配置链式组合。
- *
- * @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,45 @@ 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", "path": "src/app/index.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,38 +120,158 @@ interface RouteEndpointOptions {
 /**
  * 为 Metro server 添加 /__routes 端点，返回路由树 JSON。
  *
- * 端点返回格式：
- *   {
- *     "routes": [
- *       { "title": "首页", "pageId": "/", "pageName": "index", "visible": true, "path": "index.tsx" },
- *       { "title": "id", "pageId": "/user/[id]", "pageName": "user-[id]", "visible": false, "path": "user/[id].tsx" }
- *     ]
- *   }
- *
  * @param config  Metro config 对象
  * @param options 配置选项，必须提供 appDir
  * @returns       增强 server.enhanceMiddleware 后的新 Metro config
  */
 declare function withRouteEndpoint(config: MetroConfig, options: RouteEndpointOptions): MetroConfig;
+
+/**
+ * withDevkit — 一站式 Metro 配置入口
+ *
+ * 将模板 metro.config.js 所需的所有 devkit wrapper 封装为单个函数调用，
+ * 消除模板侧的 boilerplate。内部按固定顺序依次应用：
+ *
+ *   withWorkspaceNodeModules    — 修复沙箱中 node_modules 不在 projectRoot 内的问题
+ *   withCssInterop              — 为 expo-image / expo-camera 注入 NativeWind cssInterop
+ *   withExpoNotificationsStub   — Android：expo-notifications → stub（Expo Go no-op，Dev Build 透传）
+ *   withEntryInjection          — 在 expo-router 启动前注入脚本（仅 __DEV__）
+ *   withDevStubs                — 替换 Sentry DSN / 屏蔽 LogBox（仅 __DEV__）
+ *   withRouteEndpoint           — 添加 /__routes 端点（仅 __DEV__）
+ *   withNativeWind              — NativeWind 支持（含缓存路径修复）
+ *
+ * 用法（metro.config.js）：
+ *   const { getDefaultConfig } = require('expo/metro-config');
+ *   const { withDevkit } = require('miaoda-expo-devkit/metro');
+ *
+ *   module.exports = withDevkit(getDefaultConfig(__dirname));
+ */
+
+/**
+ * Android 平台：将 expo-notifications 替换为 stub。
+ * stub 内部根据 isRunningInExpoGo() 决定是 no-op（Expo Go）还是透传真实模块（Development Build）。
+ *
+ * 注意：此 wrapper 必须在 if (__DEV__) 外部调用，因为它需要在所有构建模式下生效。
+ * Expo Go 中 native module 的缺失是运行时问题，与开发/生产模式无关。
+ */
+declare function withExpoNotificationsStub(config: MetroConfig): MetroConfig;
+/** withDevkit 的配置选项 */
+interface DevkitOptions {
+    /**
+     * NativeWind 的 CSS 入口文件路径（相对于 projectRoot）。
+     * 默认：'./src/global.css'
+     */
+    input?: string;
+}
+/**
+ * 一站式应用所有 devkit Metro wrapper。
+ *
+ * @param config  Metro config 对象（来自 getDefaultConfig）
+ * @param options 配置选项
+ * @returns       完整配置后的 Metro config
+ */
+declare function withDevkit(config: MetroConfig, options?: DevkitOptions): MetroConfig;
+
+/**
+ * withDevStubs — Metro resolver 注入开发阶段 stub
+ *
+ * 注入行为：
+ *   1. web 平台：@expo/log-box 及 ErrorOverlayWebControls → no-op-logbox stub（屏蔽全屏错误遮罩）
+ *   2. 所有平台：@sentry/react-native → sentry-react-native-stub（替换 DSN，注入内置捕获器）
+ *
+ * 自动保留并调用已有的 resolveRequest，支持与其他 Metro 配置链式组合。
+ *
+ * 用法（metro.config.js）：
+ *   const { withDevStubs } = require('miaoda-expo-devkit/metro');
+ *   module.exports = withDevStubs(getDefaultConfig(__dirname));
+ */
+
 /**
- * 修复沙箱环境中 node_modules 位于项目父级目录时，资源文件（字体、图片等）加载返回 500 的问题。
+ * 将开发阶段 stub 注入到 Metro config 中。
  *
- * 问题根因：
- *   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/ 下。
+ * @param config  Metro config 对象（来自 getDefaultConfig 或 getSentryExpoConfig）
+ * @returns       注入 resolveRequest 后的新 Metro config
+ */
+declare function withDevStubs(config: MetroConfig): MetroConfig;
+
+/**
+ * withWorkspaceNodeModules — 修复沙箱中 node_modules 不在 projectRoot 内时的模块解析问题
  *
- * 修复方式：
- *   向上查找实际的 node_modules 目录，将其加入 watchFolders（让 Metro 索引其中的文件）
- *   和 resolver.nodeModulesPaths（让模块解析也能找到包）。
+ * 适用场景：node_modules 位于 projectRoot 的祖先目录（如 /workspace/node_modules），
+ * 而 projectRoot 自身的 node_modules 为空目录或不存在。
  *
- *   如果 node_modules 就在 projectRoot 下，则不做任何修改，直接返回原始 config。
+ * 问题：
+ *   1. Metro 只监听 projectRoot，祖先目录的 node_modules 不在 watchFolders 内，
+ *      导致模块无法被 file map 索引。
+ *   2. pnpm 的 .pnpm 目录可能是指向外部路径的 symlink
+ *      （如 /workspace/node_modules/.pnpm → /data/expo/node_modules/.pnpm）。
+ *      Metro 跟随 symlink 后，将文件以真实路径（/data/expo/...）存入 file map，
+ *      HTML 入口的 bundle URL 也随之变为 /data/expo/...bundle。
+ *      若 /data/expo/node_modules/ 不在 watchFolders，Metro HTTP server 会返回 404。
+ *
+ * 修复：
+ *   1. 将祖先目录的 node_modules 加入 watchFolders 和 resolver.nodeModulesPaths。
+ *   2. 若该 node_modules 下的 .pnpm 是指向外部路径的 symlink，
+ *      同样将外部真实路径加入 watchFolders 和 resolver.nodeModulesPaths。
+ *
+ * 用法（metro.config.js）：
+ *   const { withWorkspaceNodeModules } = require('miaoda-expo-devkit/metro');
+ *   module.exports = withWorkspaceNodeModules(config);
+ */
+
+/**
+ * 修复沙箱环境中 node_modules 位于祖先目录时，Metro 模块解析和 bundle 请求失败的问题。
  *
  * @param config  Metro config 对象（来自 getDefaultConfig）
- * @returns       修正 watchFolders 和 nodeModulesPaths 后的新 Metro config
+ * @returns       修正 watchFolders、nodeModulesPaths 后的新 Metro config
  */
 declare function withWorkspaceNodeModules(config: MetroConfig): MetroConfig;
 
-export { type InjectOptions, type RouteEndpointOptions, withDevStubs, withEntryInjection, withRouteEndpoint, withWorkspaceNodeModules };
+/**
+ * withCssInterop — 为第三方 Expo 组件注入 NativeWind cssInterop
+ *
+ * 注入方式：Metro resolver 层拦截对应包的 import，重定向到 stub 文件。
+ * stub 文件透传原包的所有导出，并调用 cssInterop 完成注册。
+ * stub 内部 import 原包时，originModulePath 检查避免循环依赖。
+ *
+ * 当前支持的包：
+ *   - expo-image：Image 组件（className → style）
+ *   - expo-camera：CameraView 组件（className → style）
+ *   - expo-linear-gradient：LinearGradient 组件（className → style）
+ *   - expo-blur：BlurView / BlurTargetView 组件（className → style）
+ *
+ * 注意：react-native-reanimated 不拦截。cssInterop 全局注册 Animated.* 会导致所有动画 style 注入失败。
+ * 需要同时使用 Tailwind className 和动画的场景，请在组件层面单独用 createAnimatedComponent + cssInterop 封装。
+ *
+ * 注意：expo-video 的 VideoView 在 web 上直接渲染 DOM <video> 元素，不经过 RN 样式系统，
+ * cssInterop/remapProps 均无效，不做拦截。需要 className 时请用 View 包裹 VideoView。
+ *
+ * 此函数在开发和生产环境均需启用（cssInterop 注册与环境无关）。
+ * 支持与其他 Metro wrapper 链式组合。
+ *
+ * 用法（metro.config.js）：
+ *   const { withCssInterop } = require('miaoda-expo-devkit/metro');
+ *   module.exports = withCssInterop(config);
+ */
+
+/**
+ * 为第三方 Expo 组件注入 NativeWind cssInterop，使其支持 className prop。
+ *
+ * @param config  Metro config 对象
+ * @returns       注入 resolveRequest 后的新 Metro config
+ */
+declare function withCssInterop(config: MetroConfig): MetroConfig;
+
+/**
+ * 将 Metro transformer 的 minifier 切换为 esbuild。
+ *
+ * esbuild 比 terser 快数十倍，内存占用极低，非常适合 web 生产构建。
+ * 通过 metro-minify-esbuild 桥接，pnpm 会将 esbuild 作为其 peer dep 一并安装，
+ * 解析路径在 devkit 上下文中（metro.config.js 加载时）完成。
+ *
+ * 注意：切换 minifier 时必须清空 minifierConfig，因为默认 config 含有
+ * terser 专属选项（如 mangle、compress 等），传给 esbuild 会报错。
+ */
+declare function withEsbuildMinify(config: MetroConfig): MetroConfig;
+
+export { type DevkitOptions, type InjectOptions, type PatchNativeWindCacheOptions, type RouteEndpointOptions, patchNativeWindCachePath, withCssInterop, withDevStubs, withDevkit, withEntryInjection, withEsbuildMinify, withExpoNotificationsStub, withNativeWind, withRouteEndpoint, withWorkspaceNodeModules };