How it works

This page gives you the mental model. If you understand this, everything else in the docs will make sense.

The short version

Ssscript is a desktop app that lets you write custom JavaScript and CSS for Webflow sites. You write code locally, the app bundles it, publishes it to a CDN, and you paste a single loader script into Webflow so your site loads it. An AI agent helps you write the code.

What it produces

When you build a project, Ssscript outputs two files:

• app.js — a single JavaScript bundle (IIFE format) containing all your modules and logic.
• app.css — a CSS bundle with your custom styles.

A single CSS bundle app.css ships styles the Designer cannot express (e.g. animation initial states, @keyframes, clip-path). Module-specific CSS lives in src/styles/mod/ and is @import-ed from app.css.

These files are what your Webflow site loads at runtime.

The pipeline

Write code → Dev server → Build → Publish → Embed in Webflow

1. Write code — in the Ssscript editor (or let the AI agent write it for you).
2. Dev server — runs locally on http://localhost:6454 with live reload. You can preview changes instantly while the Webflow Designer loads your local dev URL.
3. Build — Bun bundles your TypeScript/JavaScript and CSS into optimized production files in dist/.
4. Publish — uploads the build output to Cloudflare R2 (a global CDN). Your files get a permanent URL like https://ssscript.dev/<username>/<project>/app.js.
5. Embed — paste a single loader script into Webflow’s custom code (site-wide head). The loader handles both JS and CSS, detects the environment, and includes a smart fallback: on .webflow.io staging it tries your local dev server first and falls back to the published CDN version if the dev server isn’t running; on production it loads directly from CDN.

The module system

Ssscript projects use a module system based on data-module attributes. This is how your JavaScript code connects to Webflow elements.

In Webflow, you give an element a custom attribute:

<div data-module="slider">...</div>

In your project, you create a matching file:

src/modules/slider.ts

That file exports a function that receives the element:

export default function (element: HTMLElement, dataset: DOMStringMap) {
  // Your code runs here, scoped to this element
}

When the page loads, the module system automatically finds every element with a data-module attribute, looks up the matching file, and runs it. You don’t need to write any glue code — the discovery and mounting is automatic.

Each module can use lifecycle hooks to handle page transitions, viewport detection, and cleanup:

• onPageIn — runs when the page or element enters (for animated transitions).
• onPageOut — runs when the page is leaving.
• onView — triggers when the element enters or exits the viewport.
• onTrack — tracks scroll progress relative to the element.
• onDestroy — cleanup when the module is torn down (remove event listeners, cancel animations).

How Webflow and Ssscript relate

Webflow and Ssscript each own a different part of the final result:

Webflow	Ssscript
Structure and layout (HTML)	Custom behavior (JavaScript)
Visual styling (classes, typography, colors)	Advanced CSS that Webflow can’t do (clip-path, @keyframes, complex selectors)
CMS content and collections	Module logic, state management, animations
Responsive breakpoints	Scroll effects, viewport tracking, interactive components
Hosting and publishing the site	Hosting the custom code bundle on CDN

Webflow owns the look. Layout, spacing, typography, colors, and basic interactions should be built with Webflow classes in the Designer. Ssscript code adds behavior and advanced effects on top.

The bridge is data-module. Webflow elements get data-module="name" attributes. Ssscript modules mount on those elements. This keeps the two systems decoupled — you can rearrange elements in Webflow without breaking your code, as long as the data-module attributes stay.

The AI agent

The built-in AI agent can write, modify, and explain your code. It understands the module system, the project structure, and (when connected) your Webflow site via MCP.

You interact with it through prompts in the AI panel. It produces code diffs that you can accept or reject. Different agent modes (@@plan, @@build, @@webflow, @@figma, @@explore, @@general) steer the agent toward different kinds of tasks. See AI edits for the full reference.

Built-in tools

Each project comes with built-in libraries you can use in your modules:

• GSAP — animation library for tweens and timelines.
• Scroll (Lenis) — smooth scroll with progress tracking.
• Raf / Resize subscriptions — performance-aware animation frame and window resize handlers.
• State — lightweight event-based state management across modules.
• Page transitions (Taxi.js) — client-side navigation with animated transitions between pages (included in the unified starter; use when your project enables multi-route / transition flows).

These are pre-configured in the starter template. Import them from @lib/ in any module.

Next

• Projects — Create and open projects.
• Starters — What’s inside the starter template.
• Editor — The workspace, view modes, and tools.
• AI edits — How the AI agent works.