Stremio Web —
Rust WASM 코어와 React가 만든
"Freedom to Stream"

애드온 시스템 하나로 P2P, HTTP 스트림, 자막, 메타데이터를 전부 흡수하는 오픈소스 미디어 센터. 10.8k 스타, GPL-2.0, 2017년부터 7년째 살아남은 풀스택 웹앱의 구조를 한 번에 훑는다.

1프로젝트 한줄 요약

"한 마디로 무엇을 하는 프로젝트인가."

사용자 입장에선 그냥 "영화·드라마·라이브 채널을 찾아서 보는 깔끔한 앱"이다. 하지만 그 뒤를 들춰보면, UI 한 벌로 토렌트·HLS·HTTP·유튜브·자막 서비스를 전부 통합하는 애드온 마켓플레이스가 돌아간다. 마치 VS Code의 Extension Marketplace나 옵시디언의 커뮤니티 플러그인처럼.

2왜 주목받는가

트렌딩 이유, 경쟁 제품 대비 장점.

2026년 5월 23일 기준 TrendShift 일일 트렌딩 9위에 올라온 이유는 단순한 "오픈소스 넷플릭스 대안" 그 이상이다. 이 프로젝트가 보여주는 기술적 결단들이 흥미롭다.

3기술 스택 전체 지도

백엔드 · 프론트엔드 · 인프라.

먼저 package.json과 Dockerfile, webpack 설정에서 추출한 스택을 영역별로 본다. 이 레포(stremio-web)는 사실상 프런트엔드 + 정적 호스팅 + WASM 코어 구조라 "백엔드"는 외부 의존 서비스(애드온 서버, 토렌트 스트리밍 서버 등)로 분리되어 있다.

프런트엔드 — UI 레이어

• i18next 24 + react-i18next 15 — 다국어 지원. 번역 리소스는 별도 레포 Stremio/stremio-translations에서 git 의존성으로 가져온다.
• spatial-navigation-polyfill — TV 리모컨의 ←↑↓→ 키로 포커스 이동. CSS 속성 --nav-up 등으로 다음 포커스 대상을 명시.
• @stremio/stremio-icons / stremio-colors — 자체 디자인 시스템. 색상은 토큰화돼서 Stremio Web/Desktop/Mobile 전체에서 공유.
• react-focus-lock — 모달이 열려 있을 때 포커스를 가두는 패턴(접근성용).
• classnames, fast-equals, lodash.debounce/throttle/intersection — 잔돌이 유틸 모음.
• bowser — 브라우저 감지(Safari냐 Chrome이냐에 따라 비디오 재생 분기).
• @sentry/browser 8 — 에러 트래킹. 프로덕션 빌드에 자동 주입.

코어 — 비즈니스 로직 레이어 (Rust → WASM)

• types — Movie, Series, Stream, Subtitle, Addon Manifest 등 모든 도메인 타입.
• addon_transport — 애드온과 통신하는 트랜스포트 레이어. legacy 프로토콜 어댑터도 포함.
• state_types — Context(인증·애드온 목록), Library(시청 목록), CatalogFiltered 등 stateful 모델.
• runtime — Effect를 자동 처리하는 런타임. 비동기 작업을 추상화.
• environment — fetch·storage를 추상화한 trait. 웹에선 fetch API + IndexedDB, 데스크탑에선 reqwest + 파일시스템 등으로 다르게 구현.

비디오 재생 — 미디어 레이어

• @stremio/stremio-video — 자체 비디오 플레이어 추상화. HTMLVideoElement, HLS.js, Chromecast, 외부 플레이어(MPV·VLC) 등 여러 백엔드를 같은 인터페이스로 묶음.
• magnet-uri — 토렌트 마그넷 링크 파싱(magnet:?xt=urn:btih:…).
• buffer — Node Buffer 폴리필. WASM 바이너리 처리에 필요.

빌드 · 번들링 인프라

• entry: main + worker — UI 번들과 stremio-core WASM 워커를 분리해서 빌드.
• workbox-webpack-plugin — PWA 오프라인 캐싱. 최대 20MB 파일까지 precache.
• cssnano-preset-advanced — CSS 압축. 자동 prefix 추가/제거.
• terser-webpack-plugin — JS 압축. 주석 제거, mangle 활성.
• COMMIT_HASH 기반 파일명 — [commit_hash]/scripts/[name].js 형식으로 캐시 무효화를 git commit 단위로 한다.

호스팅 · 배포 인프라

• Docker (node:22-alpine) — 멀티 스테이지 빌드: base → app(빌드) → server(express) → 최종 이미지.
• http_server.js — Express 4 하나로 정적 파일을 서빙. index.html은 max-age 7200초, 나머지 에셋은 약 30일(2629744초).
• GitHub Pages 미러 — stremio.github.io/stremio-web에 development 브랜치 자동 배포(GitHub Actions build.yml).
• web.stremio.com — 공식 호스팅. CDN 뒤에서 동일한 Docker 이미지로 제공.

4아키텍처 심화 분석

시스템 구조도 + 핵심 설계 패턴.

Stremio Web의 진짜 흥미로운 점은 UI(React)와 상태(Rust WASM)가 메시지로만 대화한다는 분리에 있다. 보통의 React 앱이 Redux나 Zustand로 JS 안에서 상태를 관리하는 것과 정반대 방향이다. 아래는 전체 데이터 흐름을 ASCII로 그린 그림.

┌─────────────────────────────────────────────────────────────────┐
│                          BROWSER                                │
│                                                                 │
│  ┌──────────────────────┐         ┌──────────────────────────┐  │
│  │  Main Thread (UI)    │         │  Web Worker              │  │
│  │  ──────────────────  │  postMsg│  ─────────────────────   │  │
│  │  React 18 Components │ ◀─────▶ │  stremio-core (WASM)     │  │
│  │  Less / CSS Modules  │  (Msg)  │  ┌─────────────────────┐ │  │
│  │  i18next 번역        │         │  │ Context: 인증·애드온│ │  │
│  │  Sentry              │         │  │ Library: 시청 목록  │ │  │
│  │  spatial-navigation  │         │  │ Catalogs: 영화/TV   │ │  │
│  │  stremio-video       │         │  │ Streams: 재생 URL   │ │  │
│  └──────────────────────┘         │  │ MetaDetails: 상세   │ │  │
│            │                      │  └─────────────────────┘ │  │
│            │ HTMLVideoElement     │         │ Effects        │  │
│            ▼                      │         ▼                │  │
│  ┌──────────────────────┐         │  ┌─────────────────────┐ │  │
│  │  <video> / HLS.js /  │         │  │ Environment trait   │ │  │
│  │  Chromecast 송출     │         │  │ (fetch + storage)   │ │  │
│  └──────────────────────┘         │  └─────────────────────┘ │  │
│                                   └─────────│────────────────┘  │
└─────────────────────────────────────────────│───────────────────┘
                                              │ HTTPS
                                              ▼
                ┌─────────────────────────────────────────────────┐
                │              EXTERNAL SERVICES                  │
                │                                                 │
                │  ┌─────────────┐  ┌─────────────┐  ┌─────────┐  │
                │  │  api.       │  │  Cinemeta   │  │  사용자 │  │
                │  │ strem.io    │  │  (메타데이터)│  │ 제작 애 │  │
                │  │ (인증·동기) │  │             │  │ 드온 N개│  │
                │  └─────────────┘  └─────────────┘  └─────────┘  │
                │                                                 │
                │  ┌─────────────┐  ┌─────────────┐  ┌─────────┐  │
                │  │ OpenSubtit. │  │  Torrentio  │  │ HLS/M3U │  │
                │  │ (자막 애드온)│  │ (P2P 애드온)│  │ 스트림  │  │
                │  └─────────────┘  └─────────────┘  └─────────┘  │
                └─────────────────────────────────────────────────┘

핵심 설계 패턴 1 — Elm Architecture

핵심 설계 패턴 2 — Environment Trait

핵심 설계 패턴 3 — 애드온 매니페스트 프로토콜

Stremio의 진짜 차별점. 누구나 HTTP 서버 하나를 띄우고 /manifest.json을 노출하면 그게 곧 애드온이다.

{
  "id": "com.myaddon.movies",
  "version": "1.0.0",
  "name": "My Movies Addon",
  "resources": ["catalog", "meta", "stream"],
  "types": ["movie", "series"],
  "catalogs": [{ "type": "movie", "id": "top" }],
  "endpoint": "https://myaddon.example.com"
}

그러면 코어가 자동으로 /catalog/movie/top.json, /stream/movie/tt1234567.json 같은 엔드포인트를 호출해서 데이터를 끌어온다. RESTful 컨벤션을 강제하지만 매우 가볍다 — 정적 JSON 호스팅만 해도 카탈로그 애드온을 만들 수 있다.

핵심 설계 패턴 4 — WASM 워커 분리

5디렉토리 구조 해부

주요 폴더·파일의 역할.

stremio-web/
├── src/                          ← 프런트엔드 본체
│   ├── components/               ← 재사용 가능한 React 컴포넌트
│   ├── routes/                   ← 페이지 단위 라우트 (Board, Discover, Detail …)
│   ├── core/                     ← stremio-core-web 어댑터 (CoreProvider, useCore, createTransport 등)
│   ├── router/                   ← 자체 라우터 (alias: stremio-router)
│   ├── common/                   ← 유틸·훅·아이콘·상수
│   ├── index.html                ← HtmlWebpackPlugin 템플릿
│   └── index.js                  ← Webpack entry (main) + i18next 초기화 + React 앱 렌더링
├── assets/
│   ├── favicons/                 ← 16~512px 모든 사이즈
│   ├── images/                   ← 정적 이미지
│   └── screenshots/              ← README용 .webp 스크린샷
├── tests/
│   └── i18nScan.test.js          ← 번역 키 누락 검사
├── .well-known/                  ← .well-known/apple-app-site-association 등
├── .github/
│   ├── workflows/build.yml       ← CI 빌드 + GitHub Pages 배포
│   └── ISSUE_TEMPLATE/           ← 이슈 폼
├── http_server.js                ← Express 정적 서버 (Docker용)
├── manifest.json                 ← PWA 매니페스트
├── Dockerfile                    ← 멀티 스테이지 빌드
├── webpack.config.js             ← 빌드 설정의 심장부
├── tsconfig.json                 ← TS 컴파일러 설정
├── eslint.config.mjs             ← ESLint 9 flat config
├── package.json
└── pnpm-lock.yaml                ← pnpm 락 파일

6학습 포인트 (기술별)

각 기술에서 무엇을 배울 것 + 실습 아이디어.

이 레포는 "전부 다 따라하기"보다는 관심 있는 영역만 골라 깊이 파는 게 좋다. 영역별로 어떤 학습 가치가 있는지 정리한다.

7하드웨어 / 시스템 요구사항

개발용 · 사용자용 양쪽.

개발 환경 (이 레포를 직접 빌드하려면)

• Node.js — 22 이상(README 표기, package.json engines). 실제로도 Dockerfile이 node:22-alpine이므로 22 권장.
• pnpm — 11 이상. corepack enable로 활성화.
• 디스크 — pnpm 캐시 + node_modules + WASM 빌드 산출물 합쳐 약 2GB 여유 권장.
• 메모리 — webpack + thread-loader가 코어 수만큼 워커를 띄우므로 8코어 머신에서 빌드 시 RAM 4GB 이상 사용. 16GB 환경 권장.
• git — webpack.config.js가 빌드 시 git rev-parse HEAD를 호출. .git 폴더가 있어야 함.

실행 환경 (Docker로 띄우기)

• Docker 20+ — 멀티 스테이지 빌드 지원.
• 포트 8080 — http_server.js 기본 포트.
• 외부 도달 — 클라이언트가 api.strem.io, 각종 애드온 서버에 HTTPS로 접속 가능해야 함. 사내 방화벽 환경에선 별도 프록시 설정 필요.

사용자 환경

• 브라우저 — Chrome 90+, Firefox 88+, Safari 14+, Edge 90+. WASM·Service Worker·MSE(Media Source Extensions) 필요.
• 네트워크 — 토렌트 스트리밍 애드온 사용 시 외부 토렌트 트래픽 허용 필요. 일부 국가·ISP에선 VPN 권장.
• 저장소 — IndexedDB 약 50MB 사용. 시청 기록·라이브러리·애드온 설정 저장용.

8직접 해볼 수 있는 실습 과제

난이도별 5단계.

9관련 기술 심화 학습 로드맵

8주짜리 주차별 학습 계획.

이 레포를 발판으로 "풀스택 + WASM + 미디어"를 익히고 싶다면, 다음 8주 로드맵을 권장한다. 매 주 4~6시간 투자 기준.

10핵심 키워드 사전

프로젝트에 등장하는 주요 기술 용어 정리.

11참고 링크

공식 문서 · 관련 레포 · 학습 자료.