Chakra UI Panda CSS 项目开发指南

Chakra UI Panda CSS 项目开发指南

panda 🐼 Universal, Type-Safe, CSS-in-JS Framework for Product Teams ⚡️ 项目地址: https://gitcode.com/gh_mirrors/pa/panda

项目概述

Chakra UI Panda CSS 是一个现代化的 CSS-in-JS 解决方案，采用 TypeScript 构建，专注于开发者体验和性能优化。该项目采用 monorepo 架构组织代码，包含多个功能模块，共同构成了完整的 CSS 工具链。

开发环境搭建

前置准备

在开始开发前，需要确保本地环境已安装以下工具：

• Node.js (建议使用最新 LTS 版本)
• pnpm (高性能的包管理工具)

项目初始化步骤

1. 获取项目源代码
2. 进入项目目录
3. 执行 pnpm install 安装所有依赖项

如果安装过程中遇到问题，建议检查 Node.js 和 pnpm 版本是否符合要求。

项目结构解析

Panda CSS 采用模块化设计，主要功能分布在以下核心包中：

| 模块名称 | 功能描述 | |---------------------|--------------------------------------------------------------------------| | cli | 提供命令行接口，用户通过该包与 Panda CSS 交互 | | core | 包含核心功能如工具类(utility)、配方(recipes)等基础能力 | | config | 处理 Panda 配置文件的读取和合并逻辑 | | extractor | 实现快速 AST 解析和代码扫描功能 | | generator | 负责代码生成工作，输出 JS、CSS 和 JSX 等产物 | | parser | 源代码解析器，处理输入文件的解析工作 | | is-valid-prop | 提供 CSS 属性有效性验证功能 | | node | 提供 Node.js 环境下的 API 接口 | | token-dictionary | 处理设计令牌(token)和语义令牌的转换与管理 | | shared | 包含项目共享的 TypeScript 类型和工具函数 |

开发工具链

Panda CSS 采用现代化的开发工具组合：

1. 包管理：使用 pnpm 管理依赖，利用其高效的依赖解析和磁盘空间优化特性
2. 构建工具：采用 tsup 进行模块打包，支持 TypeScript 和 ES Modules
3. 测试框架：基于 Vitest 实现单元测试，主要使用快照测试确保功能稳定性
4. 版本管理：集成 Changeset 进行变更记录、生成变更日志和管理版本发布

常用开发命令

• pnpm dev：启动开发模式，监控所有包的变更并实时构建
• pnpm build：执行完整构建流程，生成所有包的生产版本
• pnpm test：运行测试套件，验证功能正确性
• pnpm release：发布变更的包到 npm 仓库

问题报告规范

当发现潜在 bug 时，建议按照以下规范提交问题报告：

1. 提供清晰的重现路径
2. 包含最小化重现示例
3. 描述预期行为和实际行为的差异
4. 说明环境信息（操作系统、Node.js 版本等）

功能建议指南

对于新功能或 API 变更建议，应当：

1. 提供详细的背景说明和使用场景
2. 包含示例代码展示 API 设计
3. 说明与现有功能的兼容性考虑
4. 讨论可能的替代方案

代码提交规范

Panda CSS 采用约定式提交(Conventional Commits)，提交消息格式为：

类型(作用域): 描述

常用提交类型包括：

• feat：新增功能
• fix：错误修复
• refactor：代码重构
• docs：文档更新
• build：构建系统变更
• test：测试相关变更
• ci：持续集成配置
• chore：其他杂项变更

分支管理策略

1. 从主分支(main)创建新分支
2. 分支命名遵循 类型/作用域 格式，例如：
   • fix/button-style
   • feat/theme-extend
   • docs/quick-start

变更记录管理

使用 Changeset 工具管理变更记录：

1. 开发完成后运行 pnpm changeset 生成变更描述
2. 变更描述将用于生成发布时的变更日志
3. 对于文档或配置等次要变更，可使用 pnpm changeset add --empty 创建空变更记录

测试要求

所有功能修改和错误修复都应包含相应的测试用例：

1. 新增功能需提供验证测试
2. Bug 修复需包含重现问题的测试用例
3. 优先考虑使用快照测试验证输出结果

文档贡献

Panda CSS 文档网站位于项目 monorepo 中，文档改进包括：

1. 修正现有文档错误
2. 补充使用示例
3. 添加高级用法指南
4. 完善 API 参考说明

通过遵循这些指南，开发者可以高效地为 Panda CSS 项目做出贡献，同时保持代码库的一致性和可维护性。

panda 🐼 Universal, Type-Safe, CSS-in-JS Framework for Product Teams ⚡️ 项目地址: https://gitcode.com/gh_mirrors/pa/panda