Vite 7＋TypeScriptにGSAPを導入する方法と注意点【VanillaJS対応】

Vite 7で管理しているTypeScriptプロジェクトにGSAPを入れたいものの、何に気をつければよいのか分かりにくいと感じる方は多いです。特にVanilla構成では、ReactやVueのような専用ラッパーがないため、初期化場所や後片付けを自分で設計する必要があります。

結論からいうと、Vite 7＋TypeScript＋VanillaでのGSAP導入は難しくありません。npm i gsapで導入し、plugin登録・アニメーションの分割管理・cleanup設計を最初から入れておくのが成功のポイントです。

本記事では、2025〜2026年の公式情報をもとに、Vite 7のNode.js要件、GSAPの最新仕様、Vanillaでの実装例、ScrollTrigger運用時の注意点までまとめます。これから初めてVite 7にGSAPを入れる方でも、そのまま進めやすい形で見ていきましょう。

Vite 7＋TypeScript＋GSAPでまず押さえたいこと

まず押さえたいのが、導入の難しさはViteよりもGSAPの運用設計にあるという点です。Vite 7自体はESMベースでTypeScriptとも相性がよく、GSAPもnpm導入に素直に対応しています。

一方で、2025年に公開されたVite 7ではNode.jsの要件が上がっているため、古い環境のままではインストールや起動でつまずきやすくなりました。また、GSAPは2025年の3.13以降、従来のボーナスpluginも含めて公開npmから利用しやすくなっており、以前のような複雑な private repository 前提ではありません。

Vite 7のTypeScriptプロジェクトにGSAPを導入する手順

導入手順はシンプルですが、最初のファイル構成を整えておくと開発効率が大きく変わります。ここではVanilla前提で、実務でも使いやすい最小構成を紹介します。

// src/lib/gsap.ts
import gsap from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'

gsap.registerPlugin(ScrollTrigger)

export { gsap, ScrollTrigger }

// src/animations/hero.ts
import { gsap } from '../lib/gsap'

export function initHeroAnimation(root: ParentNode = document) {
  const title = root.querySelector<HTMLElement>('.hero-title')
  const image = root.querySelector<HTMLElement>('.hero-image')

  if (!title || !image) return () => {}

  const ctx = gsap.context(() => {
    const tl = gsap.timeline()

    tl.from(title, {
      y: 24,
      opacity: 0,
      duration: 0.7,
      ease: 'power2.out',
    }).from(
      image,
      {
        y: 16,
        opacity: 0,
        duration: 0.8,
        ease: 'power2.out',
      },
      '-=0.3'
    )
  }, root)

  return () => ctx.revert()
}

// src/main.ts
import './style.css'
import { initHeroAnimation } from './animations/hero'

const cleanup = initHeroAnimation()

if (import.meta.hot) {
  import.meta.hot.dispose(() => {
    cleanup()
  })
}

この形にしておくと、GSAP本体の管理、plugin登録、画面ごとの責務が分離できます。main.tsにすべて直書きするよりも、あとからScrollTriggerや別セクションの演出を足しやすくなります。

VanillaでGSAP開発を効率化するコツ

Vanillaで効率よく進めるコツは、アニメーションを「その場しのぎ」で増やさないことです。最初のうちは1ファイルにまとめたくなりますが、実案件ではすぐに管理しづらくなります。

特にScrollTriggerを使う場合は、画像読み込み後やアコーディオン開閉後に位置がずれることがあります。そのため、DOMの高さが変わる処理を入れた後は、ScrollTrigger.refresh()で再計算する前提で設計しておくと安心です。

import { gsap, ScrollTrigger } from '../lib/gsap'

gsap.to('.box', {
  x: 300,
  scrollTrigger: {
    trigger: '.box',
    start: 'top 80%',
    markers: import.meta.env.DEV,
  },
})

window.addEventListener('load', () => {
  ScrollTrigger.refresh()
})

また、PCとSPで演出を分けたい場合は、CSSだけで無理に吸収するよりgsap.matchMedia()を使って条件ごとに初期化する方が管理しやすいです。さらにprefers-reduced-motionにも対応しやすく、アクセシビリティ面でも扱いやすくなります。

Vite 7でGSAP導入時によくある失敗

初心者がつまずきやすいのは、GSAPのplugin登録とcleanupを軽く見てしまうことです。導入直後は動いて見えても、開発中のHMRや本番ビルドで差が出やすい部分です。

一方で、これらは最初の設計でかなり防げます。たとえば、plugin登録を1か所にまとめる、初期化関数からcleanupを返す、root要素を渡してローカルにセレクタを閉じる、といった基本を守るだけでも安定感が変わります。

Vite 7＋TypeScriptでGSAPを使うべきケース

結論として、複数要素の連動、スクロール連動、後から調整が入る演出ではGSAPが向いています。一方で、単純なホバーや短いフェードだけならCSSアニメーションで十分なケースもあります。

選ぶときは、演出の複雑さだけでなく、今後の運用も見ます。たとえばLPやブランドサイト、採用サイトのKV、スクロール演出、セクションごとの段階表示などはGSAPが扱いやすいです。逆に、保守担当がJavaScriptアニメーションに不慣れな現場では、CSSで済む部分までGSAP化しない方が安全な場合もあります。

Vite 7＋TypeScriptにGSAPを導入する方法まとめ

Vite 7のTypeScriptプロジェクトにGSAPを導入する際は、単に動かすだけでなく、長く保守できる構成にしておくことが重要です。特にVanillaでは、初期化と破棄を自分で管理する前提で組むと、後の開発がかなり楽になります。

• Vite 7ではNode.js要件を先に確認する
• GSAPはgsapの導入だけで始められる
• pluginは必ずgsap.registerPlugin()で登録する
• アニメーションは関数化し、cleanupを返す形にする
• ScrollTrigger運用ではrefresh()とレスポンシブ対応を前提にする
• 開発時のみimport.meta.env.DEVでmarkersなどを有効にする

これからVite 7＋TypeScript＋VanillaでGSAPを導入するなら、まずは小さな1セクションから始め、ファイル分割とcleanupの形を整えてから演出を広げていくのがおすすめです。

参考リンク

参考
Getting Started | ViteVite公式

参考
Env Variables and Modes | ViteVite公式

参考
HMR API | ViteVite公式

参考
Installation | GSAPGSAP公式

参考
gsap.registerPlugin() | GSAPGSAP公式

参考
gsap.context() | GSAPGSAP公式

参考
gsap.matchMedia() | GSAPGSAP公式

参考
ScrollTrigger.refresh() | GSAPGSAP公式

参考
GSAP 3.13 releaseGSAP公式ブログ