gsap-nuxt-module 1.1.7 → 1.1.9

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/github/LucaArgentieri/gsap-nuxt-module?file=playground%2Fapp.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
@@ -119,6 +120,31 @@ onMounted(() => {
 </script>
 ```
 
+### Context form (recommended)
+
+Pass a `setup` function to wrap animations in a [`gsap.context()`](https://gsap.com/docs/v3/GSAP/gsap.context/).
+The context reverts automatically when the component unmounts — no `onUnmounted` boilerplate needed.
+During page navigation, cleanup is deferred until after the leave transition finishes.
+
+```ts
+<script setup lang="ts">
+const containerRef = ref<HTMLElement | null>(null)
+
+useGsap(() => {
+  gsap.from('.box', { opacity: 0, y: 30, duration: 0.6 })
+}, { scope: containerRef })
+</script>
+
+<template>
+  <div ref="containerRef">
+    <div class="box">I animate in safely</div>
+  </div>
+</template>
+```
+
+Returns `{ contextSafe }` for wrapping event handlers that add animations after mount.
+See the [full docs](https://lucaargentieri.github.io/gsap-nuxt-module/composables/use-gsap) for all options.
+
 ## Available composables
 
 | Composable | Plugin | `nuxt.config.ts` key |
@@ -153,11 +179,10 @@ export default defineNuxtConfig({
 
 ## Cleanup
 
-GSAP animations are not automatically cleaned up when a component unmounts.
-Use `onUnmounted` to prevent memory leaks.
+When using `useGsap()` with a setup function, cleanup is automatic. When using the zero-arg form, use `onUnmounted` to prevent memory leaks.
 
-Do not call `gsap.unregisterPlugin(...)` inside page/components: plugin registration is app-wide.
-In components, clean up only the instances created by that component.
+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`):**
 

package/dist/module.json

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

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

@@ -1,15 +1,70 @@
+import { gsap } from 'gsap';
+import type { ComputedRef, Ref, WatchSource } from 'vue';
 /**
- * Returns the GSAP instance for direct use.
+ * Wraps an event handler so it runs inside the active GSAP context.
+ *
+ * **Note:** return values are discarded when a context exists — `ctx.add()`
+ * returns `void`. Use `contextSafe` only for void side-effect handlers
+ * (DOM events, pointer callbacks, etc.).
+ */
+type ContextSafeFn = <F extends (...args: unknown[]) => void>(fn: F) => F;
+export interface UseGsapOptions {
+    scope?: Ref<HTMLElement | null> | ComputedRef<HTMLElement | null>;
+    dependencies?: WatchSource | WatchSource[];
+    revertOnUpdate?: boolean;
+    /**
+     * When to revert the GSAP context during page navigation.
+     *
+     * @deprecated This option has no behavioral effect. Both `'unmount'` and
+     * `'route-leave'` produce identical behavior: the GSAP context is reverted
+     * after the leave transition finishes, when the component unmounts via
+     * `onScopeDispose`. Kept for backward compatibility only.
+     *
+     * - `'unmount'` (default) — reverts after the leave transition finishes,
+     *   when the component is unmounted via `onScopeDispose`.
+     * - `'route-leave'` — semantically identical to `'unmount'`.
+     *
+     * In both cases, animations continue to play during the leave transition,
+     * then are reverted once the component unmounts.
+     *
+     * **Note:** if a `router.beforeEach` guard rejects navigation *after*
+     * `onBeforeRouteLeave` is registered, the `onBeforeRouteLeave` hook will still
+     * have fired and set `isLeavingViaRoute` to `true`, but the component will not unmount.
+     * The context remains active and animations continue until the next successful
+     * navigation.
+     *
+     * @example
+     * // Continuous animation that should play through the page-leave transition
+     * useGsap(() => { ... }, { cleanupOn: 'route-leave' })
+     */
+    cleanupOn?: 'unmount' | 'route-leave';
+}
+/**
+ * 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.**
- * Use `gsap.context()` + `ctx.revert()` in `onUnmounted` to avoid memory leaks.
  *
  * @see https://gsap.com/docs/v3/GSAP/
  */
-export declare function useGsap(): typeof globalThis.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;
@@ -70,7 +125,7 @@ export declare const useScrollTrigger: () => {
     snapDirectional(incrementOrArray: number | number[]): ScrollTrigger.SnapDirectionalFunc;
     sort(func?: Function): ScrollTrigger[];
     update(): void;
-} | null;
+};
 export declare const useScrollSmoother: () => {
     new (vars: ScrollSmoother.Vars): {
         readonly scrollTrigger: ScrollTrigger;
@@ -98,7 +153,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[];
@@ -112,14 +167,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;
@@ -172,7 +227,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;
@@ -190,7 +245,7 @@ export declare const useFlip: () => {
     register(core: typeof globalThis.gsap): void;
     ElementState: typeof Flip.ElementState;
     FlipState: typeof Flip.FlipState;
-} | null;
+};
 export declare const useObserver: () => {
     new (): {
         readonly deltaX: number;
@@ -222,14 +277,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;
@@ -243,18 +298,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,7 +1,58 @@
+import { useNuxtApp } from "#app";
 import { gsap } from "gsap";
+import { onMounted, onScopeDispose, watch } from "vue";
+import { onBeforeRouteLeave } from "vue-router";
 import { createGsapComposable } from "../create-gsap-composable.js";
-export function useGsap() {
-  return gsap;
+export function useGsap(setup, options) {
+  if (!setup) return gsap;
+  if (import.meta.server) {
+    return { contextSafe: (fn) => fn };
+  }
+  let ctx = null;
+  let isLeavingViaRoute = false;
+  const runSetup = () => {
+    const scope = options?.scope?.value ?? void 0;
+    ctx = gsap.context(setup, scope);
+  };
+  onBeforeRouteLeave(() => {
+    isLeavingViaRoute = true;
+    const nuxtApp = useNuxtApp();
+    nuxtApp.hooks.hookOnce("page:transition:finish", () => {
+      ctx?.revert();
+      ctx = null;
+    });
+  });
+  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(() => {
+    if (!isLeavingViaRoute) {
+      ctx?.revert();
+      ctx = null;
+    }
+  });
+  const contextSafe = (fn) => {
+    return ((...args) => {
+      if (ctx) {
+        ctx.add(() => fn(...args));
+      } else {
+        fn(...args);
+      }
+    });
+  };
+  return { contextSafe };
 }
 export const useScrollTrigger = createGsapComposable("ScrollTrigger");
 export const useScrollSmoother = createGsapComposable("ScrollSmoother");

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

@@ -2,7 +2,8 @@
  * 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).
+ * This is a client-only composable — it is safe to call on the server but
+ * will return an inert value (the plugin is never registered server-side).
  * Throws on the client if the plugin was not enabled in `nuxt.config.ts`.
  *
  * **Cleanup is the caller's responsibility.**
@@ -12,4 +13,4 @@
  * @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 | null;
+export declare function createGsapComposable<T>(pluginName: string, fallbackMessage?: string): () => NonNullable<T>;

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsap-nuxt-module",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "description": "GSAP integration for Nuxt.",
   "repository": "LucaArgentieri/gsap-nuxt-module",
   "author": "Luca Argentieri",
@@ -29,6 +29,7 @@
     "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 && nuxi prepare playground && cd playground && vue-tsc --noEmit"

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

@@ -1,3 +0,0 @@
-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

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