Frappe Island 预设的构建工具链解析从宿主 App 的依赖中加载 Vite、Tailwind 与 TypeScript【免费下载链接】frappeLow code web framework for real world applications, in Python and Javascript项目地址: https://gitcode.com/GitHub_Trending/fr/frappeFrappe 的 desk island 子系统允许应用把 Vue 组件作为可独立挂载的岛island构建进自己的 SPA而构建这些 island 的 Vite 预设preset本身却不携带任何工具链。本文围绕架构决策记录 ui/island/decisions/0005-the-preset-resolves-its-tooling-from-the-app.md完整讲解预设从被构建的 App 中解析自身工具链这一设计loadTools(root)如何在 App 的node_modules/.island/下生成再导出模块、为何采用此方案、版本一致性如何被锁定以及被否决的三种替代方案及其原因。读完本文你将理解 island 构建中 bare specifier裸模块名解析的本质并能独立排查构建工具链无法解析类错误。问题背景预设自身不携带任何构建工具Frappe 的 island 预设以源码形式随framework/ui包发布而 bench 通过相对路径链接symlinkframework/ui。这意味着当预设源码中的import vite被执行时Node 会基于导入方模块的真实路径real path来解析 bare specifier——也就是在 framework 检出目录旁寻找依赖而 bench 从不会在该处安装前端依赖。构建一个 island 需要一整套工具链Vite、vitejs/plugin-vue、Tailwind、autoprefixer、TypeScript以及 frappe-ui 的图标解析器icon resolver。预设的选择是不自己声明、不自己安装、不自己解析这些依赖而是从被构建的那个 App处加载它们。决策记录原文如此概括The preset needs Vite,vitejs/plugin-vue, Tailwind, autoprefixer, TypeScript and frappe-uis icon resolver to run a build. It loads each one from the app it builds.这一思路贯穿整个 island 构建管线具体实现在 ui/vite/island/index.js 与 ui/vite/island/tools.js 中。决策核心loadTools(root)生成再导出模块决策的关键一行loadTools(root)writes a module into the appsnode_modules/.island/. The module re-exports every build-time dependency by name, and the preset imports it.即预设不直接import vite而是在 App 自己的node_modules/.island/目录下写入一个tools.mjs模块该模块按名字再导出所有构建期依赖然后预设再动态导入这个生成的文件。由此bare specifier 的解析工作被完整交给 Node 自己的解析器且解析的起点是App 的应用树apps own tree——App 的node_modules才是 Vite、Tailwind 和 frappe-ui 真正被安装的位置。源码级实现TOOLS 清单与生成逻辑tools.js 中定义了预设所需的全部工具共七项导出键模块说明符用途viteviteisland 构建的打包器vuevitejs/plugin-vueVue 单文件组件编译插件tailwindcsstailwindcss样式扫描与生成autoprefixerautoprefixerPostCSS 浏览器前缀lucideIconsfrappe-ui/vite/lucideIconsPluginfrappe-ui 的 lucide 图标解析compilerSfcvue/compiler-sfcVue SFC 编译器typescripttypescript供 compiler-sfc 解析外部类型loadTools(root)的实现要点ui/vite/island/tools.js#L42-L71在path.join(root, node_modules/.island)目录下生成tools.mjs每行形如export * as vite from vite;生成文件头部标注// Generated by framework/ui/vite/island. Do not edit.通过await import(pathToFileURL(file).href)动态导入生成文件若导入失败抛出带明确修复指引的错误island: the build tooling does not resolve from root: ...并提示Add the missing package to the frontends devDependencies。生成目录选择node_modules/.island的原因在源码注释中说明Generated modules live where every other build artifact does——Tailwind 配置生成ui/vite/island/tailwind.js也基于同一理由写入该目录因为只有写入 App 的node_modules树内配置文件中的 bare specifier如frappe-ui/tailwind内部的tailwindcss/plugin才能对 App 的依赖解析。为什么必须写文件而不是直接解析决策文档解释了深层的解析机制差异require.resolve读取的是require条件因此拒绝 ESM-only 的子路径——frappe-ui/vite/lucideIconsPlugin正是其中之一import.meta.resolve在 Node 未开启--experimental-import-meta-resolve时会忽略其 parent 参数随后按预设自身的路径作答毫无意义。而把文件写进 App 的应用树再让 Node 解析则把整个解析工作交给 Node 的原生解析器其import条件能正确处理 ESM-only 子路径也天然以 App 为解析根。这正是决策Rejected: resolve each specifier by hand一节否掉手工解析方案的根本原因。版本一致性由 App 的 lockfile 一锤定音决策文档明确指出这一设计还顺带解决了哪个版本的依赖构建了 island的问题The apps lockfile decides. The same lockfile builds the apps SPA, so an island and the apps own pages compile the same frappe-ui the same way.island 构建所用的 Vite、Tailwind、frappe-ui 等版本完全由App 的package.json lockfile决定同一个 lockfile 也构建 App 的 SPA因此island 与 App 自身页面用同一份 frappe-ui 源码、以同样的方式编译不存在双份工具链、双份编译结果漂移的问题。这也正是决策记录否决framework declares the tooling方案的核心论据若把 Vite、Tailwind 等放进 framework 的apps/frappe/package.jsonframework 将被迫安装一套自己永不运行的第二套前端工具链并钉死所有 App 构建 island 的版本——一个使用更新版 Vite 的 App会用一个版本构建 SPA、用另一个版本构建 island。依赖声明可选的 peerDependencies安装时一次性提示当生成模块中的一个 specifier 无法解析时构建直接失败。错误信息会点名 App 的 root 路径与devDependencies作为修复方向A specifier that does not resolve fails the build. The error names the apps root anddevDependenciesas the fix.framework/ui在 ui/package.json 中将 Vite、vitejs/plugin-vue、Tailwind、autoprefixer、TypeScript 等全部声明为optional peer dependenciespeerDependenciesMeta中标记optional: true。效果是使用方 App 只需在yarn install时收到一次提示而不会被强制安装——因为 framework 自身并不运行这些工具真正的宿主是 App。与工具链包的对照toolchain 目录仓库内另有一个仅供框架侧自测的对照物ui/vite/island/toolchain/package.json包名framework/island-toolchain。其devDependencies声明了 Vite ^8.1.5、tailwindcss ^3.4.19、typescript ^5.9.3、frappe-ui 1.0.0-beta.55 等且framework/ui以link:../../..方式引用。需要区分这是框架开发者验证预设的隔离工具链而非 App 实际构建 island 所依赖的工具链——真实构建时工具链一律来自 App 自己的node_modules。从源码看后续加工CommonJS 互操作与 TypeScript 注册loadTools之后构建管线对加载到的工具还有两处关键加工ui/vite/island/tools.js#L73-L95interop互操作Tailwind、autoprefixer、compiler-sfc 都是 CommonJS 模块。静态import x from tailwindcss会把module.exports绑定到x而 namespace import 回答的是 namespace 对象module.exports被放在其default上。因此interop (module) module.default ?? module负责统一取回真实导出。registerTypeScriptfrappe-ui 的ImageGroupNodeView.vue写了definePropsNodeViewProps()其中的类型来自tiptap/vue-3。compiler-sfc 只有通过 TypeScript 编译器 API 才能解析该外部类型而vitejs/plugin-vue不会注册编译器所以预设显式调用compilerSfc.registerTS(() typescript)版本要求 TS 5因为相关类型位于只有moduleResolution: bundler才能穿过的exportsmaps 之后。这两处加工被 ui/vite/island/index.js 的islandContexttools: await loadTools(root)与islandConfig消费Vite 的build、vitejs/plugin-vue、Tailwind PostCSS 插件、autoprefixer、lucideIconsPlugin均来自context.tools证明工具全部取自 App不是文档中的孤证而是构建管线的真实数据流。被否决的替代方案为什么三条路都不走决策记录用三个小节完整记录了被否决的替代方案这是理解该决策价值的关键方案一手工逐个解析说明符Rejected: resolve each specifier by hand用根植于 App 的require.resolve或以 App 为 parent 的import.meta.resolve。失败原因如上文所述require.resolve读require条件拒绝 ESM-only 子路径frappe-ui/vite/lucideIconsPlugin即一例import.meta.resolve除非开启--experimental-import-meta-resolve否则忽略 parent 参数只会按预设自身路径作答。最终结论让写入的文件把整个解析工作交给 Node 的解析器是唯一干净的做法。方案二由 framework 声明工具链Rejected: framework declares the tooling把 Vite、Tailwind 等放进apps/frappe/package.json让预设自身路径即可解析。代价是 framework 安装了永不会运行的第二套前端工具链并钉死所有 App 的 island 构建版本——App 的 SPA 与 island 将各用各的 Vite破坏版本一致性。方案三由 App 把模块传进来Rejected: the app passes the modules in即buildIslands({ vite, tailwindcss, ... })的显式传参形式。决策记录的评价是It is the same resolution, written out by every app——每个 App 都要重复一遍同样的解析样板代码更糟的是传错模块的 App 要等进入 Rollup 内部才能发现问题错误延迟且难以定位。而生成文件方案把解析这件事收口到一处出错的 App 会在构建入口处立刻得到指名devDependencies的错误。测试验证verify.mjs 如何检验这套解析设计ui/vite/island/tests/verify.mjs 是这套预设的集成验证脚本直接体现了预设跑在 App 自己的工具链上这一约束它把tests/fixture/暂存为一个一次性 bench 里的 App frontend借用某个已执行过yarn install的 App frontend 的node_modulesmirrorModules逐项符号链接并让framework/ui指向本 checkout因为预设构建在 App 自己的工具链上fixture 本身不携带依赖运行buildIslands后校验输出为 ESM、mount导出保留、无 bare import 残留、lucide 图标 SVG 被打进 bundle、两个入口共享 chunk、单份样式表含 preflight 与主题 token、超预算仍能注册 assets.json 等。其中无 bare import 残留bareImports(panel.text).length 0正是对island 在浏览器端不依赖任何运行时解析这一目标的验证与本文所述构建期工具链解析自 App互为表里构建期的解析交给 App 的 Node 解析器运行期的解析则必须在打包时彻底完成。实战排查指南工具链解析失败怎么办综合决策文档与 tools.js 的错误信息当 island 构建报出 the build tooling does not resolve from ... 时按以下顺序排查确认目标 App 的 frontend 目录已执行过yarn install——node_modules必须存在且完整对照TOOLS清单检查 App 的devDependenciesvite、vitejs/plugin-vue、tailwindcss、autoprefixer、typescript、frappe-ui、vue是否齐全参考 ui/package.json 中framework/ui声明的 peer 范围如vite 4、tailwindcss ^3.4.0、typescript 5注意 ESM-only 子路径frappe-ui/vite/lucideIconsPlugin必须通过 Node 的import条件解析这正说明为何不能退回require.resolve手工解析方案检查 lockfile 是否被手动改动——island 与 SPA 必须由同一 lockfile 决定版本任何双 lockfile 的局面都会破坏一致性。小结预设从 App 解析自身工具链是一条围绕 Node 模块解析语义精心权衡的架构决策它用写入 App 应用树的再导出模块绕开 bare specifier 解析根的问题用App 的 lockfile 决定版本锁死 island 与 SPA 的编译一致性用optional peer dependencies 构建期报错把依赖缺失的反馈压缩到安装提示与一次清晰的构建错误。三种被否决方案手工解析、framework 声明、App 传参各自的缺陷——ESM 子路径拒绝、双工具链版本漂移、错误延迟到 Rollup 内部——反过来印证了最终方案在每个维度上的取舍。该决策与其余 island 决策共同构成 desk island 子系统ui/island/decisions/README.md的设计基石。【免费下载链接】frappeLow code web framework for real world applications, in Python and Javascript项目地址: https://gitcode.com/GitHub_Trending/fr/frappe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
