# How to Contribute to the Stremio Web Project: A Complete Developer's Guide

> Contribute to the stremio-web project with this developer's guide. Learn how to fork the repository, set up your environment, and submit pull requests to help build Stremio.

- Repository: [Stremio/stremio-web](https://github.com/Stremio/stremio-web)
- Tags: how-to-guide
- Published: 2026-05-23

---

**Yes, anyone can contribute to the Stremio Web project by forking the repository, setting up a local development environment with Node 12+ and pnpm, and following the standard GitHub pull request workflow.**

Stremio Web is an open-source React front-end for the Stremio media center that welcomes community contributions. The codebase is written in modern JavaScript and follows standard open-source practices with clear architectural patterns. Whether you want to fix bugs, add features, or improve documentation, understanding the project structure is essential for submitting successful pull requests.

## Prerequisites and Environment Setup

Before you can contribute to the stremio-web project, you need to configure your local development environment. The build system requires **Node.js version 12 or higher** and **pnpm version 10 or higher**.

Install dependencies and start the development server:

```bash
pnpm install
pnpm start

```

The `pnpm start` command launches a hot-reload development server. To verify your setup works correctly, run the test suite with `pnpm test` and check code style with `pnpm lint` before submitting any changes.

## Understanding the Architecture

The Stremio Web application follows a modular React architecture centered around dependency injection, custom routing, and reusable hooks.

### Core Application Structure

The entry point for the application is [`src/App/App.js`](https://github.com/Stremio/stremio-web/blob/main/src/App/App.js). This root component wires together platform services like Chromecast and Gamepad support, global UI providers (Toast, Tooltip, Fullscreen), and the main router configuration.

Understanding this file is crucial because it demonstrates how services and UI state propagate throughout the component tree.

### Service Layer and Dependency Injection

Stremio Web implements a lightweight dependency injection system located in `src/services/ServicesContext`. The `ServicesProvider` component supplies platform-specific objects such as `Chromecast` to the entire application through React context.

Access these services in any component using the `useServices` hook exported from [`src/services/index.js`](https://github.com/Stremio/stremio-web/blob/main/src/services/index.js). This pattern keeps platform integrations testable and decoupled from UI components.

### Routing System

The application uses a custom router implementation (`stremio-router`) configured in `src/router/Router` and [`src/App/routerViewsConfig.js`](https://github.com/Stremio/stremio-web/blob/main/src/App/routerViewsConfig.js). Routes are defined as JavaScript modules under `src/routes/*`, including views like `Discover`, `Library`, and `MetaDetails`.

The router parses URL hash fragments and renders the appropriate view components based on the configuration object in [`routerViewsConfig.js`](https://github.com/Stremio/stremio-web/blob/main/routerViewsConfig.js).

### Common Hooks and Utilities

Reusable business logic lives in `src/common/`. Key hooks include:

- **`useTranslate`** – Handles internationalization and text rendering
- **`useProfile`** – Accesses user profile data and settings
- **`useStreamingServer`** – Manages connections to local streaming servers

These hooks encapsulate API interactions and state management, making them essential tools for new feature development.

## Types of Contributions

The project accepts several categories of contributions, from simple UI tweaks to complex feature implementations.

### Bug Fixes and UI Improvements

Locate components in `src/components/` for shared UI elements or `src/routes/` for page-specific views. Most styling uses CSS modules co-located with component files.

When fixing bugs, add regression tests in the `tests/` directory to prevent future breakage.

### New Features and Routes

To add a new page, create a component under `src/routes/` and register it in [`src/App/routerViewsConfig.js`](https://github.com/Stremio/stremio-web/blob/main/src/App/routerViewsConfig.js). For example, adding a Favorites page:

```javascript
// src/routes/Favorites/index.js
import React from 'react';
import { useServices } from 'stremio/services';

const Favorites = () => {
    const { library } = useServices();
    const favItems = library.getFavorites();
    return (
        <div className="favorites">
            <h1>My Favorites</h1>
            {/* Render favorite items */}
        </div>
    );
};

export default Favorites;

```

Register the route in the configuration:

```javascript
// src/App/routerViewsConfig.js
module.exports = {
    // existing routes...
    '/favorites': require('stremio/routes/Favorites'),
};

```

### Testing and Documentation

The project uses **Jest** for unit testing. Write tests for new hooks and components to maintain coverage standards.

Access profile data in tests using the hooks:

```javascript
// tests/useProfile.test.js
import { renderHook } from '@testing-library/react-hooks';
import { useProfile } from 'stremio/common';

test('useProfile returns default object', () => {
    const { result } = renderHook(() => useProfile());
    expect(result.current).toMatchObject({ 
        name: expect.any(String) 
    });
});

```

## Step-by-Step Contribution Workflow

Follow this process to submit your work:

1. **Fork the repository** on GitHub and clone your fork locally
2. **Create a feature branch** with a descriptive name (e.g., `fix-player-controls` or `add-keyboard-shortcuts`)
3. **Implement your changes** following the architectural patterns described above
4. **Run quality checks**: execute `pnpm test` to run Jest and `pnpm lint` to check code style
5. **Commit with clear messages** explaining what changed and why
6. **Push to your fork** and open a Pull Request against the `development` branch
7. **Respond to review feedback** from maintainers who will verify your changes against CI pipelines defined in `.github/workflows/`

All contributors must adhere to the community guidelines outlined in [`CODE_OF_CONDUCT.md`](https://github.com/Stremio/stremio-web/blob/main/CODE_OF_CONDUCT.md).

## Code Standards and Testing

Maintain consistency with the existing codebase by following these standards:

- Use functional React components and hooks rather than class components
- Import shared utilities from `stremio/common` and `stremio/services` rather than relative paths when possible
- Wrap component-specific styles in CSS modules
- Add TypeScript-style JSDoc comments for complex functions

The CI pipeline automatically runs on every pull request, executing the test suite and linting rules defined in the webpack configuration.

## Summary

- Stremio Web accepts contributions from anyone willing to follow the standard open-source workflow
- Development requires Node 12+, pnpm 10+, and uses a hot-reload server for local testing
- The architecture centers on [`src/App/App.js`](https://github.com/Stremio/stremio-web/blob/main/src/App/App.js) for bootstrapping, `src/services/` for dependency injection, and custom routing via `src/router/`
- New features typically involve creating route components in `src/routes/` and registering them in [`src/App/routerViewsConfig.js`](https://github.com/Stremio/stremio-web/blob/main/src/App/routerViewsConfig.js)
- Always run `pnpm test` and `pnpm lint` before submitting pull requests to ensure CI passes
- Community interaction is governed by the [`CODE_OF_CONDUCT.md`](https://github.com/Stremio/stremio-web/blob/main/CODE_OF_CONDUCT.md) file

## Frequently Asked Questions

### What programming skills do I need to contribute?

You need proficiency in **JavaScript (ES6+)** and **React** fundamentals. Experience with webpack build systems and CSS modules is helpful but not required. Understanding of media streaming protocols is beneficial for advanced features but not necessary for UI improvements or bug fixes.

### How do I test my changes locally?

Run `pnpm start` to launch the development server with hot reloading. For specific functionality, use `pnpm test` to execute the Jest suite or `pnpm test --watch` during active development. Test against different routes by navigating to hash-based URLs like `/#/discover` or `/#/library`.

### Where can I find good first issues?

Check the GitHub Issues tab for labels like `good first issue` or `help wanted`. These typically involve UI tweaks in `src/components/`, documentation improvements, or minor bug fixes in existing routes. Starting with the `src/common/` hooks or adding test coverage provides safe entry points into the codebase.

### What is the code review process?

Maintainers review pull requests against the `development` branch, checking for architectural consistency, test coverage, and adherence to the code of conduct. The CI pipeline in `.github/workflows/` automatically validates builds, tests, and linting. Expect feedback within a few days, with faster responses for smaller, focused changes.