CLI

CLI 原地修改你的组件，不复制任何东西：把 import 的 primitive 换成@animate-ui/react 中带动效的版本，并删除 Motion 已经取代的 CSS 动画。需要 Node.js 22.12 或更高版本。

animate

处理项目里已安装的 shadcn/ui 组件。可以全部处理、点名处理，或用 --exclude 排除。

Usage: animate-ui animate <components...|all> [options]

Arguments:
  components      the components to animate (their file names in your ui
                  folder), or all

Options:
  --cwd <path>    the project directory (default: the current directory)
  --dry-run       show the changes without writing them
  --exclude <components...>
                  leave these components out: comma-separated
  --exclude sidebar,tooltip
  -h, --help      show the help

它改了什么

animate 通过 components.json 的 ui 别名（结合tsconfig.json 的 paths）定位组件，然后修改两处，Tailwind CSS 3 上是三处：

1. import 来源。它会模仿你原来的 import 风格，所以使用这些 import 的代码不需要改：

import { Dialog as DialogPrimitive } from 'radix-ui';
import { Dialog as DialogPrimitive } from '@animate-ui/react/primitives/radix-ui';

伞形入口会重新导出库里其余内容，所以混合了动画与非动画部分的 import（例如 { Dialog, Slot }）仍然可用；没有可动画内容的 import 保持不动。

2. CSS 动画。保留下来的话会叠在 Motion 上，所以 CLI 会从className、cn()、clsx()、cva()、tv()中移除：tw-animate-css 工具类（animate-in、fade-in-0、zoom-in-95 等，含变体）、shadcn/ui 的关键帧（animate-accordion-down 等）、各原语的 CSS 过渡（Base UI 的 data-starting-style、React Aria 的 data-entering、从 CSS 变量读取的高度）。

3. Tailwind CSS 3 的居中。Tailwind 3 用 translate-x-[-50%] 写transform，会与 Motion 冲突，CLI 改为用 margin 居中（inset-0 m-auto h-fit）。Tailwind 4 的 translate 使用独立属性，可以与 Motion 共存，因此保留。

输出

ok components/ui/accordion.tsx
    Accordion: radix-ui → @animate-ui/react/primitives/radix-ui
    removed CSS animations: data-open:animate-accordion-down …

ok components/ui/dialog.tsx
    Dialog: radix-ui → @animate-ui/react/primitives/radix-ui
    removed CSS animations: data-open:animate-in data-closed:animate-out …

2 files animated.

未安装的组件会给出对应的 shadcn add 命令并以退出码 1 结束；尚未支持的原语列在Not animated yet 下保持原样；如果 @animate-ui/react 尚未安装，CLI 会提示安装它和 motion。

支持的原语

migrate

把 v1（registry 复制进 components/animate-ui 的文件）迁移到 @animate-ui/react。

# 先预览，迁移会改动项目里的多个文件
bunx @animate-ui/cli@latest migrate all --dry-run

# 只迁移部分 v1 原语
bunx @animate-ui/cli@latest migrate accordion tooltip

# 不询问，直接删除不再被引用的 v1 文件
bunx @animate-ui/cli@latest migrate all --delete

迁移会按 components.json 的别名重写所有引用 v1 的文件：import 改到新包，v1 的导出名映射到 v2 的组件；改名的 props 会被替换（keepRendered → forceMount、side →data-side 等）；v1 中 Base UI beta 的 props 会按 Base UI 1 的改名重写或标注。

需要人工处理的地方会带文件名与行号、以 ! 标出：只存在于 v1 的组件与 hook、v2 不再接受的 Motion props（initial、animate、layoutId…），以及没有 v2 对应物的 Files 与 Headless UI。 结束后 CLI 会询问如何处理不再被引用的 v1 文件；非交互环境下默认保留，除非传入 --delete。

audit

audit 只读地列出项目里所有会动的属性与它们的开销，不修改任何文件。它读取 Motion 的 props 与 animate() 调用、Tailwind 的 transition / duration / ease / animation 类，以及 CSS 的transition、animation、@keyframes 与 will-change。

bunx @animate-ui/cli@latest audit
# 只读某些目录或文件
bunx @animate-ui/cli@latest audit src/components app/page.tsx
# 输出 JSON，方便脚本处理
bunx @animate-ui/cli@latest audit --json

属性按开销分类：compositor（transform、opacity、filter，GPU 绘制）、main-thread（Motion 的 x / y / scale / rotate 简写，不触发布局但每帧由 JS 写入）、paint（颜色、阴影、SVG 描边，每帧重绘）与 layout（width、height、top、margin，每帧重新测量）。报告陈述事实，不做评分。

选项

组件找不到或命令失败时退出码为 1；在 migrate 的询问中中止时为 130。

对应官方文档 2026-10-18 版本。