StyleX PostCSS 插件 include/importSources 自动发现机制：基于 auto-discovery 测试夹具的源码级解析

前端【免费下载链接】stylexStyleX is the styling system for ambitious user interfaces.项目地址https://gitcode.com/gh_mirrors/st/stylex点击查看免费下载导读本篇文章围绕stylexjs/postcss-plugin中一个专门的测试夹具__auto_discovery_fixtures__展开系统讲解 StyleX PostCSS 插件如何在不显式配置的情况下自动发现需要编译的源码文件include与 StyleX 引入来源importSources。读完本文你将理解自动发现的完整解析链路、依赖目录的发现规则、配置优先级以及如何用STYLEX_POSTCSS_DEBUG1调试这一过程并能在自己的项目里正确配置或复用这套机制。一、夹具是什么一个为验证自动发现而生的最小包在 packages/stylexjs/postcss-plugin/tests/auto_discovery_fixtures/README.md 中对这个夹具的定位写得很明确This fixture package intentionally depends on a local package that uses StyleX. It is used to test include/importSources auto-discovery in the PostCSS plugin.也就是说这个夹具包故意依赖一个使用 StyleX 的本地依赖包专门用来测试 PostCSS 插件的include与importSources自动发现能力。它不是一个可运行的应用而是一套被测试代码在运行时动态组装的最小化场景它自身是一个使用 StyleX 的应用src/下有两个使用不同引入来源的源文件它的node_modules中既有使用 StyleX 的依赖stylex-custom-lib也有不使用 StyleX 的依赖non-stylex-lib用于验证自动发现能够精确区分二者它还包含一个藏在.cache目录下的隐藏 StyleX 文件用于验证自动排除规则。测试运行时会在临时目录中动态重建这套node_modules见下文第四节的createAutoDiscoveryFixture因此夹具本身不提交真实的node_modules只有声明依赖关系的package.json。夹具目录结构__auto_discovery_fixtures__/ ├── README.md # 夹具用途说明 ├── package.json # 声明对 stylex-custom-lib / non-stylex-lib 的依赖 ├── babel.config.js # Babel 配置启用 stylexjs/babel-plugin声明 react-strict-dom 为引入来源 └── src/ ├── local-stylex.js # 通过 stylexjs/stylex 定义样式color: red ├── local-rsd.js # 通过 react-strict-dom 定义样式color: purple └── types.d.ts # 类型声明文件默认被 **/*.d.ts 排除二、夹具内部结构逐文件拆解2.1 package.json故意制造依赖了 StyleX 的依赖这一场景夹具的 package.json 内容如下{ name: auto-discovery-fixture, private: true, dependencies: { stylex-custom-lib: 1.0.0, non-stylex-lib: 1.0.0 } }这两个依赖是测试的关键对照组依赖是否使用 StyleX作用stylex-custom-lib是内部从react-strict-dom引入css并调用css.create验证自动发现能识别出依赖了 StyleX 的依赖包并纳入编译non-stylex-lib否仅export const v 1验证自动发现不会把普通依赖误纳入编译注意stylex-custom-lib的实际实现index.js中使用react-strict-dom的css.create并不是提交在夹具里的文件而是由测试代码在createAutoDiscoveryFixture()中动态生成的见 index-test.js生成的代码片段为import { css } from react-strict-dom; export const styles css.create({ lib: { backgroundColor: orange, }, });2.2 babel.config.jsBabel 层的 importSources 声明夹具的 babel.config.js 配置了stylexjs/babel-plugin并把react-strict-dom声明为 StyleX 的引入来源module.exports { plugins: [ [ stylexjs/babel-plugin, { dev: false, runtimeInjection: false, importSources: [{ from: react-strict-dom, as: css }], }, ], ], };这里采用的是importSources的对象语法{ from: react-strict-dom, as: css }表示可以从react-strict-dom包中导入css这个命名导出并把该导出当作 StyleX API 使用。这正是 src/local-rsd.js 中的用法import { css } from react-strict-dom; export const styles css.create({ local: { color: purple, }, });而 src/local-stylex.js 走的是默认来源stylexjs/styleximport * as stylex from stylexjs/stylex; export const styles stylex.create({ local: { color: red, }, });这两个文件共同构成同一项目内存在多个 StyleX 引入来源的真实场景用来验证插件在解析importSources时不会遗漏react-strict-dom这种非默认来源。三、自动发现的底层实现discovery.js 的解析链路include与importSources的自动发现逻辑集中在 src/discovery.js整个解析过程是先定 importSources再定 include最后补 exclude的流水线。3.1 importSources 的四级解析优先级核心函数是resolveImportSourcesWithMetadatadiscovery.js它按以下优先级依次尝试命中即返回优先级来源标识source字段触发条件1postcss-option用户在插件选项中显式传入importSources数组2babel-config-inline用户通过babelConfig内联传入的插件列表里带有stylexjs/babel-plugin及其importSources3babel-config-resolved项目根目录的 Babel 配置文件如babel.config.js被解析后暴露出importSources4defaults以上均未命中回退到默认值默认值定义在 discovery.jsconst DEFAULT_IMPORT_SOURCES [stylexjs/stylex, stylex];需要特别注意的是当importSources是从 Babel 配置第 2、3 级推断出来时插件不会用推断值覆盖默认值而是做去重合并importSources: dedupe([...DEFAULT_IMPORT_SOURCES, ...inferredFromBabel]),也就是说即使你的 Babel 配置里只写了react-strict-dom默认的stylexjs/stylex、stylex也依然有效。反过来如果是第 1 级显式传入的importSources则完全以用户值为准——这正是测试prefers explicit importSources over inferred babel importSourcesindex-test.js验证的行为显式传入[stylexjs/stylex]后react-strict-dom来源不再生效color: purple与background-color: orange均不被产出。如何从 Babel 配置中识别 StyleX 插件isStylexBabelPluginNamediscovery.js支持多种插件引用形态字符串名stylexjs/babel-plugin、包含该名称的路径含 Windows 分隔符与 pnpm 的分隔形态、函数引用按函数名styleXTransform/stylexPluginWithOptions兜底匹配以及default包装对象。这是为了让夹具测试中的函数引用形态见infers importSources when StyleX Babel plugin is passed as a function referenceindex-test.js也能被正确识别。3.2 include 的自动发现默认 glob 依赖目录resolveIncludeWithMetadatadiscovery.js的逻辑分两条路径用户显式传入了include直接使用用户值去重不做任何依赖目录发现。这是刻意的设计——显式配置意味着用户已明确编译范围自动发现不应越俎代庖测试does not auto-discover dependency directories when include is explicitly provided验证了这一点见 index-test.js。未传入include使用默认 glob并把发现的 StyleX 依赖目录转成绝对路径 glob 追加进去const DEFAULT_INCLUDE_GLOB **/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts};include: dedupe([DEFAULT_INCLUDE_GLOB, ...discoveredDependencyGlobs]),discoveredDependencyGlobs由discoverStylexPackageDirectoriesdiscovery.js产出其发现规则分为两路扫描直接依赖读取cwd下package.json收集dependencies、devDependencies、peerDependencies、optionalDependencies中的直接依赖名getDirectDependenciesdiscovery.js对每个依赖解析其package.json用hasStylexDependencydiscovery.js判断其dependencies/peerDependencies/optionalDependencies中是否包含目标包即 importSources 推导出的包名 默认来源包名的并集。命中则该依赖目录被加入发现集合。从 importSources 反查包目录includePackageFromImportSourcediscovery.js针对每个非默认、非相对路径的 importSource例如react-strict-dom本身解析其包目录并加入发现集合。两条路径都会避免把项目根目录本身误加进去防止 monorepo 场景下的重复扫描并且目录会与cwd去重比较。在夹具场景下package.json的直接依赖是stylex-custom-lib与non-stylex-lib。前者内部依赖react-strict-dom它是 importSources 推导出的目标包命中hasStylexDependency于是stylex-custom-lib目录被纳入编译后者没有任何 StyleX 关联被正确跳过。3.3 exclude 的自动补充resolveExcludediscovery.js遵循同样的显式优先原则有显式include仅使用用户提供的exclude无显式include在用户exclude基础上自动追加AUTO_DISCOVERY_EXCLUDESdiscovery.js把发现范围聚焦到源码node_modules/**、**/node_modules/**、.git/**、.next/**、.nuxt/**、 .svelte-kit/**、.turbo/**、.cache/**、dist/**、build/**、coverage/**、tmp/**、temp/**此外plugin.js 还会无条件追加**/*.d.ts与**/*.flow类型声明文件不含任何 CSS 规则。这也是夹具中src/types.d.ts存在的意义之一它天然会被排除证明自动排除不会把类型声明当样式源。3.4 从发现到产出builder 与 bundler 的执行链自动发现只负责决定编译哪些文件真正执行编译的是 builder.js 与 bundler.jsbuilder.findStyleXAtRule(root)在 PostCSS 根节点中查找stylex无参数 at-rulebuilder.jsbuilder.getFiles()用fast-glob按 include/exclude 收集文件并将匹配到的文件/目录转成 PostCSS 的dir-dependency/dependency消息供 watch 模式监听builder.jsbundler.shouldTransform用源码字符串中是否包含 importSource做快速预筛bundler.js未命中的文件被跳过以加速编译bundler.transform通过babel/core执行转换收集metadata.stylex规则bundler.jsbundler.bundle调用stylexjs/babel-plugin的processStylexRules把所有规则合成一段 CSS替换掉stylexat-rulebundler.js。四、测试如何验证自动发现index-test.js 的用例设计夹具的测试入口是tests/index-test.js。createAutoDiscoveryFixtureindex-test.js会在系统临时目录创建独立副本并动态补齐node_modules/stylexjs/babel-plugin指向仓库内真实 babel-plugin 构建产物的桩node_modules/stylex-custom-lib使用react-strict-dom的 StyleX 依赖产出background-color: orangenode_modules/non-stylex-lib普通依赖export const v 1node_modules/.cache/hidden-stylex.js同样使用react-strict-dom的隐藏StyleX 文件产出background-color: hotpink用于验证.cache排除规则。围绕这套场景关键测试用例与断言如下测试用例关键断言验证点auto-discovers StyleX dependency directories and importSources from Babel configL357输出包含color:redstylexjs/stylex、color:purplereact-strict-dom、background-color:orangestylex-custom-lib且存在指向stylex-custom-lib的dir-dependency消息importSources 从 Babel 配置推断 依赖目录被自动发现 watch 依赖消息正确发出does not auto-discover dependency directories when include is explicitly providedL373显式include: [src/local-stylex.js]时只有color:red无orange显式 include 会完全关闭依赖目录自动发现infers importSources from resolved babel config when plugins are not passed inlineL389仅提供cwd、让插件自行解析项目 Babel 配置三种颜色全部产出支持从磁盘上的 Babel 配置文件解析 importSourcesprefers explicit importSources over inferred babel importSourcesL406显式importSources: [stylexjs/stylex]时只有color:red显式 importSources 优先级最高processes absolute include paths in node_modules even when node_modules is excludedL467绝对路径 include 指向stylex-custom-lib/index.js时仍产出orange绝对 include 可以覆盖 node_modules 排除keeps specific node_modules excludes when absolute includes point to node_modulesL491产出orange但不产出hotpink.cache下隐藏文件被排除通配排除与精确 include 的取舍这些用例共同印证了上一节的解析规则显式配置优先、默认值兜底、依赖发现仅在 include 缺省时生效、排除规则随是否显式而自动变化。五、在真实项目中配置从夹具到生产实践夹具验证的正是 stylexjs/postcss-plugin 的 README 中描述的配置行为。在真实项目中postcss.config.js的最小配置为// postcss.config.js module.exports { plugins: { stylexjs/postcss-plugin: { include: [src/**/*.{js,jsx,ts,tsx}], }, autoprefixer: {}, }, };关键选项一览默认值以仓库源码与 README 为准选项类型 / 默认值说明includestring[]默认自动发现需要编译的路径或 glob省略时自动发现cwd下源码与使用 StyleX 的直接依赖excludestring[]默认[]排除路径优先级高于 include自动发现模式下自动追加node_modules、.next、dist、build、.cache等默认排除cwdstring默认process.cwd()插件工作目录依赖解析与 Babel 配置解析都基于它babelConfigobject默认{}默认读取项目根babel.config.js自定义时建议babelrc: false并显式传入useCSSLayersboolean默认false开启后改用layer处理优先级替代默认的:not(#\#)方案importSourcesArraystring \| { from, as }默认[stylexjs/stylex, stylex]允许导入 StyleX 的来源省略时从 Babel 插件配置推断并合并默认值Babel 侧同样需要配套配置README 推荐import styleXPlugin from stylexjs/babel-plugin; const config { plugins: [ [ styleXPlugin, { runtimeInjection: false, // PostCSS 插件需要关闭运行时注入 dev: true, unstable_moduleResolution: { type: commonJS, // 或 haste rootDir: __dirname, // 项目根目录绝对路径 }, }, ], ], };随后在入口样式文件如src/stylex.css写入占位 at-rule 并在应用入口导入/* src/stylex.css */ stylex;// src/index.js import ./stylex.css;构建时stylex会被替换为实际生成的 CSS。当你不写include时插件会做与夹具测试完全相同的三件事用默认 glob 扫描源码 → 扫描package.json直接依赖中依赖了 StyleX 的包并把其目录加入编译范围 → 自动排除构建产物目录。这意味着像stylex-custom-lib这样内部用 StyleX 写的组件库无需任何额外配置即可被编译而non-stylex-lib这类普通依赖不会拖慢构建。调试自动发现STYLEX_POSTCSS_DEBUG当自动发现的结果不符合预期时设置环境变量即可打印完整解析细节plugin.js 与 plugin.jsSTYLEX_POSTCSS_DEBUG1 npm run build输出中包含对应测试logs discovery details in debug modeindex-test.jscwd插件工作目录importSourcesSourceimportSources 来自哪一级postcss-option/babel-config-inline/babel-config-resolved/defaultsimportSources最终生效的引入来源列表include与includeWasExplicit最终 include glob 及是否为显式传入discoveredDependencyDirectories自动发现的 StyleX 依赖目录exclude最终生效的排除规则含自动追加项。六、优先级与边界行为速查从夹具测试与源码可以归纳出以下确定性的行为规则importSources 优先级显式插件选项 内联 Babel 插件配置 解析磁盘 Babel 配置 默认值来自 Babel 的推断值会与默认值合并去重。include 优先级显式 include 直接生效并关闭依赖目录自动发现缺省时 默认源码 glob 自动发现的依赖目录绝对路径 glob。exclude 规则显式 include 时仅用用户 exclude自动发现模式自动补充构建/依赖目录排除**/*.d.ts、**/*.flow无条件排除。依赖发现口径只扫描直接依赖四个依赖字段且只纳入其依赖字段中出现目标 StyleX 包的依赖目录普通依赖被跳过。node_modules 特例绝对路径 include 可以显式命中node_modules下的文件.cache等目录即便在自动发现排除列表中也会因 include 与 exclude 的 glob 匹配差异被精确排除如hidden-stylex.js只产出 hotpink 与否完全由 exclude 精确度决定。调试手段STYLEX_POSTCSS_DEBUG1输出Auto-discovery details是排查为什么某个文件没被编译的首选手段。结语__auto_discovery_fixtures__虽然只是两行说明加少量夹具文件但它精确刻画了stylexjs/postcss-plugin自动发现能力的完整边界include 缺省时的依赖目录发现、importSources 的多级推断与合并、显式配置对自动发现的覆盖以及排除规则的联动变化。结合 discovery.js 的解析实现与 index-test.js 的用例验证读者既可以理解开箱即用背后的设计取舍也能在遇到构建遗漏时快速定位问题——这正是这套夹具存在的价值。赞分享前端【免费下载链接】stylexStyleX is the styling system for ambitious user interfaces.项目地址https://gitcode.com/gh_mirrors/st/stylex点击查看免费下载相关推荐IPBan深度剖析构建企业级服务器安全防护的智能解决方案IPBan深度剖析构建企业级服务器安全防护的智能解决方案 在当今数字化时代服务器安全已成为企业IT基础设施的基石。面对日益复杂的网络攻击特别是暴力破解、僵CMS前端后端GraphQLTeleport GCP 自动发现Auto-Discovery与 GCP 节点加入机制深度解析Teleport GCP 自动发现Auto Discovery与 GCP 节点加入机制深度解析 本文基于 rfd/0113 gcp server disco网络安全认证鉴权运维后端Angular CLI ng update 包组packageGroup机制解析基于 update 测试夹具的升级阶梯与源码验证Angular CLI ng update 包组packageGroup机制解析基于 update 测试夹具的升级阶梯与源码验证 导读 ng updateCLI开发工具前端构建构建工具代码生成前端上一篇Authelia 集成 GLAuth LDAP 认证后端配置、默认值与过滤器实战指南下一篇BloodHound CE 内网侦察 API 实战指南Python 驱动、Cypher 攻击路径查询与自动化采集创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考