Installation & Setup

ScrollBooster is distributed via the npm registry and is designed to work in modern module-based architectures as well as traditional script-tag inclusions.

Using a Package Manager (Recommended)

For modern web applications utilizing bundlers like Webpack, Rollup, or Vite, installing via a package manager is the standard approach.

Using npm:

npm install scrollbooster

Using Yarn:

yarn add scrollbooster

Once installed, you can import the library into your JavaScript or TypeScript environment. ScrollBooster exposes a default export:

import ScrollBooster from 'scrollbooster';

Using a Script Tag (CDN)

If your project does not use a build step, you can include ScrollBooster directly in your HTML using the Unpkg CDN.

This method exposes the ScrollBooster class on the global window object.

<!-- Include the minified script before your custom JavaScript -->
<script src="https://unpkg.com/[email protected]/dist/scrollbooster.min.js"></script>

<script>
    // ScrollBooster is now available globally
    const sb = new ScrollBooster({ /* options */ });
</script>

Best Practice: Always pin your CDN links to a specific major/minor version (e.g., @3.0.2) to prevent unexpected breaking changes when new versions are released.

Environment Requirements & Polyfills

Modern JavaScript vs. Legacy Browsers

ScrollBooster's source code utilizes modern ES6+ syntax (classes, arrow functions, template literals).

If you are using the pre-built dist/scrollbooster.min.js file, it has already been transpiled down to ES5 via Babel (as defined in the project's internal .babelrc). This ensures out-of-the-box compatibility with Internet Explorer 11.

However, if you are importing the source directly (src/index.js), you must ensure your build pipeline (e.g., Babel, swc) is configured to transpile the code for your target browsers.

Server-Side Rendering (SSR) Pitfalls

ScrollBooster relies heavily on browser-specific APIs, specifically window, document, and DOM Event Listeners.

If you are using a framework that executes code on the server (like Next.js, Nuxt.js, or Gatsby), you will encounter a ReferenceError: window is not defined if you attempt to instantiate ScrollBooster on the server.

Troubleshooting SSR: Ensure instantiation only happens on the client side.

In React / Next.js:

import { useEffect, useRef } from 'react';
import ScrollBooster from 'scrollbooster';

export default function DraggableMap() {
    const viewportRef = useRef(null);
    const contentRef = useRef(null);

    useEffect(() => {
        // This code only runs in the browser after the component mounts
        const sb = new ScrollBooster({
            viewport: viewportRef.current,
            content: contentRef.current,
            scrollMode: 'transform'
        });

        return () => {
            // Crucial: Clean up event listeners when component unmounts
            sb.destroy(); 
        };
    }, []);

    return (
        <div ref={viewportRef}>
            <div ref={contentRef}>...</div>
        </div>
    );
}

Next Steps

Now that the library is successfully included in your project, proceed to the Quick Start guide to create your first draggable interface.