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

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:

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. 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. 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. 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.

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. For example, adding a Favorites page:

// 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:

// 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:

// 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.

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 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
• 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}