gsap-nuxt-module 1.1.5 → 1.1.8

package/README.md

@@ -18,7 +18,8 @@ Find and replace all on all files (CMD+SHIFT+F):
 
 **Enhance your Nuxt application with powerful animations and transitions using GSAP!**
 
-- [🏀 Online playground](https://stackblitz.com/edit/gsap-nuxt-module?file=app.vue)
+- [📖 Documentation](https://lucaargentieri.github.io/gsap-nuxt-module/)
+- [🏀 Online playground](https://stackblitz.com/edit/gsap-nuxt-module?file=README.md)
 - [📖 GSAP](https://gsap.com/)
 
 ## Features
@@ -100,6 +101,114 @@ onMounted(() => {
 
 That's it! You can now use gsap-nuxt-module in your Nuxt app ✨
 
+## useGsap()
+
+`useGsap()` returns the GSAP instance directly — use it to access `gsap.timeline()`,
+`gsap.to()`, `gsap.set()`, utility methods like `gsap.utils.toArray()`, and more.
+No import needed; it is auto-imported like all other composables.
+
+```ts
+<script setup lang="ts">
+const gsap = useGsap()
+const boxRef = ref(null)
+
+onMounted(() => {
+  const tl = gsap.timeline({ repeat: -1, yoyo: true })
+  tl.to(boxRef.value, { x: 200, duration: 1, ease: 'power2.inOut' })
+    .to(boxRef.value, { rotation: 360, duration: 0.8 })
+})
+</script>
+```
+
+## Available composables
+
+| Composable | Plugin | `nuxt.config.ts` key |
+|---|---|---|
+| `useGsap()` | GSAP core | — (always available) |
+| `useScrollTrigger()` | ScrollTrigger | `ScrollTrigger` |
+| `useScrollSmoother()` | ScrollSmoother | `ScrollSmoother` |
+| `useSplitText()` | SplitText | `SplitText` |
+| `useMotionPathHelper()` | MotionPathHelper | `MotionPathHelper` |
+| `useDraggable()` | Draggable | `Draggable` |
+| `useFlip()` | Flip | `Flip` |
+| `useObserver()` | Observer | `Observer` |
+| `useGSDevTools()` | GSDevTools | `GSDevTools` |
+| `useCustomEase()` | CustomEase | `CustomEase` |
+| `useCustomWiggle()` | CustomWiggle | `CustomWiggle` |
+| `useCustomBounce()` | CustomBounce | `CustomBounce` |
+
+## Plugin loading
+
+Only plugins listed in `nuxt.config.ts` are dynamically imported —
+zero bundle overhead for unused plugins.
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  gsap: {
+    plugins: ['ScrollTrigger', 'Draggable'],
+    // only these two will be bundled
+  },
+})
+```
+
+## Cleanup
+
+GSAP animations are not automatically cleaned up when a component unmounts.
+Use `onUnmounted` to prevent memory leaks.
+
+Plugin registration is handled once by the module at app startup — never call `gsap.registerPlugin()` manually.
+In components, clean up only the instances your component created (tweens, timelines, ScrollTrigger instances, Draggable instances, etc.).
+
+**Simple plugin instance cleanup (`Draggable`):**
+
+```ts
+<script setup lang="ts">
+const Draggable = useDraggable()
+const boxRef = ref<HTMLElement | null>(null)
+let draggables: ReturnType<typeof Draggable.create> = []
+
+onMounted(() => {
+  if (!boxRef.value) return
+  draggables = Draggable.create(boxRef.value)
+})
+
+onUnmounted(() => {
+  draggables.forEach((instance) => instance.kill())
+  draggables = []
+})
+</script>
+```
+
+See real cleanup examples in `playground/pages/draggable.vue`, `playground/pages/scroll-trigger.vue`, `playground/pages/split-text.vue`, and `playground/pages/scroll-smoother.vue`.
+
+**Recommended — `gsap.context()` (covers all child tweens, timelines and ScrollTriggers):**
+
+```ts
+<script setup lang="ts">
+const gsap = useGsap()
+let ctx: gsap.Context
+
+onMounted(() => {
+  ctx = gsap.context(() => {
+    gsap.to('.box', { x: 100 })
+  })
+})
+
+onUnmounted(() => ctx.revert())
+</script>
+```
+
+**Single timeline:**
+
+```ts
+const gsap = useGsap()
+const tl = gsap.timeline()
+onUnmounted(() => tl.kill())
+```
+
+→ [gsap.context() docs](https://gsap.com/docs/v3/GSAP/gsap.context())
+
 ## Contribution
 
 <details>

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=3.0.0"
   },
-  "version": "1.1.5",
+  "version": "1.1.8",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,4 +1,3 @@
-import { fileURLToPath } from 'node:url';
 import { defineNuxtModule, createResolver, addPlugin, addImportsDir } from '@nuxt/kit';
 
 const module$1 = defineNuxtModule({
@@ -13,14 +12,13 @@ const module$1 = defineNuxtModule({
     plugins: []
   },
   setup(_options, _nuxt) {
-    const resolver = createResolver(import.meta.url);
-    const runtimeDir = fileURLToPath(new URL("./runtime", import.meta.url));
+    const { resolve } = createResolver(import.meta.url);
     _nuxt.options.runtimeConfig.public.gsap = {
       plugins: _options.plugins ?? []
     };
-    addPlugin(resolver.resolve("./runtime/plugin"));
-    addImportsDir(resolver.resolve(runtimeDir, "composables"));
-    addImportsDir(resolver.resolve(runtimeDir, "utils"));
+    addPlugin({ src: resolve("./runtime/plugin"), mode: "client" });
+    addImportsDir(resolve("./runtime/composables"));
+    addImportsDir(resolve("./runtime/utils"));
   }
 });
 

package/dist/runtime/composables/createGsapComposable.d.ts

@@ -1,3 +1,37 @@
+import { gsap } from 'gsap';
+import type { ComputedRef, Ref, WatchSource } from 'vue';
+type ContextSafeFn = <F extends (...args: unknown[]) => unknown>(fn: F) => F;
+export interface UseGsapOptions {
+    scope?: Ref<HTMLElement | null> | ComputedRef<HTMLElement | null>;
+    dependencies?: WatchSource | WatchSource[];
+    revertOnUpdate?: boolean;
+}
+/**
+ * Zero-argument overload — returns the raw GSAP instance.
+ *
+ * Use it to call `gsap.timeline()`, `gsap.to()`, `gsap.set()`,
+ * utility methods (`gsap.utils`, `gsap.ticker`), and more.
+ *
+ * **Cleanup is the caller's responsibility.**
+ *
+ * @see https://gsap.com/docs/v3/GSAP/
+ */
+export declare function useGsap(): typeof gsap;
+/**
+ * Setup-function overload — wraps `gsap.context()` with automatic revert.
+ *
+ * Animations declared inside `setup` are scoped to the optional `scope` element
+ * and are reverted automatically when the component unmounts (or the effect scope
+ * is disposed). Pass `dependencies` to re-run `setup` reactively.
+ *
+ * Returns `{ contextSafe }` — a wrapper for event handlers that need to add
+ * animations to the existing context after mount.
+ *
+ * @see https://gsap.com/docs/v3/GSAP/gsap.context()
+ */
+export declare function useGsap(setup: (ctx: gsap.Context) => void, options?: UseGsapOptions): {
+    contextSafe: ContextSafeFn;
+};
 export declare const useScrollTrigger: () => {
     new (vars: ScrollTrigger.StaticVars, animation?: gsap.core.Animation): {
         readonly animation?: gsap.core.Animation | undefined;
@@ -51,14 +85,14 @@ export declare const useScrollTrigger: () => {
     observe(vars: Observer.ObserverVars): Observer;
     positionInViewport(element: Element | string, referencePoint?: string | number, horizontal?: boolean): number;
     refresh(safe?: boolean): void;
-    register(core: typeof gsap): void;
+    register(core: typeof globalThis.gsap): void;
     removeEventListener(event: "scrollStart" | "scrollEnd" | "refreshInit" | "refresh" | "matchMedia" | "revert", callback: gsap.Callback): void;
     saveStyles(targets: gsap.DOMTarget): void;
     scrollerProxy(scroller: gsap.DOMTarget, vars?: ScrollTrigger.ScrollerProxyVars): void;
     snapDirectional(incrementOrArray: number | number[]): ScrollTrigger.SnapDirectionalFunc;
     sort(func?: Function): ScrollTrigger[];
     update(): void;
-};
+} | null;
 export declare const useScrollSmoother: () => {
     new (vars: ScrollSmoother.Vars): {
         readonly scrollTrigger: ScrollTrigger;
@@ -86,7 +120,7 @@ export declare const useScrollSmoother: () => {
     create(vars: ScrollSmoother.Vars): ScrollSmoother;
     get(): ScrollSmoother | undefined;
     refresh(safe?: boolean): void;
-};
+} | null;
 export declare const useSplitText: () => {
     new (target: gsap.DOMTarget, vars?: SplitText.Vars): {
         readonly chars: Element[];
@@ -100,14 +134,14 @@ export declare const useSplitText: () => {
         split(vars: SplitText.Vars): SplitText;
     };
     create(target: gsap.DOMTarget, vars?: SplitText.Vars): SplitText;
-};
+} | null;
 export declare const useMotionPathHelper: () => {
     new (target: gsap.DOMTarget, vars?: MotionPathHelper.Vars): {
         kill(): void;
     };
     create(target: gsap.DOMTarget, vars?: MotionPathHelper.Vars): MotionPathHelper;
     editPath(target: gsap.DOMTarget, vars?: MotionPathHelper.EditPathVars): MotionPathHelper;
-};
+} | null;
 export declare const useDraggable: () => {
     new (target: gsap.DOMTarget, vars?: Draggable.Vars): {
         readonly autoScroll: number;
@@ -160,7 +194,7 @@ export declare const useDraggable: () => {
     get(target: gsap.DOMTarget): Draggable;
     hitTest(testObject1: Draggable.TestObject, testObject2: Draggable.TestObject, threshold?: number | string): boolean;
     timeSinceDrag(): number;
-};
+} | null;
 export declare const useFlip: () => {
     new (): {};
     readonly version: string;
@@ -175,10 +209,10 @@ export declare const useFlip: () => {
     killFlipsOf(targets: gsap.DOMTarget, complete?: boolean): void;
     makeAbsolute(targets: gsap.DOMTarget | Flip.FlipState[]): Element[];
     to(state: Flip.FlipState, vars?: Flip.FromToVars): gsap.core.Timeline;
-    register(core: typeof gsap): void;
+    register(core: typeof globalThis.gsap): void;
     ElementState: typeof Flip.ElementState;
     FlipState: typeof Flip.FlipState;
-};
+} | null;
 export declare const useObserver: () => {
     new (): {
         readonly deltaX: number;
@@ -210,14 +244,14 @@ export declare const useObserver: () => {
     create(vars: Observer.ObserverVars): Observer;
     getAll(): Observer[];
     getById(id: string): Observer | undefined;
-};
+} | null;
 export declare const useGSDevTools: () => {
     new (target: gsap.DOMTarget, vars?: GSDevTools.Vars): {
         kill(): void;
     };
     create(vars?: GSDevTools.Vars): GSDevTools;
     getById(id: string): GSDevTools | null;
-};
+} | null;
 export declare const useCustomEase: () => {
     new (id: string, data?: string | number[], config?: CustomEaseConfig): {
         id: string;
@@ -231,18 +265,19 @@ export declare const useCustomEase: () => {
     register(core: object): void;
     get(id: string): EaseFunction;
     getSVGData(ease: CustomEase | EaseFunction | string, config?: CustomEaseConfig): string;
-};
+} | null;
 export declare const useCustomWiggle: () => {
     new (id: string, vars?: CustomWiggleVars): {
         ease: EaseFunction;
     };
     create(id: string, vars?: CustomWiggleVars): EaseFunction;
     register(core: object): void;
-};
+} | null;
 export declare const useCustomBounce: () => {
     new (id: string, vars?: CustomBounceVars): {
         ease: EaseFunction;
     };
     create(id: string, vars?: CustomBounceVars): EaseFunction;
     register(core: object): void;
-};
+} | null;
+export {};

package/dist/runtime/composables/createGsapComposable.js

@@ -1,4 +1,41 @@
+import { gsap } from "gsap";
+import { onMounted, onScopeDispose, watch } from "vue";
 import { createGsapComposable } from "../create-gsap-composable.js";
+export function useGsap(setup, options) {
+  if (!setup) return gsap;
+  if (import.meta.server) {
+    return { contextSafe: (fn) => fn };
+  }
+  let ctx = null;
+  const runSetup = () => {
+    const scope = options?.scope?.value ?? void 0;
+    ctx = gsap.context(setup, scope);
+  };
+  onMounted(() => {
+    runSetup();
+  });
+  if (options?.dependencies !== void 0) {
+    const deps = Array.isArray(options.dependencies) ? options.dependencies : [options.dependencies];
+    watch(deps, () => {
+      if (options.revertOnUpdate === false) return;
+      ctx?.revert();
+      runSetup();
+    }, { flush: "post" });
+  }
+  onScopeDispose(() => {
+    ctx?.revert();
+    ctx = null;
+  });
+  const contextSafe = (fn) => {
+    return ((...args) => {
+      if (ctx) {
+        return ctx.add(() => fn(...args));
+      }
+      return fn(...args);
+    });
+  };
+  return { contextSafe };
+}
 export const useScrollTrigger = createGsapComposable("ScrollTrigger");
 export const useScrollSmoother = createGsapComposable("ScrollSmoother");
 export const useSplitText = createGsapComposable("SplitText");

package/dist/runtime/create-gsap-composable.d.ts

@@ -1,6 +1,15 @@
 /**
- * Factory to create GSAP plugin composables.
- * @param pluginName - Name of the GSAP plugin as provided in nuxtApp injects.
- * @param fallbackMessage - Optional error message for missing plugin.
+ * Factory that creates a composable returning a registered GSAP plugin.
+ *
+ * The returned composable reads the plugin from `nuxtApp` at call time.
+ * Returns `null` during SSR (plugin is client-only).
+ * Throws on the client if the plugin was not enabled in `nuxt.config.ts`.
+ *
+ * **Cleanup is the caller's responsibility.**
+ * Destroy instances created from the plugin (e.g. `Draggable`, `ScrollTrigger`)
+ * in `onUnmounted` to avoid memory leaks.
+ *
+ * @param pluginName - Name of the GSAP plugin as registered in nuxtApp.
+ * @param fallbackMessage - Optional custom error message for missing plugin.
  */
-export declare function createGsapComposable<T>(pluginName: string, fallbackMessage?: string): () => T;
+export declare function createGsapComposable<T>(pluginName: string, fallbackMessage?: string): () => T | null;

package/dist/runtime/create-gsap-composable.js

@@ -1,6 +1,7 @@
 import { useNuxtApp } from "#app";
 export function createGsapComposable(pluginName, fallbackMessage) {
   return () => {
+    if (import.meta.server) return null;
     const nuxtApp = useNuxtApp();
     const plugin = nuxtApp[`$${pluginName}`];
     if (!plugin) {

package/dist/runtime/gsap-loaders.d.ts

@@ -0,0 +1,3 @@
+export function loadFlip(): Promise<typeof import("gsap/Flip")>;
+export function loadDraggable(): Promise<typeof import("gsap/Draggable")>;
+export function loadObserver(): Promise<typeof import("gsap/Observer")>;

package/dist/runtime/gsap-loaders.js

@@ -0,0 +1,7 @@
+// @ts-nocheck
+
+export const loadFlip = () => import('gsap/Flip')
+
+export const loadDraggable = () => import('gsap/Draggable')
+
+export const loadObserver = () => import('gsap/Observer')

package/dist/runtime/gsap-plugins.d.ts

@@ -1,7 +1,3 @@
-/**
- * This object contains lazy-loaded GSAP plugins for use in the application.
- *
- */
 export declare const gsapPlugins: {
     ScrollTrigger: () => Promise<{
         new (vars: ScrollTrigger.StaticVars, animation?: gsap.core.Animation): {

package/dist/runtime/gsap-plugins.js

@@ -1,3 +1,4 @@
+import { loadDraggable, loadFlip, loadObserver } from "./gsap-loaders.js";
 export const gsapPlugins = {
   // Scroll Plugins
   ScrollTrigger: () => import("gsap/ScrollTrigger").then((mod) => mod.ScrollTrigger),
@@ -13,10 +14,10 @@ export const gsapPlugins = {
   MotionPathPlugin: () => import("gsap/MotionPathPlugin").then((mod) => mod.MotionPathPlugin),
   MotionPathHelper: () => import("gsap/MotionPathHelper").then((mod) => mod.MotionPathHelper),
   // UI Plugins
-  Flip: () => import("gsap/Flip").then((mod) => mod.Flip),
-  Draggable: () => import("gsap/Draggable").then((mod) => mod.Draggable),
+  Flip: () => loadFlip().then((mod) => mod.Flip),
+  Draggable: () => loadDraggable().then((mod) => mod.Draggable),
   InertiaPlugin: () => import("gsap/InertiaPlugin").then((mod) => mod.InertiaPlugin),
-  Observer: () => import("gsap/Observer").then((mod) => mod.Observer),
+  Observer: () => loadObserver().then((mod) => mod.Observer),
   // Other Plugins
   PixiPlugin: () => import("gsap/PixiPlugin").then((mod) => mod.PixiPlugin),
   EaselPlugin: () => import("gsap/EaselPlugin").then((mod) => mod.EaselPlugin),

package/dist/runtime/plugin.js

@@ -1,37 +1,41 @@
 import { gsap } from "gsap";
 import { gsapPlugins } from "./gsap-plugins.js";
 import { defineNuxtPlugin, useRuntimeConfig } from "#app";
-export default defineNuxtPlugin(async (nuxtApp) => {
-  const config = useRuntimeConfig().public.gsap;
-  const pluginsToRegister = new Set(config.plugins || []);
-  const pluginDependencies = {
-    ScrollSmoother: ["ScrollTrigger"],
-    CustomWiggle: ["CustomEase"],
-    CustomBounce: ["CustomEase"]
-  };
-  const resolvedPlugins = /* @__PURE__ */ new Set();
-  const resolvePlugin = (plugin) => {
-    if (resolvedPlugins.has(plugin)) return;
-    const deps = pluginDependencies[plugin] || [];
-    deps.forEach(resolvePlugin);
-    resolvedPlugins.add(plugin);
-  };
-  for (const plugin of pluginsToRegister) {
-    resolvePlugin(plugin);
-  }
-  for (const pluginName of resolvedPlugins) {
-    const loader = gsapPlugins[pluginName];
-    if (!loader) {
-      throw new Error(
-        `[gsap-nuxt-module] Plugin "${pluginName}" not found. Available plugins: ${Object.keys(gsapPlugins).join(", ")}`
-      );
+export default defineNuxtPlugin({
+  name: "gsap-nuxt-module",
+  enforce: "post",
+  setup: async (nuxtApp) => {
+    const config = useRuntimeConfig().public.gsap;
+    const pluginsToRegister = new Set(config.plugins || []);
+    const pluginDependencies = {
+      ScrollSmoother: ["ScrollTrigger"],
+      CustomWiggle: ["CustomEase"],
+      CustomBounce: ["CustomEase"]
+    };
+    const resolvedPlugins = /* @__PURE__ */ new Set();
+    const resolvePlugin = (plugin) => {
+      if (resolvedPlugins.has(plugin)) return;
+      const deps = pluginDependencies[plugin] || [];
+      deps.forEach(resolvePlugin);
+      resolvedPlugins.add(plugin);
+    };
+    for (const plugin of pluginsToRegister) {
+      resolvePlugin(plugin);
     }
-    try {
-      const plugin = await loader();
-      gsap.registerPlugin(plugin);
-      nuxtApp.provide(pluginName, plugin);
-    } catch (err) {
-      console.error(`[gsap-nuxt-module] Failed to load plugin "${pluginName}":`, err);
+    for (const pluginName of resolvedPlugins) {
+      const loader = gsapPlugins[pluginName];
+      if (!loader) {
+        throw new Error(
+          `[gsap-nuxt-module] Plugin "${pluginName}" not found. Available plugins: ${Object.keys(gsapPlugins).join(", ")}`
+        );
+      }
+      try {
+        const plugin = await loader();
+        gsap.registerPlugin(plugin);
+        nuxtApp.provide(pluginName, plugin);
+      } catch (err) {
+        console.error(`[gsap-nuxt-module] Failed to load plugin "${pluginName}":`, err);
+      }
     }
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsap-nuxt-module",
-  "version": "1.1.5",
+  "version": "1.1.8",
   "description": "GSAP integration for Nuxt.",
   "repository": "LucaArgentieri/gsap-nuxt-module",
   "author": "Luca Argentieri",
@@ -29,26 +29,27 @@
     "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
     "release": "npm run lint && npm run prepack && changelogen --release --patch && npm publish && git push --follow-tags",
     "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "test": "vitest run",
     "test:watch": "vitest watch",
-    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+    "test:types": "vue-tsc --noEmit && nuxi prepare playground && cd playground && vue-tsc --noEmit"
   },
   "dependencies": {
-    "@nuxt/kit": "^3.15.4",
+    "@nuxt/kit": "^4.0.0",
     "gsap": "^3.14.2"
   },
   "devDependencies": {
-    "@nuxt/devtools": "^2.1.0",
+    "@nuxt/devtools": "^3.0.0",
     "@nuxt/eslint-config": "^1.1.0",
     "@nuxt/module-builder": "^1.0.1",
-    "@nuxt/schema": "^3.15.4",
-    "@nuxt/test-utils": "^3.17.0",
+    "@nuxt/schema": "^4.0.0",
+    "@nuxt/test-utils": "^4.0.0",
     "@types/node": "latest",
     "changelogen": "^0.6.0",
-    "eslint": "^9.21.0",
-    "nuxt": "^3.15.4",
+    "eslint": "^10.0.0",
+    "nuxt": "^4.0.0",
     "typescript": "^5.9.3",
-    "vitest": "^3.0.7",
-    "vue-tsc": "^2.2.4"
+    "vitest": "^4.0.0",
+    "vue-tsc": "^3.0.0"
   }
 }