How to Set Up the Stremio Web Development Environment: Complete Setup Guide

Setting up the Stremio Web development environment requires Node.js v12+, pnpm v10+, and running pnpm install followed by pnpm start to launch the HTTPS dev server on localhost:8080 with hot reloading disabled for deterministic builds.

The Stremio Web client is a React 18 application that streams media through a sophisticated build pipeline managed by Webpack. This guide explains how to configure the Stremio Web development environment using the official build scripts and configuration files from the Stremio/stremio-web repository.

Prerequisites

Before cloning the repository, ensure your system meets the baseline requirements defined in the project README.md. You must have Node.js v12 or higher and pnpm v10 or higher installed. The project explicitly requires pnpm rather than npm or yarn for dependency management.

Initial Setup

Clone the repository and install all third-party dependencies declared in package.json. The dependency list includes React 18, i18next for localization, and core Stremio libraries such as @stremio/stremio-core-web and @stremio/stremio-video.

git clone https://github.com/Stremio/stremio-web.git
cd stremio-web
pnpm install

This command populates node_modules with runtime dependencies and development tools including Babel, TypeScript, ESLint, Jest, and the Webpack toolchain.

Development Workflow

Start the local development server using the predefined script in package.json. This command executes webpack serve --mode development as configured in the scripts block.

pnpm start

The Webpack Dev Server automatically serves the application over HTTPS on port 8080. According to the configuration in webpack.config.js, hot module reloading is explicitly disabled (hot: false) to maintain a deterministic development environment. The server proxies requests and serves the entry point defined at src/index.js.

Build System Architecture

The webpack.config.js file defines the entire compilation pipeline and asset management strategy for the Stremio Web development environment.

Entry Points and Output Structure

Webpack processes two primary entry points: the main UI at src/index.js and the Core Web worker from @stremio/stremio-core-web/worker.js. The output directory follows a unique pattern: build/<COMMIT_HASH>/..., where the commit hash is injected from the current Git state via the COMMIT_HASH constant defined at line 15 of the configuration.

Transpilation Pipeline

JavaScript files undergo processing through Babel with @babel/preset-env and @babel/preset-react presets. TypeScript files route through ts-loader, while Less stylesheets compile to CSS via less-loader and MiniCssExtractPlugin. To accelerate builds, the configuration implements thread-loader pre-warmed at lines 25-34, which parallelizes transpilation across available CPU cores.

Environment Variables and Plugins

The EnvironmentPlugin injects critical build-time variables into the bundle, including VERSION, COMMIT_HASH, and SENTRY_DSN (lines 12-19). For production optimizations, WorkboxPlugin generates a Service Worker that precaches assets, while CopyWebpackPlugin handles static files like favicons and .well-known directory contents. The HtmlWebPackPlugin generates the final HTML from the template at src/index.html.

Application Initialization

The src/index.js file serves as the application bootstrap, executing several essential tasks before React mounts the interface.

Error Tracking and Browser Detection

The script conditionally initializes Sentry error tracking when process.env.SENTRY_DSN is present. It then uses the bowser library to detect browser capabilities and adjust the viewport meta tag specifically for desktop browsers.

Internationalization Setup

Translations load from the stremio-translations package, with i18next configured to default to en-US. This setup occurs before the React tree mounts to ensure localized strings are available immediately.

React Mounting and Service Workers

The code creates a React root using ReactDOM.createRoot and wraps the App component with context providers including PlatformProvider, CoreProvider, and FileDropProvider. Finally, it registers service-worker.js automatically in production builds unless disabled via the SERVICE_WORKER_DISABLED environment variable.

Production Builds

Generate an optimized production bundle using the build script, which executes webpack --mode production.

pnpm run build

This emits minified assets to ./build/<commit>/... and enables source maps via devtool: 'source-map' (line 38). The WorkboxPlugin creates a precaching Service Worker that enables offline functionality for deployed applications.

Testing and Code Quality

Run the automated test suite and lint checks against the src directory using the following commands:

pnpm test              # Executes Jest tests

pnpm lint              # Runs ESLint against src/

pnpm scan-translations # Custom Jest test for missing i18n keys

The scan-translations script is particularly useful when adding new UI strings, as it validates that all translation keys exist in the localization files.

Summary

• Prerequisites: Node.js v12+ and pnpm v10+ are required to run the Stremio Web development environment.
• Entry Files: The build system targets src/index.js and the Core Web worker as dual entry points.
• Dev Server: Runs on HTTPS port 8080 with pnpm start, featuring disabled HMR for stable development.
• Configuration: webpack.config.js manages transpilation via Babel and ts-loader, parallelized with thread-loader.
• Production: pnpm run build outputs versioned assets to build/<COMMIT_HASH>/ with Service Worker precaching.
• Code Quality: ESLint, Jest, and translation scanning ensure code standards and complete localization.

Frequently Asked Questions

What Node.js version is required for Stremio Web development?

The project requires Node.js v12 or higher, though newer LTS versions are recommended for compatibility with modern pnpm features. This requirement is explicitly listed in the README prerequisites section.

Why does the development server use HTTPS on localhost?

The Webpack Dev Server configuration explicitly sets server: 'https' to mirror production security contexts, particularly for testing Service Worker functionality and secure media APIs that require encrypted contexts. The server runs on port 8080 with hot reloading disabled to ensure deterministic behavior.

How do I add new translations to the Stremio Web UI?

Add your key-value pairs to the appropriate JSON files in the stremio-translations package, then run pnpm scan-translations to validate that all keys are properly referenced in the source code. The i18n system initializes in src/index.js with a default language of en-US.

What is the purpose of the Core Web worker in the build?

The Core Web worker (@stremio/stremio-core-web/worker.js) runs as a separate entry point to handle Stremio's core logic off the main thread, preventing UI blocking during intensive operations like torrent streaming or metadata fetching. This architecture ensures the React interface remains responsive while the core processes media streams.

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