How the AI Website Cloner Template Handles Smooth Scroll Libraries Like Lenis During Extraction

The extraction agent detects smooth-scroll libraries by scanning for CSS classes like .lenis or .locomotive-scroll, then automatically records the dependency, updates global CSS, installs the package, and injects a client-side initialization hook to replicate the original scrolling behavior.

The JCodesMore/ai-website-cloner-template treats smooth-scroll libraries as critical global UI patterns that must be preserved during site extraction. When cloning a website that uses Lenis or Locomotive Scroll, the agent captures these behaviors in the research phase and reconstructs them during the Next.js build process.

Detection Phase: Identifying Smooth Scroll Libraries in the Source

Scanning for CSS Class Markers

During the reconnaissance phase, the extraction script scans the live target page for specific markers that indicate smooth-scroll library usage. According to the cloning skill documentation in .claude/skills/clone-website/SKILL.md, the agent specifically checks for CSS classes such as .lenis (Lenis) or .locomotive-scroll (Locomotive Scroll) to identify when these libraries are active.

The detection logic uses standard DOM querying to verify presence:

// Browser-MCP snippet used during reconnaissance
const hasLenis = !!document.querySelector('.lenis');
if (hasLenis) {
  console.log('Lenis detected – will be added to globals and installed');
}

This check ensures that scroll-driven interactions are not lost during the extraction process and that the cloned site maintains the original's scroll physics.

Specification and Documentation

Recording Behaviors in BEHAVIORS.md

Once a smooth-scroll library is detected, the extractor records the findings in the global behavior documentation. The agent writes the class name and any custom scroll container wrappers to docs/research/BEHAVIORS.md, creating a specification that the builder phase references.

This documentation includes:

• The detected library name (e.g., Lenis, Locomotive Scroll)
• Associated CSS selectors and wrapper structures
• Required installation commands for the target project

The specification ensures that the scrolling feels identical to the source site by codifying the exact configuration needed for reproduction.

Foundation Build: Updating Global Styles

Modifying src/app/globals.css

During Phase 2 – Foundation Build, the extractor updates src/app/globals.css to include the necessary CSS rules for smooth scrolling. This includes adding scroll-behavior: smooth as a fallback for browsers without the library, and any custom variables or wrapper styles the specific library requires.

/* src/app/globals.css – added by the foundation step */
html,
body {
  scroll-behavior: smooth; /* fallback for browsers without Lenis */
}

/* Lenis adds a wrapper around the page content */
.lenis {
  overflow: hidden;
}

These updates ensure that the base styling supports the smooth-scroll library before the JavaScript initialization occurs.

Installation and Initialization

Package Installation

The builder agent adds the detected library to the project dependencies in package.json. For Lenis, this typically involves adding the @studio-freight/lenis package:

{
  "dependencies": {
    "@studio-freight/lenis": "^1.0.0"
  }
}

Client-Side Provider Component

To mirror the original site's scroll behavior, the builder creates a client-side helper component that imports and instantiates the library inside a useEffect hook. This pattern ensures the smooth-scroll instance runs only in the browser and properly cleans up on unmount.

'use client';
import { useEffect } from 'react';
import Lenis from '@studio-freight/lenis';

export default function LenisProvider() {
  useEffect(() => {
    const lenis = new Lenis({
      // match the original site's configuration if known
      smooth: true,
      direction: 'vertical',
      gestureDirection: 'vertical',
    });

    const raf = (time: number) => {
      lenis.raf(time);
      requestAnimationFrame(raf);
    };
    requestAnimationFrame(raf);

    return () => lenis.destroy();
  }, []);

  return null; // no UI – just sets up scrolling
}

This component replicates the scroll dynamics exactly, ensuring that scroll-driven animations, parallax effects, and scroll-snap sections trigger at the same positions as the original site.

Verification and Quality Assurance

The final validation phase confirms that the smooth-scroll implementation matches the source. The builder verifies that npm run build completes successfully and performs visual QA to ensure the scrolling physics feel identical. This includes checking that scroll-driven components like parallax layers and scroll-snap sections behave as recorded in the behavior specification.

Summary

• Detection: The extraction agent scans for .lenis or .locomotive-scroll classes in the source DOM to identify smooth-scroll libraries.
• Documentation: Findings are recorded in docs/research/BEHAVIORS.md with specific class names and configuration requirements.
• Styling: The src/app/globals.css file receives necessary CSS rules to support the library's global behavior.
• Installation: The required package (e.g., @studio-freight/lenis) is added to package.json dependencies.
• Initialization: A client-side provider component instantiates the library in a useEffect hook to replicate original scroll dynamics.

Frequently Asked Questions

How does the clone detect if a site uses Lenis?

The extraction script queries the DOM for specific CSS classes defined in .claude/skills/clone-website/SKILL.md. It checks for .lenis or .locomotive-scroll classes, which are standard markers for these libraries. When found, the agent flags the library for inclusion in the generated Next.js project.

Where does the extraction agent record smooth-scroll library requirements?

The agent writes the specifications to docs/research/BEHAVIORS.md. This file documents the detected library name, associated CSS classes, and any custom scroll container wrappers needed to reproduce the behavior. The builder phase references this documentation to install and configure the correct dependencies.

What files are modified to support smooth scrolling in the cloned site?

The primary files modified are src/app/globals.css (to add global scroll styles and library-specific CSS) and package.json (to install the dependency). Additionally, the builder generates a new client component (such as src/components/LenisProvider.tsx) that handles the library initialization in a React-friendly manner.

How is the smooth-scroll library initialized in the Next.js output?

The builder creates a client-side React component marked with the 'use client' directive. This component imports the library (e.g., import Lenis from '@studio-freight/lenis') and instantiates it inside a useEffect hook. The initialization includes setting up a requestAnimationFrame loop to update the scroll position and returning a cleanup function to destroy the instance when the component unmounts.

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