gsap-nuxt-module 1.1.7 → 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/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
@@ -156,8 +157,8 @@ export default defineNuxtConfig({
 GSAP animations are not automatically cleaned up when a component unmounts.
 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.8",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

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

@@ -1,15 +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;
+}
 /**
- * Returns the GSAP instance for direct use.
+ * 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;
@@ -258,3 +280,4 @@ export declare const useCustomBounce: () => {
     create(id: string, vars?: CustomBounceVars): EaseFunction;
     register(core: object): void;
 } | null;
+export {};

package/dist/runtime/composables/createGsapComposable.js

@@ -1,7 +1,40 @@
 import { gsap } from "gsap";
+import { onMounted, onScopeDispose, watch } from "vue";
 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;
+  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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsap-nuxt-module",
-  "version": "1.1.7",
+  "version": "1.1.8",
   "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"