react-bits

react-bits

版本 1.0.0
DavidHDev/react-bits
2026 年 1 月

注意：
本技能提供关于集成、定制和贡献 react-bits 的指导——这是规模最大、创意最丰富的动画 React 组件库。
内容涵盖 Vite 4/5/6、Tailwind CSS v4、Three.js/Fiber、GSAP 和 Framer Motion 集成。

---

何时使用此技能

• 需要将富有创意的动画 React 组件（文本动画、背景效果、交互式 UI 元素）集成到 React/Next.js 项目时。
• 需要定制或调试现有的 react-bits 组件（例如调整 GSAP 时间线、Three.js 画布配置或 Tailwind 类）时。
• 按照 feat/<feature-name> 分支约定，为 react-bits 仓库贡献新的动画组件时。

何时不使用此技能

• 处理标准的非动画 UI 组件时（请改用 Radix、Shadcn 或 Tailwind UI 等标准组件库）。
• 由于严格的包体积限制，目标项目无法支持体积较大的动画库（Three.js、GSAP、Framer Motion）时。

项目概况

• 技术栈：React、Vite、Tailwind CSS v4、GSAP、Three.js（@react-three/fiber、@react-three/drei）、Framer Motion（motion）、jsrepo（用于管理注册表）。
• 注册表：使用 jsrepo 构建和分发组件。
• 脚本：
  • npm run dev：并行运行 jsrepo build --watch 和 Vite 文档服务器。
  • npm run build：构建注册表、生成 LLMs 文本和站点地图，并构建 Vite 网站。
  • npm run new:component：使用 scripts/generateComponent.js 生成新的组件模板。
  • npm run lint：使用 ESLint 检查代码库。
  • npm run format：使用 Prettier 格式化代码库。

说明

步骤 1：集成和安装组件

1. 从 react-bits 目录中找到所需组件（例如，文本动画、背景、UI 组件）。
2. 在目标项目中安装所需的对等依赖（例如，根据组件需要安装 gsap、motion、@react-three/fiber、lucide-react）。
3. 复制组件源代码，或在目标项目已配置 jsrepo 的情况下使用它。

步骤 2：定制和性能优化

1. Tailwind CSS：确保已配置 Tailwind CSS（源仓库使用 Tailwind v4）。
2. GSAP 上下文：定制 GSAP 动画时，务必在 useLayoutEffect 中清理时间线和补间，或使用 @gsap/react 的 useGSAP hook，以防止内存泄漏以及在 React 18/19 Strict Mode 中重复触发。
3. Three.js 画布：确保 <Canvas> 组件尺寸设置正确，并在卸载时释放 WebGL 上下文。

步骤 3：贡献新组件

1. 运行 npm run new:component，生成新组件的脚手架。
2. 使用简洁的 React 模式，在 src/components/ 下实现组件。
3. 在本地文档服务器（npm run dev）中验证组件是否正常工作。
4. 提交前运行 npm run lint 和 npm run format。
5. 创建名为 feat/<feature-name> 的分支，并向 main 提交 PR。

最佳实践

• 清理 GSAP：卸载时务必清理 GSAP 时间线和补间，以防止内存泄漏。
• 自包含组件：确保组件不导入用户通过 jsrepo 安装组件时无法获取的内部工具。
• 分支命名：所有拉取请求均遵循 feat/<feature-name> 分支命名约定。

示例

示例 1：安全的 GSAP 动画组件

import { useRef } from 'react';
import gsap from 'gsap';
import { useGSAP } from '@gsap/react';

export default function AnimatedBox() {
  const container = useRef<HTMLDivElement>(null);

  useGSAP(() => {
    gsap.to('.box', { rotation: 360, duration: 2, repeat: -1, ease: 'linear' });
  }, { scope: container });

  return (
    <div ref={container}>
      <div className="box w-16 h-16 bg-blue-500 rounded" />
    </div>
  );
}

参考资料

文件	用途
package.json	项目依赖（GSAP、Three.js、Tailwind v4）和脚本
CONTRIBUTING.md	分支命名约定（feat/）和 PR 指南
jsrepo.config.ts	用于分发组件的注册表配置