How to Debug Issues in the Stremio-Web Application: A Complete Developer Guide

To debug issues in the Stremio-Web application, use the browser console for runtime JavaScript errors, React DevTools for component inspection, and enable verbose logging via environment variables in src/services/Chromecast/ChromecastTransport.js while monitoring network requests through the browser's Network tab.

Stremio-Web is a modern React single-page application (SPA) that runs inside the browser as part of the Stremio media ecosystem. Understanding how to effectively debug issues in the Stremio-Web application requires familiarity with its context-based architecture, centralized error reporting via Sentry, and service worker integration. This guide provides practical techniques based on the actual source code in the Stremio/stremio-web repository.

Core Architecture and Entry Points

Understanding the bootstrap sequence is essential before debugging. The application initializes in src/index.js, which configures Sentry error reporting, sets up internationalization (i18n), registers the service worker, and mounts the root component inside React.StrictMode.

Key architectural components include:

• CoreProvider (src/core/index.js) – Injects the Stremio core (backend bridge) into React context for all downstream components
• PlatformProvider (src/common/PlatformProvider.js) and FileDropProvider (src/common/FileDropProvider.js) – Expose platform-specific APIs for Chromecast and drag-and-drop functionality
• Router (src/router/Router/index.js) – Centralized routing logic that determines which view to render based on URL patterns defined in src/router/Router/routeConfigForPath.js and src/router/Router/urlParamsForPath.js
• Services (src/services/Chromecast/Chromecast.js) – Wrappers around external APIs including Chromecast integration
• Common Hooks (src/common/useStreamingServer.js, src/common/useNotifications.js) – Reusable React hooks for state management and networking

Debugging Runtime JavaScript Errors

Browser Console Monitoring: Open the browser's developer console to view uncaught exceptions. The Sentry initialization block at the top of src/index.js captures errors globally, so verify that SENTRY_DSN is set in your environment if errors are not being reported.

Sentry Payload Inspection: To inspect what data Sentry collects before transmission, configure the scope after initialization:

// src/index.js (after Sentry.init)
Sentry.configureScope(scope => {
    scope.setTag('environment', process.env.NODE_ENV);
    console.debug('Sentry scope configured:', scope);
});

Debugging Component Rendering Issues

React DevTools: Since the entire application runs under React.StrictMode, use the React DevTools browser extension to inspect the component tree, examine props and state, and identify why specific views like src/routes/Library/Library.js might fail to render.

Error Boundaries: For development environments, wrap routes with a custom error boundary to isolate UI crashes:

// src/common/ErrorBoundary.js
import React from 'react';

export class ErrorBoundary extends React.Component {
    state = { hasError: false, error: null };

    static getDerivedStateFromError(error) {
        return { hasError: true, error };
    }

    componentDidCatch(error, info) {
        console.error('ErrorBoundary caught:', error, info);
    }

    render() {
        if (this.state.hasError) {
            return <div>Something went wrong: {this.state.error.message}</div>;
        }
        return this.props.children;
    }
}

Implement the boundary in src/App/App.js:

// src/App/App.js
import { ErrorBoundary } from '../common/ErrorBoundary';

function App() {
    return (
        <ErrorBoundary>
            {/* existing router view */}
            <Routes />
        </ErrorBoundary>
    );
}

Debugging Routing and URL Mismatches

When routes fail to resolve or URL parameters parse incorrectly, examine the router configuration in src/router/Router/routeConfigForPath.js and the URL parser in src/router/Router/urlParamsForPath.js. The central router logic in src/router/Router/index.js uses these files to map paths to specific view components like the Library or Video player.

Debugging Service Worker Registration Failures

Service worker issues typically manifest as caching problems or failed updates. The registration code lives in src/index.js within the service-worker registration block. Check the catch block in this file for specific error messages if the worker fails to register.

To force a service worker reload during development:

// src/index.js
if (navigator.serviceWorker?.controller) {
    navigator.serviceWorker.controller.postMessage({ type: 'skipWaiting' });
    console.info('Service worker skipWaiting message sent');
}

Debugging Network Requests

Monitor network traffic in the browser's Network tab, filtering by endpoints like /api/addons. The src/common/useStreamingServer.js hook handles streaming server communications, while various files in src/services/ manage external API calls. Inspect these files to verify request construction and response handling.

Debugging Chromecast Integration

Chromecast transport logs are controlled via environment variables in src/services/Chromecast/ChromecastTransport.js. Enable verbose logging by setting CHROMECAST_DEBUG=true:

// src/services/Chromecast/ChromecastTransport.js
const DEBUG = process.env.CHROMECAST_DEBUG === 'true';
if (DEBUG) {
    console.info('Chromecast transport debug enabled');
}

The main integration point is src/services/Chromecast/Chromecast.js, which coordinates with the transport layer.

Debugging Internationalization (i18n) Issues

Translation resources are built from stremio-translations in the i18n initialization block of src/index.js. If text fails to appear or displays keys instead of values, verify that resources are loading correctly in the network tab and that the initialization logic executed without errors.

Debugging Performance Bottlenecks

Use the browser's Performance tab to identify long-running tasks in the React Scheduler. UI-heavy components like Video and Library utilize useAnimationFrame from src/common/useAnimationFrame.js for smooth animations. Check this hook's implementation if you encounter jank or high CPU usage during animations.

Summary

• Monitor src/index.js – This file controls Sentry initialization, i18n setup, and service worker registration, making it the first place to check for bootstrap failures
• Use React DevTools – Essential for inspecting the component hierarchy and context providers like CoreProvider and PlatformProvider
• Enable environment-specific logging – Set CHROMECAST_DEBUG=true to troubleshoot casting issues and use Sentry.configureScope to verify error reporting
• Inspect router configuration – Check src/router/Router/routeConfigForPath.js and urlParamsForPath.js when URLs fail to resolve correctly
• Wrap components with ErrorBoundary – Prevent total UI crashes during development by catching errors in React components
• Check service worker status – Use the skipWaiting message pattern to bypass caching issues during active development

Frequently Asked Questions

How do I enable Chromecast debugging in Stremio-Web?

Set the environment variable CHROMECAST_DEBUG to true before building. In src/services/Chromecast/ChromecastTransport.js, this variable triggers console logging in the transport layer, allowing you to see communication between the browser and cast devices. Rebuild the application after setting the variable, then open the browser console to view the debug messages.

Where are runtime JavaScript errors logged in Stremio-Web?

Runtime errors are logged to the browser console and sent to Sentry if the SENTRY_DSN environment variable is configured. The Sentry initialization occurs in src/index.js, and you can enhance logging by adding Sentry.configureScope calls to tag errors with specific environment details before they are transmitted.

How can I force a service worker update during debugging?

Send a skipWaiting message to the active service worker controller. In src/index.js, check for navigator.serviceWorker.controller and post a message with { type: 'skipWaiting' }. This immediately activates the waiting service worker, bypassing the standard lifecycle and clearing cached assets that might be causing stale code execution.

Why might React components fail to render in Stremio-Web?

Rendering failures typically stem from uncaught errors in the component tree or missing context providers. Since the app uses React.StrictMode, check the console for warnings about deprecated patterns. Use the ErrorBoundary pattern shown in src/common/ErrorBoundary.js to isolate crashes, and verify that CoreProvider in src/core/index.js is properly mounted above the component hierarchy.

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