Skip to main content
We welcome contributions to HLS Downloader! This guide covers the contribution process, coding standards, and project conventions.

​
Getting started

1

Discuss your idea

Before writing code, discuss your proposed change:
  • Open an issue for bugs or feature requests
  • Comment on existing issues to volunteer
  • Reach out via email for major architectural changes
This helps avoid duplicate work and ensures your contribution aligns with project goals.
2

Fork and clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/hls-downloader.git
cd hls-downloader
3

Set up development environment

corepack enable
corepack prepare [email protected] --activate
pnpm install --frozen-lockfile
4

Create a feature branch

git checkout -b feature/my-awesome-idea
Use descriptive branch names:
  • feature/add-quality-filter
  • fix/download-button-crash
  • docs/update-build-instructions

​
Development workflow

1

Make your changes

Write code following the coding standards below.
Reference the AGENTS.md file for architecture-specific guidelines when implementing features.
2

Write tests

Add tests for new functionality:
# Run tests as you develop
pnpm --filter ./src/core run test -- --watch
See the Testing guide for details.
3

Test your changes

# Run all tests
pnpm test

# Build the extension
pnpm run build

# Load in browser and verify functionality
4

Update documentation

If your change affects usage or build steps, update README.md or other relevant docs.

​
Pull request process

1

Commit your changes

Use conventional commit messages:
git add .
git commit -m "feat: add playlist quality filter"
2

Push to your fork

git push origin feature/my-awesome-idea
3

Open a pull request

  1. Go to the main repository
  2. Click “Pull requests” → “New pull request”
  3. Select your fork and branch
  4. Fill out the PR template with:
    • Description of changes
    • Related issue numbers
    • Testing performed
    • Screenshots (if UI changes)
4

Address review feedback

Maintainers will review your PR and may request changes. Push additional commits to the same branch to update the PR.
5

Merge approval

Once approved by two maintainers, your PR will be merged. If you don’t have merge permissions, request a reviewer to merge it.
Ensure your PR:
  • Removes any build dependencies before completion
  • Updates version numbers following SemVer if applicable
  • Does not include build artifacts (dist/, *.zip, *.xpi)

​
Coding standards

​
Style guidelines

  • Use 2 spaces for indentation in all .ts, .tsx, .js, and .json files
  • Run Prettier before committing (if configured): 
    pnpm exec prettier --write "src/**/*.{ts,tsx}"
  • Enable strict mode in tsconfig.json
  • Prefer interface over type for object shapes
  • Use explicit return types for public functions: 
    // Good
export function calculateSize(segments: Segment[]): number {
  return segments.reduce((sum, s) => sum + s.size, 0);
}

// Avoid
export function calculateSize(segments: Segment[]) {
  return segments.reduce((sum, s) => sum + s.size, 0);
}
  • Avoid any - use unknown or specific types
  • Use functional components with hooks
  • Destructure props in function signature: 
    // Good
export const Button = ({ variant, children }: ButtonProps) => {
  return <button className={variant}>{children}</button>;
};

// Avoid
export const Button = (props: ButtonProps) => {
  return <button className={props.variant}>{props.children}</button>;
};
  • Keep components small and focused
  • Extract custom hooks for reusable logic
Order imports by category:
// 1. External dependencies
import React from 'react';
import { useDispatch } from 'react-redux';

// 2. Workspace packages
import { Button } from '@hls-downloader/design-system';
import { downloadActions } from '@hls-downloader/core';

// 3. Relative imports
import { formatSize } from '../utils';
import type { Playlist } from '../types';

​
Architecture guidelines

Follow the principles outlined in AGENTS.md:

Core package

  • Implement business logic as pure functions
  • Create use cases in src/core/src/use-cases/
  • Orchestrate with epics in src/core/src/controllers/
  • Never import from background, popup, or design-system

Background package

  • Initialize store and wire services
  • Implement service interfaces from core
  • Keep background scripts thin - delegate to core use cases
  • Handle browser extension APIs

Popup package

  • Build UI with components from design system
  • Connect to Redux store via react-redux
  • Keep components presentational when possible
  • Write Storybook stories for complex components

Design system

  • Create reusable, accessible components
  • Use Radix UI primitives as foundation
  • Style with Tailwind CSS
  • Document props and usage in Storybook
Never edit src/core/lib directly. It’s generated from TypeScript sources in src/core/src. The build process will overwrite your changes.

​
Commit guidelines

Use the conventional commit format: 
<type>: <summary>

[optional body]

[optional footer]

​
Commit types

  • feat: New feature for the user
  • fix: Bug fix for the user
  • docs: Documentation changes
  • style: Formatting, missing semicolons, etc. (no code change)
  • refactor: Refactoring production code
  • test: Adding or refactoring tests
  • chore: Updating build tasks, package manager configs, etc.

​
Examples

git commit -m "feat: add download button to sniffer tab"
For complex changes, add a body and footer:
git commit -m "feat: add playlist quality filter

Users can now filter playlists by resolution before downloading.

- Add quality selector component
- Implement filter logic in core
- Update UI to show filtered results

Closes #123"
Focus commit messages on why the change was made, not what changed (the diff shows that).

​
Testing requirements

1

Write unit tests

Cover new functionality with tests:
# Run tests for your package
pnpm --filter ./src/core run test
2

Ensure tests pass

# All tests must pass before PR submission
pnpm test
3

Check coverage

# Verify coverage hasn't dropped significantly
pnpm test:coverage
Aim for 80%+ coverage for new code. Complex UI components may have lower coverage.
See the Testing guide for detailed testing patterns.

​
Build artifact handling

Never commit build artifacts. The following are git-ignored:
  • dist/
  • dist-mv2/ and dist-mv3/
  • extension-chrome.zip
  • extension-firefox.xpi
  • extension-archive.zip
  • src/core/lib/ (generated TypeScript output)
Before committing, verify no artifacts are staged: 
git status

# If artifacts appear, they shouldn't - check .gitignore
Clean up after testing: 
pnpm run clean

​
Automation guidelines

If you’re using AI assistants or automation tools to contribute:
The AGENTS.md file contains specific instructions for automated contributions:
  • Where to implement features (use cases vs. epics)
  • How to organize code across packages
  • Build and test requirements
  • Artifact handling rules
Key points:
  • Install dependencies with pnpm install when necessary
  • Run pnpm test before submitting
  • Build with pnpm run build and verify output
  • Remove dist/ and archives after verification
  • Follow the commit message format strictly

​
Code of conduct

This project follows the Contributor Covenant Code of Conduct.
Our pledge: Create a harassment-free experience for everyone, regardless of:
  • Age, body size, disability
  • Ethnicity, gender identity and expression
  • Level of experience, education, socio-economic status
  • Nationality, personal appearance, race, religion
  • Sexual identity and orientation
Expected behavior:
  • Use welcoming and inclusive language
  • Be respectful of differing viewpoints
  • Accept constructive criticism gracefully
  • Focus on what’s best for the community
  • Show empathy toward others
Unacceptable behavior:
  • Sexualized language or imagery
  • Trolling, insults, or personal attacks
  • Public or private harassment
  • Publishing others’ private information
  • Other unprofessional conduct
Report unacceptable behavior to: [email protected]All complaints will be:
  • Reviewed and investigated promptly
  • Treated with confidentiality
  • Responded to appropriately
Maintainers may take corrective action including warnings, temporary bans, or permanent removal from the project.
TL;DR: Be kind. Treat others with respect and kindness.

​
Getting help

Issues

Ask questions or report problems

Discussions

Chat about ideas and features

Email

Contact maintainer: [email protected]

Documentation

Read development guides

​
Recognition

All contributors are recognized in the project’s contributor graph and release notes. Thank you for making HLS Downloader better!
Your contributions help thousands of users download HLS streams efficiently. We appreciate your time and effort.

​
Quick checklist

Before submitting a PR, verify:
  • Tests pass: pnpm test
  • Extension builds: pnpm run build
  • No build artifacts committed
  • Commit messages follow conventional format
  • Documentation updated if needed
  • Code follows style guidelines (2 spaces, TypeScript conventions)
  • Changes discussed in an issue (for large changes)
  • PR description explains changes and motivation
See you in the pull requests! We’re excited to review your contribution.

Build docs developers (and LLMs) love

Get started for freeTalk to us