Recommended workflow for using GSAP / third-party JavaScript libraries?

[JacobVinjegaard]

Hi!

First of all, I really like the direction of Instatic. I'm currently evaluating it as an alternative to Webflow for my client work.

I'm trying to import an existing website that uses GSAP and ScrollTrigger.

In a normal HTML project I would either include GSAP using CDN script tags or import it through npm/TypeScript.

Inside Instatic I'm not sure what the recommended workflow is.

So far I have tried:

Adding the GSAP CDN script tags.
Creating a runtime .ts script.
Using ES module imports.
Importing from esm.sh.

Unfortunately I haven't been able to get GSAP working, and I can't find any documentation describing the recommended approach.

My questions are:

What is the recommended way to use external JavaScript libraries such as GSAP?
Is there a global Head or Layout file where external scripts should be loaded?
Should third-party libraries always be imported through TypeScript modules?
If npm imports are the preferred solution, how should packages be installed and resolved inside an Instatic project?
Is there an example project demonstrating the recommended way to use GSAP (or another third-party JavaScript library)?

One of the main reasons I'm interested in Instatic is the ability to import existing HTML/CSS/JS websites and continue editing them visually.

At the moment, understanding the recommended workflow for external JavaScript libraries is the only thing preventing me from moving forward.

Thanks in advance!

[DavidBabinec]

Hello Jacob,

thanks for the question! I understand that it's not very obvious now and the documentation is lacking. We're working on that.

Using external dependencies is actually very simple:

1. Add the dependency based on their npm package:

2. Create the script and import the dependency:

3. Enable script execution in canvas to run it:

[amylee2051]

Getting GSAP (and particularly ScrollTrigger) working in modern static site tools and bundlers can definitely be tricky if you hit lifecycle timing issues or scoping problems.

Here is a breakdown of what is likely going wrong and the recommended workflow to get GSAP running cleanly in Instatic.

The Core Problem: Why GSAP Might Be Failing right now
When using GSAP with plugins like ScrollTrigger in modern environments, failure usually happens for two reasons:

Timing/DOM Readiness: Your JS file executes before the HTML elements exist in the DOM or before the layout engine finishes rendering.

Missing Plugin Registration: ScrollTrigger is loaded or imported, but gsap.registerPlugin(ScrollTrigger) wasn't called before running the animation code.

Recommended Workflows
Method 1: The Modern ES Module / npm Approach (Best Practice)
If Instatic supports TypeScript/JavaScript runtime scripts or npm package resolution, importing via ES modules is the cleanest path for type safety and bundling.

Install or Import via ESM:
If you can import directly from ESM or npm:

import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
// Or if using CDN module URLs (e.g., esm.sh):
// import { gsap } from "https://esm.sh/gsap";
// import { ScrollTrigger } from "https://esm.sh/gsap/ScrollTrigger";

// ALWAYS register the plugin first
gsap.registerPlugin(ScrollTrigger);

Wrap initialization in a DOM / Mount check:
Ensure your script runs after the DOM elements exist:

function initAnimations() {
gsap.from(".hero-title", {
y: 50,
opacity: 0,
duration: 1,
scrollTrigger: {
trigger: ".hero-title",
start: "top 80%",
}
});
}

// Run on load
if (document.readyState === "loading") {
document.addEventListener("DOMContentLoaded", initAnimations);
} else {
initAnimations();
}

Method 2: Global Script Loading (CDN / Head Tag)
If you prefer loading GSAP globally via standard <script> tags in the Global Head or page settings, make sure script execution order is maintained:

Add scripts to Head / Footer:
Load core GSAP first, then ScrollTrigger, using defer or putting them at the bottom of the body:

<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script> <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/ScrollTrigger.min.js"></script>

Access via window.gsap in your runtime script:

window.addEventListener("DOMContentLoaded", () => {
const { gsap, ScrollTrigger } = window;
gsap.registerPlugin(ScrollTrigger);

// Your animations here...
});

Answers to Your Specific Questions
What is the recommended way to use external libraries like GSAP?
Use ES Module imports (or npm) if you are writing custom TypeScript/JS components. If you are importing static legacy HTML sites directly, CDN scripts placed before the closing tag or in the global head/layout template are usually easiest.

Is there a global Head or Layout file where external scripts should be loaded?
Yes, global/layout templates are best for base scripts (like GSAP Core & ScrollTrigger) so they are cached once across all pages rather than reloaded per component.

Should third-party libraries always be imported through TypeScript modules?
Not strictly, but importing via modules provides autocompletion and prevents global scope pollution. If you use CDN scripts, simply declare them in TypeScript if needed (declare const gsap: any;).

Key checklist for ScrollTrigger specifically:

Did you call gsap.registerPlugin(ScrollTrigger)?

If the page uses dynamic visual components or image loading, call ScrollTrigger.refresh() after the DOM finishes rendering to recalculate scroll positions.