Theatre.js 开发环境搭建与项目结构解析

Theatre.js 开发环境搭建与项目结构解析

前言

Theatre.js 是一个强大的 JavaScript 动画库，它提供了可视化编辑器，让开发者能够轻松创建复杂的动画效果。本文将深入解析 Theatre.js 的开发环境搭建流程和项目结构，帮助开发者快速上手项目开发。

开发环境准备

基础环境要求

在开始 Theatre.js 开发前，需要确保系统满足以下要求：

1. Node.js 14+：这是运行 JavaScript 的基础环境
2. Yarn 1.22+：项目使用 Yarn 作为包管理工具

可以通过以下命令检查当前环境版本：

node -v  # 检查 Node.js 版本
yarn -v  # 检查 Yarn 版本

项目初始化

获取项目代码后，需要执行以下步骤完成初始化：

yarn         # 安装所有依赖
yarn postinstall  # 执行后安装脚本

重要提示：

• 项目使用 Yarn Workspaces 管理多包结构，因此不能使用 npm install
• 项目采用 Yarn v2 特性，当你进入项目目录时，Yarn 会自动切换到 v2 模式

开发工作流

快速开发模式

playground 包是快速体验和修改 Theatre.js 的最佳入口：

cd ./packages/playground
yarn serve   # 启动开发服务器
yarn cli build  # 构建项目

或者使用快捷命令：

yarn playground  # 从项目根目录直接启动

playground 包含多个预设项目，非常适合快速测试和调试 Theatre.js 功能。

示例项目开发

examples/ 目录包含多个使用不同构建工具的示例项目：

1. 首先构建所有包：

yarn cli build

2. 然后进入具体示例目录运行：

cd examples/dom-cra
yarn start

这些示例展示了 Theatre.js 与 Parcel、Create React App 等工具的集成方式。

测试与质量保障

单元/集成测试

项目使用 Jest 作为测试框架，测试文件以 .test.ts 或 .test.tsx 结尾：

yarn test        # 运行所有测试
yarn test --watch  # 监控模式运行测试

端到端测试

端到端测试位于 playground 包中，用于验证完整功能流程。

类型检查

项目全面采用 TypeScript，提供完整的类型支持：

yarn typecheck        # 检查类型
yarn typecheck --watch  # 监控模式检查

对于 VSCode 用户，项目已配置好 TypeScript 监控任务，可直接在编辑器中使用。

代码规范检查

项目使用 ESLint 进行代码规范检查：

yarn lint:all        # 运行检查
yarn lint:all --fix  # 自动修复可修复的问题

项目发布

发布流程

所有包（除 @theatre/r3f 外）共享相同的版本号，发布命令如下：

yarn cli release x.y.z       # 发布正式版
yarn cli release x.y.z-dev.w  # 发布开发版
yarn cli release x.y.z-rc.w  # 发布候选版

项目结构解析

Theatre.js 采用 monorepo 结构，包含多个独立包：

1. 核心包：

   • @theatre/core：核心动画库
   • @theatre/studio：可视化编辑器
   • @theatre/dataverse：响应式数据流库

2. 框架集成：

   • @theatre/react：React 工具集
   • @theatre/r3f：react-three-fiber 扩展

3. 开发辅助：

   • playground：开发测试环境
   • examples：各种构建工具的示例项目

每个包可能包含 dotEnv/ 目录，存放开发相关配置文件。

常用命令汇总

| 命令 | 功能 | |------|------| | yarn playground | 启动 playground 开发服务器 | | yarn test | 运行所有测试 | | yarn typecheck | 类型检查 | | yarn lint:all | 代码规范检查 | | yarn cli build | 构建所有包 |

开发建议

1. 代码贡献方向：

   • 修复已知问题
   • 实现新功能
   • 完善文档
   • 创建新的示例项目

2. 开发流程建议：

   • 从标记为"Good first issue"的问题开始
   • 保持分支与主分支同步
   • 合并前进行充分的测试

3. 代码质量保障：

   • 确保通过所有测试
   • 保持类型定义完整
   • 遵循代码规范

通过本文的介绍，开发者应该能够快速搭建 Theatre.js 的开发环境，理解项目结构，并开始参与项目开发。Theatre.js 作为一个功能强大的动画库，其开发模式也体现了现代 JavaScript 项目的最佳实践。