Handling Smooth Scroll Libraries Like Lenis in Cloned Projects: AI Website Cloner Template Guide

The AI Website Cloner Template automatically detects Lenis smooth-scroll implementations by scanning for the .lenis CSS class and injects a singleton initialization pattern into the generated Next.js project to preserve pixel-perfect scrolling fidelity.

When cloning websites that rely on Lenis or similar smooth-scroll libraries, maintaining the exact scrolling behavior is critical for user experience fidelity. The JCodesMore/ai-website-cloner-template provides a systematic workflow for detecting, installing, and wiring these libraries into the generated Next.js code. This ensures that handling smooth scroll libraries like Lenis in cloned projects retains the fluid motion and timing of the original site.

How Detection Works in the Cloning Pipeline

The template embeds detection logic directly into its platform-specific skill instructions. When the AI inspects a target website, it searches the DOM for specific CSS signatures that indicate smooth-scroll libraries are active.

Scanning for the Lenis Class Signature

In .windsurf/workflows/clone-website.md and .opencode/commands/clone-website.md, the cloning instructions explicitly check for the .lenis class on scroll containers. This selector is the primary signature that triggers the Lenis integration workflow.

When the detection finds .lenis in the inspected HTML or CSS, the pipeline automatically adds Lenis to the list of required third-party packages. The instructions also append a reminder to the global CSS and build configuration: "Don't forget smooth scroll libraries. Check for Lenis (.lenis class)".

Installing and Initializing Lenis in Next.js

Once detection is complete, the template generates a complete integration pattern for the Next.js application. This involves three distinct steps that ensure the library runs efficiently as a singleton instance.

Package Installation

The cloning agent inserts an npm install lenis command into the generated project's README. You can also run this manually in the project root:

npm install lenis

Creating the Singleton Utility

The template generates src/lib/lenis.ts to create a reusable singleton instance. This prevents duplicate initializations during React component re-renders and provides a single source of truth for the scroll controller.

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

let lenis: Lenis | null = null;

export function useLenis() {
  useEffect(() => {
    if (!lenis) {
      lenis = new Lenis({
        // Mirror the original site's configuration if captured
        duration: 1.2,
        easing: (t: number) => Math.min(1, 1.001 - Math.pow(2, -10 * t)),
        smooth: true,
      });
    }

    const raf = () => {
      lenis?.raf(Date.now());
      requestAnimationFrame(raf);
    };
    requestAnimationFrame(raf);

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

Hooking Into the Root Layout

The initialization hooks into src/app/layout.tsx to ensure smooth scrolling applies globally across all routes. The component imports the useLenis hook and invokes it at the top level:

import './globals.css';
import { useLenis } from '@/lib/lenis';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  useLenis();

  return (
    <html lang="en" className="lenis">
      <body>{children}</body>
    </html>
  );
}

The className="lenis" attribute mirrors the original site's DOM structure, ensuring that any CSS selectors targeting .lenis continue to function correctly.

Why Preserving Smooth Scroll Matters

Browser-native scrolling lacks the inertia and easing curves that libraries like Lenis provide. Omitting the library from a cloned project creates "jumpy" scroll behavior that breaks the pixel-perfect fidelity goal of the cloner. By automatically detecting and wiring the library, the template ensures that clones retain the exact timing and feel of the source site's user experience.

Complete Implementation Example

Combine the detection, installation, and initialization steps to restore the full smooth-scroll behavior:

1. Detection phase – The agent finds .lenis in .windsurf/workflows/clone-website.md rules
2. Installation – Run npm install lenis or trust the generated README
3. Utility creation – Add the singleton code to src/lib/lenis.ts
4. Layout integration – Import and call useLenis() in src/app/layout.tsx
5. CSS preservation – Copy any scroll-related styles from the source into src/app/globals.css:

/* src/app/globals.css - generated from inspection */
.lenis {
  /* Original site scroll container styles */
}

Summary

• Detection: The template scans for .lenis class signatures in .windsurf/workflows/clone-website.md and .opencode/commands/clone-website.md during the cloning process.
• Installation: Automatically adds npm install lenis to the generated project instructions.
• Initialization: Creates a singleton utility in src/lib/lenis.ts and hooks it into src/app/layout.tsx via a custom React hook.
• Fidelity: Preserves the exact scrolling physics and timing of the original website to maintain pixel-perfect user experience.

Frequently Asked Questions

How does the AI Website Cloner detect Lenis?

The cloner inspects the target site's HTML and CSS for the specific .lenis class that the library adds to the scroll container. This detection is defined in the workflow instructions at .windsurf/workflows/clone-website.md and .opencode/commands/clone-website.md, which guide the AI to record the finding and add Lenis to the dependency list.

Where is the Lenis initialization code placed?

The initialization logic resides in two generated files: src/lib/lenis.ts contains the singleton instance and useLenis hook, while src/app/layout.tsx imports and executes this hook to activate smooth scrolling across the entire Next.js application.

Can I customize the Lenis configuration?

Yes. The src/lib/lenis.ts utility exposes the standard Lenis constructor options. You can adjust duration, easing, orientation, and other parameters to match the exact values used by the original site, ensuring the cloned project replicates the source's scrolling physics.

What if the original site uses Locomotive Scroll instead?

The detection workflow in .windsurf/workflows/clone-website.md can be extended to check for Locomotive Scroll signatures (such as data-scroll-container attributes). While the template specifically mentions Lenis detection, the same pattern—identifying library-specific DOM markers—applies to any smooth-scroll library you encounter during cloning.

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