How to Deploy a Custom Build of Stremio-Web: A Complete Production Guide

Deploying a custom build of Stremio-Web requires compiling the React application with webpack, then serving the generated assets using the built-in Express server (http_server.js) or a production-ready Docker container.

Stremio-Web is the browser-based interface for the Stremio media center, implemented as a single-page React application bundled by webpack. If you need to customize the UI, inject environment-specific configurations, or host a private instance, you must know how to deploy a custom build of stremio-web from the official source repository. This guide covers the complete pipeline from dependency installation to production deployment, referencing actual file paths and build scripts from the Stremio/stremio-web codebase.

Prerequisites and Environment Setup

Before building, ensure your environment meets the baseline requirements defined in package.json and the Dockerfile. Stremio-Web uses pnpm as its package manager and requires Node.js 12 or higher (Node.js 20 is used in the official Docker images).

Clone the repository and switch to the active development branch:

git clone https://github.com/Stremio/stremio-web.git
cd stremio-web
git checkout development

Install all dependencies using pnpm:

pnpm install

This command installs both the runtime dependencies and the webpack toolchain required to compile the application.

Building the Production Bundle

The build process is orchestrated by webpack.config.js, which compiles the React source code, processes CSS, and generates hashed asset filenames for cache busting.

Run the production build:

pnpm run build

Webpack writes the output to build/<commit-hash>/, creating a directory structure that includes:

• index.html – The SPA entry point that loads the bundled assets
• scripts/main.js – The compiled React application code (src/index.js)
• scripts/worker.js – The Web Worker for core functionality (@stremio/stremio-core-web/worker.js)
• styles/main.css – Compiled CSS assets
• Images, fonts, and WebAssembly binaries as needed

The commit hash subdirectory ensures unique URLs for each build, preventing stale cached assets from being served to users.

Deployment Options

Once the build completes, you can deploy the compiled assets using one of three methods.

Option 1: Built-in Express Server

The repository includes a minimal Express server in http_server.js that serves the static files with appropriate cache-control headers. This is the fastest way to verify or run a production build locally.

Start the server:

node http_server.js

By default, the server listens on port 8080 (defined by the HTTP_PORT constant). It applies long-term caching headers—approximately 7200 seconds for index.html and one month for other assets (see lines 15-19 of http_server.js)—to optimize performance while ensuring the entry point updates relatively quickly.

For production use behind a reverse proxy (nginx, Caddy, or Traefik), run this server and proxy traffic to port 8080. The Express server handles the SPA routing by serving index.html for unknown routes, ensuring client-side navigation works correctly.

Option 2: Docker Deployment

For reproducible, isolated deployments suitable for CI/CD pipelines, use the multi-stage Dockerfile provided in the repository root.

Build the image:

docker build -t stremio-web:custom .

Run the container:

docker run -p 8080:8080 stremio-web:custom

The Dockerfile performs a multi-stage build:

1. Base stage: Sets up Node.js 20-alpine with pnpm installed
2. App stage: Installs dependencies and executes pnpm build to generate the build/ directory
3. Server stage: Installs only the minimal express runtime dependency
4. Final stage: Copies the compiled build/ folder and http_server.js into a clean image, exposing port 8080 and running node http_server.js

This approach bundles only the compiled assets and the lightweight Express runtime, resulting in a small production image that contains no build tools or source code.

Option 3: External Static Hosting

If you prefer hosting on CloudFront, Netlify, Vercel, or nginx, simply upload the contents of build/<commit-hash>/ to your static file host. Configure your server to:

• Serve index.html for all unmatched routes (SPA fallback)
• Respect the cache-control headers or set long-term caching for hashed assets
• Support HTTPS, as the application expects secure contexts for certain features

The webpack build includes a Service Worker generated by WorkboxPlugin that precaches static assets, enabling offline functionality once the initial load completes.

Configuration and Asset Management

When deploying a custom build, consider these technical details from the source architecture:

Cache Busting: The ${COMMIT_HASH} variable in webpack.config.js injects the Git commit hash into the output path. This ensures each deployment has unique URLs, forcing browsers to download new assets rather than using stale cached versions.

Environment Variables: The webpack configuration uses webpack.EnvironmentPlugin to inject values at compile time. Pass custom build arguments when building the Docker image:

docker build --build-arg API_URL=https://custom.api.com -t stremio-web:custom .

Service Worker: Production builds automatically generate a Service Worker via Workbox that precaches all static assets under the commit-hash path. This enables offline access and improves load times for returning users.

Key Architecture Files

Understanding these core files helps troubleshoot deployment issues:

• webpack.config.js: Defines the build pipeline, entry points (src/index.js and the core-web worker), asset hashing, and Workbox integration
• http_server.js: Minimal Express server that serves the build/ directory with proper cache headers and SPA routing
• Dockerfile: Multi-stage container definition that creates a production-ready image
• package.json: Contains npm scripts (start, build, docker) and dependency definitions
• src/index.js: The primary React application entry point

Summary

Deploying a custom Stremio-Web build involves three core steps:

• Prepare the source by installing dependencies with pnpm and running the webpack build via pnpm run build
• Package the assets from the build/<commit-hash>/ directory, either copying them to a web server or building a Docker image
• Serve the application using the built-in Express server (http_server.js) on port 8080, or deploy to any static host capable of SPA routing

The commit-hash directory structure prevents caching issues, while the optional Service Worker enables offline functionality for deployed instances.

Frequently Asked Questions

What Node.js version is required to build Stremio-Web?

The build requires Node.js 12 or higher, though the official Dockerfile uses Node.js 20-alpine. Using Node.js 20 ensures compatibility with the latest pnpm version and build dependencies specified in package.json.

Can I deploy Stremio-Web without using Docker?

Yes. After running pnpm run build, you can serve the build/<commit-hash>/ directory using any static file server. The repository includes http_server.js—a minimal Express server that you can start with node http_server.js—or you can use nginx, Apache, or cloud static hosting providers like Netlify or Vercel.

How does the cache-busting mechanism work?

Webpack outputs all compiled assets to a directory named after the current Git commit hash (e.g., build/abc123/). This unique path ensures that browsers treat each deployment as a distinct resource, eliminating stale JavaScript or CSS cache issues while allowing long-term caching headers for performance.

Where is the Service Worker generated during the build?

The Service Worker is automatically generated by the WorkboxPlugin defined in webpack.config.js during production builds. It precaches all static assets in the build directory, enabling offline functionality. The worker registers when users load the application and caches assets under the commit-hash path defined by the build output.

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