# How to Deploy a Custom Build of Stremio-Web: A Complete Production Guide > Learn how to deploy a custom build of Stremio-Web. Compile your React app with webpack and serve assets via Express or a Docker container for seamless production deployment. - Repository: [Stremio/stremio-web](https://github.com/Stremio/stremio-web) - Tags: how-to-guide - Published: 2026-05-23 --- **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`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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: ```bash git clone https://github.com/Stremio/stremio-web.git cd stremio-web git checkout development ``` Install all dependencies using pnpm: ```bash 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`](https://github.com/Stremio/stremio-web/blob/main/webpack.config.js), which compiles the React source code, processes CSS, and generates hashed asset filenames for cache busting. Run the production build: ```bash pnpm run build ``` Webpack writes the output to `build//`, creating a directory structure that includes: - [`index.html`](https://github.com/Stremio/stremio-web/blob/main/index.html) – The SPA entry point that loads the bundled assets - [`scripts/main.js`](https://github.com/Stremio/stremio-web/blob/main/scripts/main.js) – The compiled React application code ([`src/index.js`](https://github.com/Stremio/stremio-web/blob/main/src/index.js)) - [`scripts/worker.js`](https://github.com/Stremio/stremio-web/blob/main/scripts/worker.js) – The Web Worker for core functionality (`@stremio/stremio-core-web/worker.js`) - [`styles/main.css`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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: ```bash 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`](https://github.com/Stremio/stremio-web/blob/main/index.html)** and **one month for other assets** (see lines 15-19 of [`http_server.js`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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: ```bash docker build -t stremio-web:custom . ``` Run the container: ```bash 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`](https://github.com/Stremio/stremio-web/blob/main/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//` to your static file host. Configure your server to: - Serve [`index.html`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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: ```bash 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`](https://github.com/Stremio/stremio-web/blob/main/webpack.config.js)**: Defines the build pipeline, entry points ([`src/index.js`](https://github.com/Stremio/stremio-web/blob/main/src/index.js) and the core-web worker), asset hashing, and Workbox integration - **[`http_server.js`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/package.json)**: Contains npm scripts (`start`, `build`, `docker`) and dependency definitions - **[`src/index.js`](https://github.com/Stremio/stremio-web/blob/main/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//` 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`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/package.json). ### Can I deploy Stremio-Web without using Docker? Yes. After running `pnpm run build`, you can serve the `build//` directory using any static file server. The repository includes [`http_server.js`](https://github.com/Stremio/stremio-web/blob/main/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`](https://github.com/Stremio/stremio-web/blob/main/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.