Apache Airflow React 插件模板完整开发指南从库构建到动态加载集成【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow导读本文基于 Apache Airflow 仓库中官方提供的 React 插件模板dev/react-plugin-tools/react_plugin_template/README.md系统讲解如何在 Airflow 生态中开发可被 Core UI 动态加载的 React 插件。你将掌握模板的库构建模式、pnpm开发脚本、Vite 外部依赖配置、TypeScript 声明文件生成、主题继承机制以及通过fastapi_apps插件把构建产物部署到 Airflow API Server 的完整实战方案。模板定位作为库组件构建的 React 插件该模板的核心理念是插件以库library而非应用application的形式构建构建产物可被其他应用尤其是 Airflow Core UI动态导入消费。这意味着插件开发需要遵循宿主应用Host Application的共享约定与 Airflow 主应用共享同一个 React 实例避免重复打包导致 Hooks 状态冲突遵循 Airflow UI 的开发模式与规范Chakra 主题、语义化 token携带完整的 TypeScript 配置与构建设置产出可被类型系统消费的声明文件。模板完整源码位于 dev/react-plugin-tools/react_plugin_template/入口组件在 src/main.tsx开发调试入口在 src/dev.tsx构建配置在 vite.config.ts包元数据在 package.json。快速创建新插件项目bootstrap CLI与其手工拷贝模板官方提供了脚手架工具 bootstrap.py。从 dev/react-plugin-tools/README.md 可知其用法# 在 dev/react-plugin-tools 目录下执行 python bootstrap.py my-awesome-plugin # 或指定自定义目录 python bootstrap.py my-awesome-plugin --dir /path/to/my-projects/my-awesome-pluginbootstrap.py会询问是否包含 AI Agent 编码规则回答y会在生成项目中加入ai-agent-rules/目录含 airflow-plugin.md 等规则文件并自动把模板中的{{PROJECT_NAME}}占位符替换为实际项目名、按文件类型移除 Apache License 头源码见 bootstrap.py。可用脚本模板自带的开发与质量工具链模板在 package.json 中预置了完整脚本脚本命令作用devvite --port 5173 --strictPort启动带热更新的开发服务器固定 5173 端口被占用即报错buildvite build构建生产环境库产物build:typestsc --p tsconfig.lib.json仅生成 TypeScript 声明文件build:libvite build仅构建 JavaScript 库testvitest run运行单元测试coveragevitest run --coverage运行测试并生成覆盖率linteslint --quiet tsc --p tsconfig.app.json静态检查代码质量与类型lint:fixeslint --fix tsc --p tsconfig.app.json自动修复可修复的 lint 问题formatpnpm prettier --write .格式化全部代码previewvite preview本地预览构建产物环境约束package.json声明engines: { node: 22 }包管理器固定为pnpm10.28.1packageManager字段。依赖方面使用 React 19、Chakra UI 3、Vite 8并以vitejs/plugin-react-swc提供 SWC 加速的 React 编译。库构建输出一次构建多端消费执行pnpm build后模板在dist/目录产出dist/main.js—— ES module 格式的 JavaScript 库dist/main.d.ts—— TypeScript 声明文件由vite-plugin-dts从src/main.tsx提取生成Source maps —— 供调试定位源码。构建后其他应用即可按库方式导入组件import { PluginComponent } from your-plugin-name; // 在 React 应用中使用 PluginComponent /构建配置源码剖析vite.config.ts模板的库构建行为全部集中在 vite.config.ts核心配置如下build: isLibraryBuild ? { chunkSizeWarningLimit: 1600, lib: { entry: resolve(src, main.tsx), // 库入口 fileName: main, formats: [umd], // UMD 格式便于全局加载 name: AirflowPlugin, // 全局命名 }, rollupOptions: { external: [react, react-dom, react-router-dom, react/jsx-runtime], output: { globals: { react: React, react-dom: ReactDOM, react-router-dom: ReactRouterDOM, react/jsx-runtime: ReactJSXRuntime, }, }, }, } : { chunkSizeWarningLimit: 1600 },要点逐条对应源码UMD 格式 AirflowPlugin全局名formats: [umd]、name: AirflowPlugin使产物在宿主环境可通过全局变量访问外部依赖externalReact、React DOM、React Router、JSX runtime 均标记为 external不打包进产物运行时由宿主应用以globals中声明的全局变量React、ReactDOM等提供这是避免多实例冲突的关键CSS 注入cssInjectedByJsPlugin()把样式自动注入 JS bundle宿主无需额外加载 CSS 文件类型声明仅库构建时启用dts({ include: [src/main.tsx], insertTypesEntry: true, outDir: dist })浏览器兼容定义define中把global映射为globalThis、process.env置空测试配置vitest使用happy-dom环境、globals: true、passWithNoTests: true并挂载 testsSetup.ts。开发服务器则开启cors: true注释明确Only used by the dev server并设置base: ./便于相对路径加载。开发模式与主题继承机制pnpm dev启动开发服务器后在5173 端口运行通过 src/dev.tsx 入口加载组件createRoot(...).render(StrictModePluginComponent //StrictMode)启用热模块替换HMR改代码即时生效。主题处理是模板最具实用价值的细节本地开发使用默认 Chakra 主题而插件被加载进 Airflow Core UI 后继承主应用主题保证视觉一致。实现见 src/main.tsxconst PluginComponent (props: PluginComponentProps) { // 优先使用 Airflow Core UI 注入的全局 Chakra 主题系统 const system (globalThis.ChakraUISystem) ?? localSystem; return ( ChakraProvider value{system} ColorModeProvider HomePage / /ColorModeProvider /ChakraProvider ); };配套文件src/theme.ts 定义本地回退主题localSystem createSystem(defaultConfig)src/context/colorMode/ColorModeProvider.tsx 基于next-themes提供明暗模式切换attributeclass示例页面 src/pages/HomePage.tsx 展示了如何使用bg.subtle、fg、fg.muted等 Chakra 语义 token 而非硬编码颜色。包配置package.json 的库发布字段模板的 package.json 已按 npm 库规范配置好发布字段{ main: ./dist/main.js, module: ./dist/main.js, types: ./dist/main.d.ts, exports: { .: { import: ./dist/main.js, types: ./dist/main.d.ts } }, files: [dist] }main/module—— CommonJS 与 ES module 的入口指向types—— 指向生成的声明文件消费端获得完整类型提示exports—— 提供现代 import/export 支持与子路径封装files—— 仅发布dist避免把源码与配置文件带上 npm 包。自定义插件三个高频改造点模板 README 明确指出三个最常改动的位置组件 Props在 src/main.tsx 的PluginComponentProps接口中声明插件需要的参数外部依赖修改 vite.config.ts 的external数组——凡是宿主Airflow UI已提供、插件需共享的依赖都应加入构建输出调整 vite.config.ts 的lib配置入口、文件名、格式、全局名。升级依赖的注意事项升级被标记为 external 的依赖React 等与宿主共享的依赖需格外谨慎它们与宿主应用共享若版本跨度超出宿主兼容范围可能导致 Hooks 行为异常或路由失效。升级前应验证与宿主应用的兼容性。相关约定在 ai-agent-rules/airflow-plugin.md 中也有强调这些依赖are shared with the Airflow host application and bundling another copy can break hooks or routing。最佳实践清单综合模板 README 与 ai-agent-rules/airflow-plugin.md开发 Airflow React 插件应遵循保持 React 外部化始终把 React 生态标记为 external避免与宿主产生双实例冲突统一全局命名使用标准全局名AirflowPlugin除非宿主集成方式变更错误处理实现恰当的 Error Boundary 与降级回退完整类型为插件 props 与导出提供严格 TypeScript 类型控制包体积监控 bundle 大小对大型依赖考虑外部化主题一致性使用 Chakra 组件与语义 token避免绕过 Airflow 继承主题的裸样式公共接口优先通过 Airflow 公开的插件与 REST API 集成不要依赖不遵循 SemVer 的内部 UI API实验性接口预期将 React 插件接口视为实验性升级共享依赖时主动验证兼容性。故障排查常见问题与解法模板 README 列出了四个高频报错均为外部依赖与加载环境问题Failed to resolve module specifier react确保 React 已在 vite.config.ts 中标记为 external确认宿主应用在全局暴露了 React对应globals.react React。Cannot read properties of null (reading useState)典型的 React 实例不匹配——检查 external 配置确认宿主应用中全局 React 正确设置插件与宿主使用同一份 React。Objects are not valid as a React child确保返回的是组件函数而非 JSX 元素检查懒加载是否返回了正确的组件结构。MIME type 报错确保静态服务器以正确的 MIME type 提供.js与.cjs文件text/javascript。部署到 Airflow从构建到插件接入开发完成后部署路径为执行pnpm build生成dist/产物将dist/目录内容托管在自有基础设施上或托管在 Airflow 内部——通过注册fastapi_apps插件为 API Server 添加静态文件服务。fastapi_apps是 Airflow 插件体系中的一等字段在 airflow-core/src/airflow/api_fastapi/core_api/datamodels/plugins.py 的插件数据模型中定义了fastapi_apps: list[FastAPIAppResponse]并在生成的 OpenAPI 规范v2-rest-api-generated.yaml中对应fastapi_apps字段用于声明插件自带的 FastAPI 应用含静态文件挂载。即注册一个返回 FastAPI 应用的fastapi_apps插件在其上挂载静态文件路由指向distAirflow API Server 即可对外提供插件的 JS 产物供 Core UI 动态导入加载。插件的具体集成方式可查阅仓库中 Airflow 的插件文档与 plugins_manager 相关实现注意插件集成应走公开的插件与 REST API 面而非仅供 Core UI 使用的内部接口。结语这套模板把 Airflow 插件开发的标准答案固化成了可复制的工程结构库式构建、依赖外部化、类型产物、主题继承、静态托管部署一应俱全。无论是编写一个自定义页面组件还是为 Airflow UI 扩展业务面板都可以从 bootstrap.py 一键起步再按本文的配置要点完成定制与部署。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Apache Airflow React 插件模板完整开发指南从库构建到动态加载集成【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow导读本文基于 Apache Airflow 仓库中官方提供的 React 插件模板dev/react-plugin-tools/react_plugin_template/README.md系统讲解如何在 Airflow 生态中开发可被 Core UI 动态加载的 React 插件。你将掌握模板的库构建模式、pnpm开发脚本、Vite 外部依赖配置、TypeScript 声明文件生成、主题继承机制以及通过fastapi_apps插件把构建产物部署到 Airflow API Server 的完整实战方案。模板定位作为库组件构建的 React 插件该模板的核心理念是插件以库library而非应用application的形式构建构建产物可被其他应用尤其是 Airflow Core UI动态导入消费。这意味着插件开发需要遵循宿主应用Host Application的共享约定与 Airflow 主应用共享同一个 React 实例避免重复打包导致 Hooks 状态冲突遵循 Airflow UI 的开发模式与规范Chakra 主题、语义化 token携带完整的 TypeScript 配置与构建设置产出可被类型系统消费的声明文件。模板完整源码位于 dev/react-plugin-tools/react_plugin_template/入口组件在 src/main.tsx开发调试入口在 src/dev.tsx构建配置在 vite.config.ts包元数据在 package.json。快速创建新插件项目bootstrap CLI与其手工拷贝模板官方提供了脚手架工具 bootstrap.py。从 dev/react-plugin-tools/README.md 可知其用法# 在 dev/react-plugin-tools 目录下执行 python bootstrap.py my-awesome-plugin # 或指定自定义目录 python bootstrap.py my-awesome-plugin --dir /path/to/my-projects/my-awesome-pluginbootstrap.py会询问是否包含 AI Agent 编码规则回答y会在生成项目中加入ai-agent-rules/目录含 airflow-plugin.md 等规则文件并自动把模板中的{{PROJECT_NAME}}占位符替换为实际项目名、按文件类型移除 Apache License 头源码见 bootstrap.py。可用脚本模板自带的开发与质量工具链模板在 package.json 中预置了完整脚本脚本命令作用devvite --port 5173 --strictPort启动带热更新的开发服务器固定 5173 端口被占用即报错buildvite build构建生产环境库产物build:typestsc --p tsconfig.lib.json仅生成 TypeScript 声明文件build:libvite build仅构建 JavaScript 库testvitest run运行单元测试coveragevitest run --coverage运行测试并生成覆盖率linteslint --quiet tsc --p tsconfig.app.json静态检查代码质量与类型lint:fixeslint --fix tsc --p tsconfig.app.json自动修复可修复的 lint 问题formatpnpm prettier --write .格式化全部代码previewvite preview本地预览构建产物环境约束package.json声明engines: { node: 22 }包管理器固定为pnpm10.28.1packageManager字段。依赖方面使用 React 19、Chakra UI 3、Vite 8并以vitejs/plugin-react-swc提供 SWC 加速的 React 编译。库构建输出一次构建多端消费执行pnpm build后模板在dist/目录产出dist/main.js—— ES module 格式的 JavaScript 库dist/main.d.ts—— TypeScript 声明文件由vite-plugin-dts从src/main.tsx提取生成Source maps —— 供调试定位源码。构建后其他应用即可按库方式导入组件import { PluginComponent } from your-plugin-name; // 在 React 应用中使用 PluginComponent /构建配置源码剖析vite.config.ts模板的库构建行为全部集中在 vite.config.ts核心配置如下build: isLibraryBuild ? { chunkSizeWarningLimit: 1600, lib: { entry: resolve(src, main.tsx), // 库入口 fileName: main, formats: [umd], // UMD 格式便于全局加载 name: AirflowPlugin, // 全局命名 }, rollupOptions: { external: [react, react-dom, react-router-dom, react/jsx-runtime], output: { globals: { react: React, react-dom: ReactDOM, react-router-dom: ReactRouterDOM, react/jsx-runtime: ReactJSXRuntime, }, }, }, } : { chunkSizeWarningLimit: 1600 },要点逐条对应源码UMD 格式 AirflowPlugin全局名formats: [umd]、name: AirflowPlugin使产物在宿主环境可通过全局变量访问外部依赖externalReact、React DOM、React Router、JSX runtime 均标记为 external不打包进产物运行时由宿主应用以globals中声明的全局变量React、ReactDOM等提供这是避免多实例冲突的关键CSS 注入cssInjectedByJsPlugin()把样式自动注入 JS bundle宿主无需额外加载 CSS 文件类型声明仅库构建时启用dts({ include: [src/main.tsx], insertTypesEntry: true, outDir: dist })浏览器兼容定义define中把global映射为globalThis、process.env置空测试配置vitest使用happy-dom环境、globals: true、passWithNoTests: true并挂载 testsSetup.ts。开发服务器则开启cors: true注释明确Only used by the dev server并设置base: ./便于相对路径加载。开发模式与主题继承机制pnpm dev启动开发服务器后在5173 端口运行通过 src/dev.tsx 入口加载组件createRoot(...).render(StrictModePluginComponent //StrictMode)启用热模块替换HMR改代码即时生效。主题处理是模板最具实用价值的细节本地开发使用默认 Chakra 主题而插件被加载进 Airflow Core UI 后继承主应用主题保证视觉一致。实现见 src/main.tsxconst PluginComponent (props: PluginComponentProps) { // 优先使用 Airflow Core UI 注入的全局 Chakra 主题系统 const system (globalThis.ChakraUISystem) ?? localSystem; return ( ChakraProvider value{system} ColorModeProvider HomePage / /ColorModeProvider /ChakraProvider ); };配套文件src/theme.ts 定义本地回退主题localSystem createSystem(defaultConfig)src/context/colorMode/ColorModeProvider.tsx 基于next-themes提供明暗模式切换attributeclass示例页面 src/pages/HomePage.tsx 展示了如何使用bg.subtle、fg、fg.muted等 Chakra 语义 token 而非硬编码颜色。包配置package.json 的库发布字段模板的 package.json 已按 npm 库规范配置好发布字段{ main: ./dist/main.js, module: ./dist/main.js, types: ./dist/main.d.ts, exports: { .: { import: ./dist/main.js, types: ./dist/main.d.ts } }, files: [dist] }main/module—— CommonJS 与 ES module 的入口指向types—— 指向生成的声明文件消费端获得完整类型提示exports—— 提供现代 import/export 支持与子路径封装files—— 仅发布dist避免把源码与配置文件带上 npm 包。自定义插件三个高频改造点模板 README 明确指出三个最常改动的位置组件 Props在 src/main.tsx 的PluginComponentProps接口中声明插件需要的参数外部依赖修改 vite.config.ts 的external数组——凡是宿主Airflow UI已提供、插件需共享的依赖都应加入构建输出调整 vite.config.ts 的lib配置入口、文件名、格式、全局名。升级依赖的注意事项升级被标记为 external 的依赖React 等与宿主共享的依赖需格外谨慎它们与宿主应用共享若版本跨度超出宿主兼容范围可能导致 Hooks 行为异常或路由失效。升级前应验证与宿主应用的兼容性。相关约定在 ai-agent-rules/airflow-plugin.md 中也有强调这些依赖are shared with the Airflow host application and bundling another copy can break hooks or routing。最佳实践清单综合模板 README 与 ai-agent-rules/airflow-plugin.md开发 Airflow React 插件应遵循保持 React 外部化始终把 React 生态标记为 external避免与宿主产生双实例冲突统一全局命名使用标准全局名AirflowPlugin除非宿主集成方式变更错误处理实现恰当的 Error Boundary 与降级回退完整类型为插件 props 与导出提供严格 TypeScript 类型控制包体积监控 bundle 大小对大型依赖考虑外部化主题一致性使用 Chakra 组件与语义 token避免绕过 Airflow 继承主题的裸样式公共接口优先通过 Airflow 公开的插件与 REST API 集成不要依赖不遵循 SemVer 的内部 UI API实验性接口预期将 React 插件接口视为实验性升级共享依赖时主动验证兼容性。故障排查常见问题与解法模板 README 列出了四个高频报错均为外部依赖与加载环境问题Failed to resolve module specifier react确保 React 已在 vite.config.ts 中标记为 external确认宿主应用在全局暴露了 React对应globals.react React。Cannot read properties of null (reading useState)典型的 React 实例不匹配——检查 external 配置确认宿主应用中全局 React 正确设置插件与宿主使用同一份 React。Objects are not valid as a React child确保返回的是组件函数而非 JSX 元素检查懒加载是否返回了正确的组件结构。MIME type 报错确保静态服务器以正确的 MIME type 提供.js与.cjs文件text/javascript。部署到 Airflow从构建到插件接入开发完成后部署路径为执行pnpm build生成dist/产物将dist/目录内容托管在自有基础设施上或托管在 Airflow 内部——通过注册fastapi_apps插件为 API Server 添加静态文件服务。fastapi_apps是 Airflow 插件体系中的一等字段在 airflow-core/src/airflow/api_fastapi/core_api/datamodels/plugins.py 的插件数据模型中定义了fastapi_apps: list[FastAPIAppResponse]并在生成的 OpenAPI 规范v2-rest-api-generated.yaml中对应fastapi_apps字段用于声明插件自带的 FastAPI 应用含静态文件挂载。即注册一个返回 FastAPI 应用的fastapi_apps插件在其上挂载静态文件路由指向distAirflow API Server 即可对外提供插件的 JS 产物供 Core UI 动态导入加载。插件的具体集成方式可查阅仓库中 Airflow 的插件文档与 plugins_manager 相关实现注意插件集成应走公开的插件与 REST API 面而非仅供 Core UI 使用的内部接口。结语这套模板把 Airflow 插件开发的标准答案固化成了可复制的工程结构库式构建、依赖外部化、类型产物、主题继承、静态托管部署一应俱全。无论是编写一个自定义页面组件还是为 Airflow UI 扩展业务面板都可以从 bootstrap.py 一键起步再按本文的配置要点完成定制与部署。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
)
