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

> Discover how the AI Website Cloner detects and configures smooth scroll libraries like Lenis and Locomotive Scroll automatically. Get seamless scrolling in your Next.js projects.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: how-to-guide
- Published: 2026-07-07

---

**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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/layout.tsx) and CSS overrides in [`src/app/globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main//.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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main//.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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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:

```bash

# 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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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.

```tsx
// 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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/globals.css) to normalize the experience:

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

```

As noted in [`/.windsurf/workflows/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main//.windsurf/workflows/clone-website.md) at lines 135-136, the builder must "Add these to [`globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main//.windsurf/workflows/clone-website.md).
- **Documentation**: Findings are recorded in [`docs/research/BEHAVIORS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/layout.tsx).
- **CSS normalization**: Required overrides like `html { scroll-behavior: auto; }` are injected into [`src/app/globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main//.windsurf/workflows/clone-website.md) and [`/.opencode/commands/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main//.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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/BEHAVIORS.md), the initialization script is added to [`src/app/layout.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/layout.tsx) as a client-side effect, and the CSS overrides are placed in [`src/app/globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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.