auto-animate

AutoAnimate - エラー防止ガイド

パッケージ：@formkit/[email protected] (Sept 2025) フレームワーク：React、Vue、Solid、Svelte、Preact 最終更新日：2025-11-22

---

SSR セーフなパターン（Cloudflare Workers／Next.js では必須）

// Use client-only import to prevent SSR errors
import { useState, useEffect } from "react";

export function useAutoAnimateSafe<T extends HTMLElement>() {
  const [parent, setParent] = useState<T | null>(null);

  useEffect(() => {
    if (typeof window !== "undefined" && parent) {
      import("@formkit/auto-animate").then(({ default: autoAnimate }) => {
        autoAnimate(parent);
      });
    }
  }, [parent]);

  return [parent, setParent] as const;
}

重要な理由：Issue #1（SSR／Next.js のインポートエラー）を防ぎます。AutoAnimate はサーバー上では使用できない DOM API を使用します。

---

既知の問題の防止（報告済みのエラー 10 件）

このスキルは、報告済みの問題 10 件以上を防ぎます。

Issue #1：SSR／Next.js のインポートエラー

エラー：「Can't import the named export 'useEffect' from non EcmaScript module」 ソース：https://github.com/formkit/auto-animate/issues/55 発生する理由：AutoAnimate はサーバー上では使用できない DOM API を使用します。 防止策：動的インポートを使用します（templates/vite-ssr-safe.tsx を参照）。

Issue #2：条件付きの親要素のレンダリング

エラー：親要素が条件付きの場合、アニメーションが動作しません。 ソース：https://github.com/formkit/auto-animate/issues/8 発生する理由：存在しない要素には Ref を設定できません。 防止策：

// ❌ Wrong
{showList && <ul ref={parent}>...</ul>}

// ✅ Correct
<ul ref={parent}>{showList && items.map(...)}</ul>

Issue #3：一意なキーの不足

エラー：アイテムが正しくアニメーションしない、またはちらつきます。 ソース：公式ドキュメント 発生する理由：React が変更されたアイテムを追跡できません。 防止策：常に一意で安定したキー（key={item.id}）を使用します。

Issue #4：Flexbox の幅に関する問題

エラー：要素の幅が滑らかにアニメーションせず、急に切り替わります。 ソース：公式ドキュメント 発生する理由：flex-grow: 1 は周囲のコンテンツを待機します。 防止策：アニメーションする要素では flex-grow の代わりに明示的な幅を指定します。

Issue #5：テーブル行の表示に関する問題

エラー：行の削除時にテーブル構造が崩れます。 ソース：https://github.com/formkit/auto-animate/issues/7 発生する理由：Display: table-row がアニメーションと競合します。 防止策：個々の行ではなく <tbody> に適用するか、div ベースのレイアウトを使用します。

Issue #6：Jest のテストエラー

エラー：「Cannot find module '@formkit/auto-animate/react'」 ソース：https://github.com/formkit/auto-animate/issues/29 発生する理由：Jest が ESM のエクスポートを正しく解決できません。 防止策：jest.config.js で moduleNameMapper を設定します。

Issue #7：esbuild との互換性

エラー：「Path '.' not exported by package」 ソース：https://github.com/formkit/auto-animate/issues/36 発生する理由：ESM／CommonJS の条件が一致していません。 防止策：ESM モジュールを適切に処理するよう esbuild を設定します。

Issue #8：CSS の position による副作用

エラー：AutoAnimate の追加後にレイアウトが崩れます。 ソース：公式ドキュメント 発生する理由：親要素に自動的に position: relative が設定されます。 防止策：CSS で position の変更を考慮するか、明示的に設定します。

Issue #9：Vue／Nuxt の登録エラー

エラー：「Failed to resolve directive: auto-animate」 ソース：https://github.com/formkit/auto-animate/issues/43 発生する理由：プラグインが正しく登録されていません。 防止策：Vue／Nuxt の設定でプラグインを正しく設定します（references/ を参照）。

Issue #10：Angular の ESM に関する問題

エラー：「ESM-only package」でビルドに失敗します。 ソース：https://github.com/formkit/auto-animate/issues/72 発生する理由：CommonJS のビルド環境です。 防止策：Angular Package Format 用に ng-packagr を設定します。

---

重要なルール（エラー防止）

必ず行うこと

✅ 一意で安定したキーを使用する - key={index} ではなく key={item.id} を使用します。 ✅ 親要素を DOM に残す - 親の Ref 要素は常にレンダリングします。 ✅ SSR ではクライアント専用にする - サーバー環境では動的インポートを使用します。 ✅ アクセシビリティに配慮する - disrespectUserMotionPreference: false を維持します。 ✅ モーションを無効にしてテストする - アニメーションがなくても UI が動作することを確認します。 ✅ 明示的な幅を使用する - アニメーションする要素では flex-grow を避けます。 ✅ テーブルでは tbody に適用する - 個々の行には適用しません。

避けるべきこと

❌ 条件付きの親要素 - {show && <ul ref={parent}>} ❌ キーにインデックスを使う - key={index} はアニメーションを壊します ❌ SSR を無視する - Cloudflare Workers／Next.js で問題が発生します ❌ アニメーションを強制する - disrespectUserMotionPreference: true はアクセシビリティを損ないます ❌ テーブルを直接アニメーションさせる - tbody または div ベースのレイアウトを使用してください ❌ 一意のキーを省略する - 適切なアニメーションに必要です ❌ 複雑なアニメーション - Motion を使用してください

注：AutoAnimate は prefers-reduced-motion を自動的に尊重します（無効にしないでください）。

---

パッケージのバージョン

最新：@formkit/[email protected]（2025年9月5日）

{
  "dependencies": {
    "@formkit/auto-animate": "^0.9.0"
  }
}

フレームワークの互換性：React 18 以降、Vue 3 以降、Solid、Svelte、Preact

---

公式ドキュメント

• 公式サイト：https://auto-animate.formkit.com
• GitHub：https://github.com/formkit/auto-animate
• npm：https://www.npmjs.com/package/@formkit/auto-animate
• React ドキュメント：https://auto-animate.formkit.com/react

---

テンプレートとリファレンス

同梱のリソースを参照してください：

• templates/ - コピーして使えるサンプル（SSR 対応、アコーディオン、トースト、フォーム）
• references/ - CSS の競合、SSR パターン、ライブラリの比較