Skip to main content
HLS Downloader is built with modern web technologies using a monorepo architecture. This guide introduces the core technologies and helps you set up your development environment.

​
Tech stack

The extension leverages a powerful combination of technologies for performance, type safety, and maintainability:

​
Core technologies

TypeScript

Strongly-typed language providing compile-time safety across all packages

pnpm workspace

Efficient monorepo management with shared dependencies and parallel builds

Vite

Lightning-fast build tool for development and production bundles

Vitest

Modern testing framework with built-in coverage reporting

​
Architecture layers

Business logic layer built with:
  • Redux + Redux Toolkit for state management
  • RxJS + redux-observable for async operations and side effects
  • TypeScript for compile-time type safety
All domain logic lives here as pure functions and use cases.
Extension background script that:
  • Initializes the Redux store
  • Wires services like IndexedDBFS, FetchLoader, and M3u8Parser
  • Integrates ffmpeg.wasm for local video merging
  • Handles extension lifecycle events
Shared UI component library:
  • Radix UI primitives for accessible components
  • Tailwind CSS + tailwindcss-animate for styling
  • Lucide React icons
  • Reusable components consumed by the popup
Static resources:
  • Extension manifests (MV2 and MV3)
  • Icons in multiple sizes
  • FFmpeg WebAssembly files

​
Prerequisites

Before you begin, ensure you have the following installed:
1

Node.js 20+

Download from nodejs.org. Includes Corepack for managing package managers.
node --version  # should be 20.0.0 or higher
2

Enable Corepack

Corepack manages the pinned pnpm version automatically:
corepack enable
corepack prepare pnpm@10.11.0 --activate
3

zip command

Required for creating extension archives. Usually pre-installed on macOS and Linux.On Windows, install via Git for Windows or use WSL.

​
Quick start

1

Clone the repository

git clone https://github.com/puemos/hls-downloader.git
cd hls-downloader
2

Install dependencies

pnpm install --frozen-lockfile
The --frozen-lockfile flag ensures you install exact dependency versions matching the lock file.
3

Build the extension

pnpm run build
This creates:
  • dist/ directory with extension files
  • extension-chrome.zip for Chromium browsers
  • extension-firefox.xpi for Firefox
4

Clean up artifacts

pnpm run clean
Never commit build artifacts (dist/, *.zip, *.xpi). They’re listed in .gitignore.

​
Manifest versions

HLS Downloader supports both Manifest V2 and V3:
Manifest V2 (default): Used for Firefox and legacy Chromium workflows. Supports background pages.Manifest V3: Required for modern Chromium browsers (Chrome, Edge, Brave, Arc). Uses service workers and offscreen documents.
The default build targets MV2. To build for MV3: 
MV_TARGET=mv3 pnpm run build
See the Building guide for detailed build commands and variants.

​
Project structure

The monorepo is organized as a pnpm workspace: 
hls-downloader/
├── src/
│   ├── core/              # Business logic & Redux store
│   │   ├── src/
│   │   │   ├── controllers/  # Redux epics & orchestration
│   │   │   ├── entities/     # Domain models
│   │   │   ├── services/     # Service interfaces
│   │   │   ├── store/        # Redux slices & reducers
│   │   │   ├── use-cases/    # Business operations
│   │   │   └── utils/        # Helper functions
│   │   └── lib/           # Generated TypeScript output
│   │
│   ├── background/        # Extension background script
│   │   └── src/
│   │       ├── listeners/    # Event handlers
│   │       └── services/     # Service implementations
│   │
│   ├── popup/             # React UI
│   │   ├── src/
│   │   │   ├── components/   # React components
│   │   │   └── modules/      # Feature modules
│   │   └── .storybook/    # Storybook configuration
│   │
│   ├── design-system/     # UI component library
│   │   └── src/
│   │       ├── components/   # Reusable components
│   │       ├── hooks/        # Custom React hooks
│   │       └── lib/          # Utilities
│   │
│   └── assets/            # Static resources
│       └── assets/
│           ├── icons/        # Extension icons
│           └── ffmpeg/       # FFmpeg WebAssembly files
│
├── scripts/               # Build and utility scripts
├── package.json           # Root workspace configuration
├── pnpm-workspace.yaml    # Workspace definition
└── tsconfig.json          # TypeScript configuration
The src/core/lib directory is generated by TypeScript compilation. Never edit it directly - always modify files in src/core/src.

​
Next steps

Architecture

Learn about clean architecture patterns and package boundaries

Building

Explore build commands, variants, and watch mode

Testing

Run tests and generate coverage reports

Contributing

Guidelines for submitting pull requests

Build docs developers (and LLMs) love

Get started for freeTalk to us