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

> Set up the awesome Stremio Web development environment fast. Follow this guide for Node.js, pnpm, and launching the HTTPS dev server with hot reloading disabled.

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

---

**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`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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`.

```bash
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`](https://github.com/Stremio/stremio-web/blob/main/package.json). This command executes `webpack serve --mode development` as configured in the `scripts` block.

```bash
pnpm start

```

The Webpack Dev Server automatically serves the application over HTTPS on port 8080. According to the configuration in [`webpack.config.js`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/src/index.js).

## Build System Architecture

The [`webpack.config.js`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/src/index.html).

## Application Initialization

The [`src/index.js`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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`.

```bash
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:

```bash
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`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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.