How to Detect and Configure Smooth Scroll Libraries (Lenis, Locomotive Scroll) in the AI Website-Cloner Template

The AI Website-Cloner Template detects smooth scroll libraries by scanning target sites for specific CSS classes (.lenis or .locomotive-scroll) during reconnaissance, then automatically wires the corresponding npm packages and initialization scripts into the generated Next.js project.

The JCodesMore/ai-website-cloner-template treats smooth scrolling as a critical global UI pattern that must be replicated to preserve the "feel" of a cloned site. When the agent analyzes a target website, it identifies non-native scroll implementations and configures the appropriate library initialization in src/app/layout.tsx and CSS overrides in src/app/globals.css.

How Smooth Scroll Library Detection Works

The template uses a two-phase detection strategy that maps visual markers to underlying library implementations.

Scanning for CSS Markers

During the site reconnaissance phase, the agent inspects the DOM for characteristic class names injected by popular smooth-scroll libraries. According to the workflow files, the agent explicitly checks for:

• .lenis — The root container class added by Lenis
• .locomotive-scroll — The wrapper element used by Locomotive Scroll

These detection rules are documented in /.windsurf/workflows/clone-website.md at lines 75-78, which instructs the agent to "check for .lenis class or scroll container wrappers" when analyzing the target page. The same instructions appear in /.opencode/commands/clone-website.md at the same line range.

Recording Findings in BEHAVIORS.md

When the agent identifies a smooth-scroll implementation, it records the discovery in the global-behaviors section of docs/research/BEHAVIORS.md. This metadata file serves as a contract between the reconnaissance agent and downstream builders, signaling that the cloned site requires custom scroll physics rather than native browser scrolling.

Configuring Lenis and Locomotive Scroll in Next.js

Once detected, the template executes a standardized configuration routine during Phase 2: Foundation Build to integrate the library into the Next.js scaffold.

Installation and Dependencies

The builder agent installs the required package based on the detection result:

# For Lenis

npm i lenis

# For Locomotive Scroll

npm i locomotive-scroll

Client-Side Initialization

The initialization logic is injected into src/app/layout.tsx as a client-side effect that dynamically imports the library only when the corresponding CSS class is present in the DOM. This prevents unnecessary bundle weight when the library isn't needed.

// src/app/layout.tsx
"use client";

import { useEffect } from "react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    // Lenis initialization
    if (document.querySelector(".lenis")) {
      import("lenis").then(({ default: Lenis }) => {
        const lenis = new Lenis();
        function raf(time: number) {
          lenis.raf(time);
          requestAnimationFrame(raf);
        }
        requestAnimationFrame(raf);
      });
    }
    // Locomotive Scroll initialization
    else if (document.querySelector(".locomotive-scroll")) {
      import("locomotive-scroll").then(({ default: LocomotiveScroll }) => {
        new LocomotiveScroll({
          el: document.querySelector(".locomotive-scroll")!,
          smooth: true,
        });
      });
    }
  }, []);

  return <html>{children}</html>;
}

CSS Overrides in globals.css

Smooth-scroll libraries often conflict with native browser scrolling behavior. The workflow instructs agents to add specific overrides to src/app/globals.css to normalize the experience:

/* src/app/globals.css */
html {
  scroll-behavior: auto;
}

As noted in /.windsurf/workflows/clone-website.md at lines 135-136, the builder must "Add these to globals.css and note any libraries that need to be installed."

Why Smooth Scroll Detection Matters for Website Cloning

Smooth-scroll libraries like Lenis and Locomotive Scroll replace the browser's native scroll physics with custom inertia, damping, and scroll-syncing capabilities. Failing to detect and replicate these behaviors results in a clone that looks visually identical but feels "wrong" to users—scroll-triggered animations fire at incorrect times, scroll-snapping points misalign, and the overall navigation experience diverges from the original.

By detecting these libraries early through their CSS signatures and automatically configuring the initialization scripts, the AI Website-Cloner Template ensures that scroll-dependent interactions remain faithful to the source site.

Summary

• Detection method: The agent scans for .lenis and .locomotive-scroll CSS classes during site reconnaissance, as defined in /.windsurf/workflows/clone-website.md.
• Documentation: Findings are recorded in docs/research/BEHAVIORS.md under global behaviors to inform downstream builders.
• Configuration: Detected libraries trigger automatic npm installation and dynamic imports in src/app/layout.tsx.
• CSS normalization: Required overrides like html { scroll-behavior: auto; } are injected into src/app/globals.css during Phase 2.
• Implementation: Initialization runs client-side via useEffect to ensure the DOM is ready before instantiating the smooth-scroll instance.

Frequently Asked Questions

How does the AI Website-Cloner Template identify which smooth scroll library a target site uses?

The template identifies libraries by scanning for specific CSS class names that these libraries inject into the DOM. Specifically, it looks for .lenis for the Lenis library and .locomotive-scroll for Locomotive Scroll. These detection rules are hardcoded in the workflow files at /.windsurf/workflows/clone-website.md and /.opencode/commands/clone-website.md.

Where is the smooth scroll configuration stored in the generated project?

The configuration is split across three locations: the detection record lives in docs/research/BEHAVIORS.md, the initialization script is added to src/app/layout.tsx as a client-side effect, and the CSS overrides are placed in src/app/globals.css. This separation ensures that the behavior is documented, implemented, and styled correctly.

Can the template handle both Lenis and Locomotive Scroll in the same project?

The current implementation uses conditional logic to initialize only one library per page, checking for .lenis first and falling back to .locomotive-scroll. If a site uses both simultaneously (rare but possible), the code would require manual modification to initialize both instances, as the template prioritizes the first match to avoid conflicting scroll implementations.

Why does the initialization script use dynamic imports instead of static imports?

The template uses import("lenis") and import("locomotive-scroll") inside the useEffect hook to implement code splitting. This ensures that the smooth scroll library is only loaded when the corresponding CSS class is detected in the DOM, keeping the initial bundle size smaller for pages that don't require these libraries.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}