前端Web框架SSR前端构建插件系统微前端跨平台【免费下载链接】ice ice.js: The Progressive App Framework Based On React基于 React 的渐进式应用框架项目地址https://gitcode.com/gh_mirrors/ice1/ice点击查看免费下载导读本文介绍 ice.js 官方兼容插件ice/plugin-rax-compat它用于将基于 rax-app 开发的存量项目迁移到 ice.js 渐进式应用框架。读完本文你将掌握该插件的安装与配置方法、inlineStyle/cssModule/legacy三个核心选项的含义与适用场景并从源码层面理解它在类型定义、模块别名、JSX 编译与样式处理四个维度上的兼容机制以及如何利用仓库中的示例工程与集成测试验证迁移结果。插件定位为 rax-app 存量项目提供迁移通道rax-app 是阿里巴巴推出的跨端应用框架其组件库rax-view、rax-text、rax-image等与运行时 API如createElement、createContext在 API 形态上与 React 高度相似但并非完全等价。当项目需要从 rax-app 迁移到基于 React 的 ice.js 时会遇到三类典型障碍类型体系不匹配Rax 的类型定义基于 React 16.8 之前的时代与 React 18 的类型定义存在差异直接迁移会出现大量类型报错模块路径不同rax-children、rax-clone-element等组成 Rax 核心逻辑的rax-*包在 React 生态中并不存在样式模型不同Rax 项目习惯使用classNameheader配合样式表内联styleSheet的写法与 Web 端 CSS 文件外链的模型不同。ice/plugin-rax-compat正是为了解决这些问题而存在。它是一个标准的 ice.js 构建期插件PluginRaxCompatPluginOptions其入口 packages/plugin-rax-compat/src/index.ts 在setup阶段依次挂载了四个服务TypingsService类型声明、AliasService模块别名、JSXServiceJSX 编译、StyleService样式处理从插件 package.json 可以看到它依赖rax-compat、stylesheet-loader、babel-plugin-transform-jsx-stylesheet、ice/bundles等包来完成这些工作。安装与基本配置首先安装插件依赖npm install ice/plugin-rax-compat --save-dev # 或 pnpm add -D ice/plugin-rax-compat然后在项目根目录的ice.config.mts中注册插件import { defineConfig } from ice; import compatRax from ice/plugin-rax-compat; export default defineConfig(() ({ plugins: [compatRax({ /* options */ })], }));仓库中的 examples/rax-project/ice.config.mts 给出了一个最简示例直接调用compatRax()不传任何选项即可获得默认行为且可与其他插件如ice/plugin-jsx-plus组合使用import { defineConfig } from ice/app; import compatRax from ice/plugin-rax-compat; import jsxPlus from ice/plugin-jsx-plus; export default defineConfig(() ({ publicPath: /, plugins: [ compatRax(), jsxPlus(), ], }));插件选项详解插件的完整选项类型定义在 packages/plugin-rax-compat/src/typings.ts 中入口 src/index.ts 的normalizeOptions会为未传入的选项补齐默认值。下表汇总了三个选项的含义与默认值选项类型默认值作用inlineStyleboolean \| ((id: string) boolean)false启用 stylesheet loader将命中的样式资源导入为内联的 styleSheet 对象cssModulebooleantrue控制.module.cssless/scss文件是否走 CSS Module 处理legacybooleanfalse兼容 Rax v0.6.x 的命名空间导入方式如import Rax from raxinlineStyle是否启用行内样式默认false。开启后插件会启用 stylesheet loader 来导入 CSS 文件把样式编译为可供 JS 引用的 styleSheet 对象从而支持 Rax 风格的内联样式写法。值得注意的是inlineStyle除了布尔值之外还支持函数形式。在 src/typings.ts 的类型定义中它被声明为boolean | ((id: string) boolean)即可以按文件路径精确控制哪些文件启用内联样式。这一点在 src/services/styles/index.ts 的StyleService.provide中有明确提示当全量启用inlineStyle: true时插件会输出一条警告建议改用函数式写法控制内联样式的影响范围inlineStyle: (id) id.includes(inline-style-module),判断逻辑由 src/utils.ts 中的checkInlineStyleEnable实现函数类型直接调用该函数并返回结果布尔类型直接返回本身。cssModule控制 CSS Module 文件的处理方式默认true。当inlineStyle启用、且cssModule被关闭时.module.css以及.module.less等文件也会被交由 stylesheet-loader 处理即把 CSS Module 文件也内联为样式对象——但原文档明确指出这种做法不推荐。原因是 CSS Module 的类名在编译后是局部化的哈希值其本意是配合className{styles.xxx}使用强行内联会破坏模块隔离语义。legacy兼容 Rax v0.6.x 的导入方式默认false。启用后支持 Rax 老版本v0.6.x的默认导入 命名空间调用写法import Rax from rax; Rax.createContext();四大兼容逻辑的实现原理原文档明确了该插件处理的四类兼容逻辑类型定义、别名、JSX、样式。下面结合源码逐一展开。1. 类型定义用 React 18 的类型补齐 Rax 命名空间Rax 的类型定义停留在 React 16.8 时代与 React 18 的类型定义存在差异。插件会向.ice目录渲染一份rax-compat.d.ts模板见 packages/plugin-rax-compat/src/templates/rax-compat.d.ts内部直接复用 React 的类型定义对Rax命名空间进行声明涵盖FC、ForwardRefRenderFunction、RaxNode、PropsWithChildren、RaxFragment、RaxChildren等常用类型。具体实现位于 src/services/typings.tsTypingsService通过api.generator.addRenderFile把模板渲染到构建目录再通过addExport以纯类型导入type __UNUSED_TYPE_FOR_IMPORT_EFFECT_ONLY__的方式引入注释中解释了这样做的原因——避免值导入触发 Webpack 编译报错Export assignment cannot be used when targeting ECMAScript modules.该 .d.ts 使用export 语法。2. 别名把 rax-* 包映射到 rax-compat 内部实现Rax 的核心逻辑由一组rax-*包组成如rax-children、rax-clone-element这些包在 React 生态中不存在。插件通过 Webpack/构建工具的 alias 机制将它们映射到rax-compat包的内部实现。完整的别名注册表定义在 src/services/alias.ts 的AliasRegistry中别名映射目标raxrax-compatrax-childrenrax-compat/childrenrax-clone-elementrax-compat/clone-elementrax-create-classrax-compat/create-classrax-create-factoryrax-compat/create-factoryrax-create-portalrax-compat/create-portalrax-find-dom-noderax-compat/find-dom-noderax-is-valid-elementrax-compat/is-valid-elementrax-unmount-component-at-noderax-compat/unmount-component-at-noderax-compat/runtime/jsx-dev-runtimerax-compat/runtime/jsx-dev-runtimerax-compat/runtime/jsx-runtimerax-compat/runtime/jsx-runtime这些映射在api.onGetConfig阶段合并进构建配置的config.alias。当启用legacy模式时AliasService还会做两件额外的事通过api.generator.addRenderFile把 src/templates/rax-compat-legacy-exports.ts.template 渲染为.ice/rax-compat-legacy-exports.ts将rax的别名指向这个生成的文件。从模板内容可以看到该文件同时支持三种导入形态import * as rax from rax-compat的命名空间导入v1.0、export * from rax-compat的具名导出、以及export default { ...rax }的默认导出v0.6并额外补充了 Rax 时代的PropTypes对象用空函数占位从而让Rax.createContext()这类 v0.6.x 写法可以正常工作。启用legacy时插件会输出一条 warninglegacy 模式仅应用于兼容 rax v0.6.x。3. JSX基于源码内容动态调整 swc 编译配置JSX 的编译行为由 src/services/jsx.ts 中的JSXService控制。它包裹了原有的swcOptions.compilationConfig并针对每个源码文件做两种判断当源码中包含jsx createElement注解时将jsc.transform.react.runtime设置为classic经典运行时由开发者显式提供createElement当源码中存在from rax或require(rax)的导入语句时将importSource设置为rax-compat/runtime自动 JSX 运行时从该模块获取jsx/jsxs等函数与 React 18 保持一致。判断依据分别是source.indexOf(jsx createElement)和正则/(from|require\()\s*[]rax[]/。由于配置是函数式的、逐文件执行的因此同一项目中不同文件的 JSX 编译策略可以不同实现了按源码形态的精细切换。4. 样式inlineStyle 模式下的行内样式处理当inlineStyle启用时StyleServicesrc/services/styles/index.ts会按顺序挂载三个处理环节JSX 转换、客户端Webpack处理、服务端esbuild处理。第一步JSXClassNameTransformer 改写 classNamebabel-plugin-transform-jsx-stylesheet 接入配置了retainClassName: true与forceEnableCSS: true会把源码中的静态 className 字符串改写为 style 引用// 转换前 div classNameheader / // 转换后 div style{styleSheet.header} /需要特别留意三个限制条件原文档明确强调只有项目源码内的代码才会被转换node_modules中的代码一律跳过转换器入口直接returnclassName{xxx}这类表达式写法不会被转换转换器只处理静态字符串字面量import ./x.module.css这类仅引入样式的写法不会被转换模块引入不等于 className 使用。此外转换器只处理.jsx?/.tsx?/.mjs后缀的文件TypeScript 文件会额外注入typescript与decorators-legacy解析插件是否转换同样经过checkInlineStyleEnable过滤即遵循inlineStyle的函数式作用域控制。第二步ClientSide——覆盖 Webpack Ruleset客户端侧插件通过configureWebpack注入处理器见 applyClientSideProcessor.ts为每种样式类型css/less/sass/scss重新组织 Webpack 规则为oneOf结构命中内联样式的文件交由stylesheet-loader处理编译为导出 styleSheet 对象的 JS 模块非 css 文件会先经过预处理器less-loader、sass-loader编译其中 less 开启了javascriptEnabled: true其余文件保持原本的处理逻辑即打入额外的 CSS 文件。oneOf内部根据两个正则判断归属当cssModule启用默认时*.module.css与*.global.css走常规样式 loader当cssModule禁用时只有*.global.css走常规 loader.module.*文件也交由 stylesheet-loader 内联处理。判断函数如下简化自源码const commonStyleResourceMatcher new RegExp( options.cssModule ? (\\.module|global)\\.${styleKind}$ : (\\.global)\\.${styleKind}$, i, ); const useCommonStyleLoader commonStyleResourceMatcher.test(id) || !inlineStyleEnabled;原文档还提示了两个限制在--speedup模式下该逻辑无法生效禁用cssModule后.module.css(less/...)文件也会被 stylesheet-loader 处理。第三步ServerSide——esbuild 处理在 SSR/SSG 场景下服务端构建由 esbuild 完成。插件会向服务端构建配置注入名为esbuild-inline-style的 onLoad 插件见 applyServerSideProcessor.ts对命中内联样式的.css/.sass/.scss/.less文件执行样式到 styleSheet 的转换并把文件内容类型改为 JSloader: js从而让服务端代码也能以 JS 模块方式引用样式对象。该处理仅当userConfig.ssr或userConfig.ssg开启时生效注入时会移除esbuild-empty-css插件并依据cssModule决定在esbuild-css-modules插件之后还是原位插入。样式到 styleSheet 的核心转换无论客户端还是服务端样式转换的最终实现都汇聚在 src/lib/transform-styles.ts 的styleSheetLoader中。它的处理管线是less/sass/scss 预处理 → postcss 插件rpx2vwunitPrecision: 4将 rpx 单位换算为 vw→css.parse解析样式表 → 逐规则转换为 styleSheet 对象并额外处理伪类className:active合并为classNameActive键、media媒体查询运行时通过window.matchMedia动态合并、font-face通过FontFaceAPI 注册以及prefers-color-scheme主题等场景。这就是classNamexxx最终能映射为style{styleSheet.xxx}的底层原因。实战验证示例工程与集成测试仓库提供了两个直接相关的示例工程与对应的集成测试可用于验证插件行为examples/rax-project基础 rax 项目迁移示例ice.config.mts中以默认选项注册插件页面源码可直接使用rax、rax-view、rax-text等模块examples/rax-inline-style行内样式示例ice.config.mts中启用inlineStyle: true并配置server.bundle与server.format: cjs以支撑 SSR 验证页面 src/pages/index.jsx 中既使用classNamehomeContainer的静态 className也使用 CSS Module 的import styles from ./index.module.less写法还引入了来自 node_modules 的组件覆盖了多种边界场景。集成测试 tests/integration/rax-inline-style.test.ts 对 build 与 devServer 两种模式分别断言了四个关键结果可作为迁移正确性的验收标准img元素保留class属性来自 CSS Module 的className{styles[logo]}未被转换span元素保留class属性CSS Module 场景未被转换span元素的style包含display:block来自 node_modules 组件的内联 CSS说明行内样式对依赖包同样生效span元素的style包含color:rgb(85,85,85)来自项目源码index.css的静态 className说明classNamexxx被成功转换为内联 style。这些断言与 README 中“只有项目源码中classNamexxx写法才会被转换”的说明相互印证CSS Module 的表达式写法与 class 保留共存静态 className 则被内联。使用注意事项与限制汇总综合原文档与源码使用该插件时需要注意以下事项inlineStyle建议按需开启全量启用会输出警告推荐使用函数式写法inlineStyle: (id) ...限定到具体模块如按目录或文件名匹配插件内部会将该函数应用到每个源文件与样式文件转换边界只有项目源码、只有静态字符串classNamexxx写法会被转换为style{styleSheet.xxx}className{styles.xxx}CSS Module、className{xxx}、import ./x.module.css均不会转换node_modules代码也不会转换--speedup限制客户端样式规则覆盖在--speedup模式下无法生效cssModule与内联的取舍仅在确有需要时关闭cssModule此时.module.*文件也会被内联官方标注为不推荐legacy仅用于 v0.6.x启用后rax会映射到生成的rax-compat-legacy-exports.ts以获得Rax.createContext()这类命名空间 API 与PropTypes导出新代码应使用 v1.0 的具名/命名空间导入方式SSR/SSG服务端内联样式处理仅在开启ssr或ssg时生效且会移除esbuild-empty-css插件、强制开启 tree shaking。如需深入插件实现可以继续阅读 packages/plugin-rax-compat/src/index.ts插件入口与选项归一化、src/services/alias.ts别名注册、src/services/jsx.tsswc 配置、src/services/styles/applyClientSideProcessor.tsWebpack 规则覆盖以及 src/lib/transform-styles.tsstyleSheet 转换核心。赞分享前端Web框架SSR前端构建插件系统微前端跨平台【免费下载链接】ice ice.js: The Progressive App Framework Based On React基于 React 的渐进式应用框架项目地址https://gitcode.com/gh_mirrors/ice1/ice点击查看免费下载相关推荐在 ice.js 中平滑迁移 rax-app 项目ice/plugin-rax-compat 兼容插件全解析在 ice.js 中平滑迁移 rax app 项目ice/plugin rax compat 兼容插件全解析 导读 ice/plugin rax comp前端Web框架SSR前端构建插件系统微前端跨平台ice.js 的 Rax 兼容层rax-compat 运行时 polyfill 原理与迁移实践ice.js 的 Rax 兼容层rax compat 运行时 polyfill 原理与迁移实践 rax compat 是 ice.js 生态中用于以 Rax前端Web框架SSR前端构建插件系统微前端跨平台rax-compat 运行时兼容层让 Rax 代码跑在真实 React 18 之上ice.js 渐进式框架实践rax compat 运行时兼容层让 Rax 代码跑在真实 React 18 之上ice.js 渐进式框架实践 rax compat 是 ice.js 仓前端Web框架SSR前端构建插件系统微前端跨平台上一篇foobox-cn重构foobar2000默认用户界面的模块化皮肤配置方案下一篇如何快速上手Restyaboard从零开始的完整入门指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考