Contributing to ScrollBooster

First off, thank you for considering contributing to ScrollBooster! It's an open-source, community-driven micro-library, and pull requests are highly welcome.

Whether you are fixing a bug, improving the documentation, or proposing a new physics feature, please follow the guidelines below to ensure a smooth review process.

1. Local Development Setup

To work on ScrollBooster locally, you will need Node.js and Yarn installed on your machine.

  1. Fork the repository on GitHub via the UI.

  2. Clone your fork to your local machine: 

    git clone https://github.com/YOUR_USERNAME/scrollbooster.git
cd scrollbooster

  3. Install dependencies using Yarn (the project utilizes a yarn.lock file, so Yarn is preferred over npm to ensure consistent dependency versions): 

    yarn install

2. Project Architecture

The project is extremely lightweight by design.

  • src/index.js: This is the only source file. It contains the entire physics engine, class definition, and event listener logic. Make all of your logic changes here.
  • dist/: Contains the minified, Babel-transpiled production code. Never edit files in this directory manually. They are auto-generated.
  • test/: Contains raw HTML/JS playground files used to verify functionality.

3. Running the Development Environment

The easiest way to test your changes in real-time is to use the included Webpack Dev Server and the provided test files.

  1. Run the development server: 

    yarn start

  2. Open your browser and navigate to http://localhost:8080/test/index.html (the CLI will confirm the exact port).

  3. You will see an interface testing various edge cases: "Native scroll test", "Horizontal only", "Without bounce", etc.
  4. As you make changes to src/index.js, the dev server will automatically reload the page.

Tip: If you want Webpack to just watch and recompile the files without starting a web server, you can run yarn dev.

4. Testing Methodology

ScrollBooster relies on manual visual regression and basic Mocha/Chai assertions in the browser.

When you open test/index.html, Mocha runs a suite of basic property checks (e.g., verifying scr.position.x equals 0 on init).

Visual Testing is Critical: Because this is a physics and touch-interaction library, automated testing cannot catch "bad feel" or "janky scrolling".

  • Test your changes with a standard mouse.
  • Test with a laptop trackpad (both vertical and horizontal swipes).
  • Test using Chrome DevTools Device Toolbar to simulate touch events.

5. Code Style & Formatting

We value clean, consistent code. The repository is equipped with Prettier and EditorConfig.

Before committing, ensure your code adheres to the rules defined in .prettierrc.js (4 spaces, single quotes, 120 print width). It is highly recommended to configure your code editor to "Format on Save" using Prettier.

6. Building and Committing

Once you are satisfied with your changes in src/index.js, you must generate the updated production files before submitting your Pull Request.

  1. Run the production build script: 

    yarn build
    This process pushes src/index.js through Babel, minifies it via Terser, and updates dist/scrollbooster.min.js and its corresponding sourcemap.

  2. Stage and commit your changes. Make sure you include the changes in the /dist directory. 

    git add src/index.js dist/
git commit -m "feat: Add dynamic friction calculation based on velocity"

7. Submitting a Pull Request

  1. Push your changes to your fork on GitHub.
  2. Open a Pull Request against the master branch of the original ilyashubin/scrollbooster repository.
  3. In your PR description, clearly explain:
    • The Problem: What bug are you fixing or what feature are you adding?
    • The Solution: How does your code fix it?
    • Testing: How did you test it? (e.g., "Tested on Mac trackpad and iOS Safari").

Thank you for helping make ScrollBooster better!