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:
Local Development Setup
Follow these steps to get the project running on your machine:
- Fork the repository on GitHub.
- Clone your fork locally:
git clone https://github.com/your-username/embla-carousel.git cd embla-carousel - Install dependencies:
pnpm install - 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 #123syntax. - 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.