Contributing Guide

Getting Started

Thank you for your interest in contributing to Embla Carousel! This project is a monorepo managed with pnpm, containing the core library, framework wrappers (React, Vue, Svelte, etc.), and the documentation site.

Prerequisites

To contribute to this project, ensure you have the following installed:

• Node.js (LTS version recommended)
• pnpm (used for managing the monorepo workspace)

Local Development Setup

Follow these steps to get the project running on your machine:

1. Fork the repository on GitHub.
2. Clone your fork locally:

   git clone https://github.com/your-username/embla-carousel.git
   cd embla-carousel
   

3. Install dependencies:

   pnpm install
   

4. Build the packages: Since the packages depend on each other, you need to run an initial build:

   pnpm run build
   

Running the Documentation Site

The documentation site is the best place to test your changes in a real-world environment.

pnpm run dev:docs

This will start the Gatsby-based documentation server at http://localhost:8000.

Development Workflow

Embla Carousel is organized into several packages under the packages/ directory:

• embla-carousel: The core engine (TypeScript).
• embla-carousel-react: The React wrapper.
• embla-carousel-autoplay: Official plugins.

Making Changes

When modifying the core library or plugins, use the watch mode to ensure changes are compiled as you work:

# Watch core library
pnpm run dev --filter embla-carousel

Code Quality

Before submitting your code, ensure it meets the project's quality standards:

• Linting: Check for code style issues.

  pnpm run lint
  

• Type Checking: Ensure all TypeScript types are valid.

  pnpm run check-types
  

• Testing: Run the test suite.

  pnpm run test
  

Submitting a Pull Request

Once your changes are ready, follow these steps to submit them for review:

1. Create a Branch

Always create a descriptive branch name for your work:

git checkout -b feat/add-new-option
# or
git checkout -b fix/issue-description

2. Commit Your Changes

We follow standard community commit guidelines. Ensure your commit messages are clear and describe the intent of the change.

3. Open a Pull Request

• Navigate to the Embla Carousel repository.
• Click Compare & pull request.
• Provide a detailed description of your changes. If your PR fixes an existing issue, link it using the Closes #123 syntax.
• Ensure all CI checks (Linting, Tests, Build) pass.

Contribution Guidelines

• Stay Framework-Agnostic: If you are adding a feature to the core, ensure it does not rely on any specific framework (React, Vue, etc.) or DOM environment that isn't available in all modern browsers.
• Performance Matters: Embla is built to be lightweight. Avoid adding large dependencies or high-overhead logic.
• Documentation: If your change introduces a new feature or changes an API, please update the relevant documentation files within the docs/ directory.