Streambert Offline Detection and Content Availability: A Technical Deep Dive

Streambert uses the browser's native navigator.onLine API combined with React state management to detect network status changes, automatically disabling API-dependent features like search and trending feeds while maintaining access to cached viewing history and local media.

Streambert is a desktop-style web application built to provide seamless media streaming even when connectivity drops. Understanding Streambert offline detection and content availability reveals a lightweight, browser-native approach that ensures users retain access to downloaded or cached content without requiring external dependencies. This analysis examines the implementation details found in the truelockmc/streambert repository to explain how the application gracefully degrades functionality when the network disappears.

Detecting Network Status in Streambert

The offline detection logic resides primarily in src/App.jsx, where the application initializes a boolean state variable by reading the browser's navigator.onLine property:

const [offline, setOffline] = useState(() => !navigator.onLine);

To maintain synchronization with the operating system's network state, the component attaches event listeners to the global window object inside a useEffect hook:

useEffect(() => {
  const goOffline = () => setOffline(true);
  const goOnline  = () => setOffline(false);
  window.addEventListener("offline", goOffline);
  window.addEventListener("online",  goOnline);
  return () => {
    window.removeEventListener("offline", goOffline);
    window.removeEventListener("online",  goOnline);
  };
}, []);

This setup ensures that whenever the underlying network interface changes state, React re-renders the component tree with the updated connectivity flag.

Content Availability During Offline Mode

When the offline state becomes true, Streambert immediately restricts network-dependent operations while preserving access to locally stored data. The implementation varies by component, with each responsible for checking the offline flag before executing fetch requests.

HomePage.jsx Conditional Data Fetching

In src/pages/HomePage.jsx (lines 102-172 and 216-246), the component guards all API calls with an early return statement:

useEffect(() => {
  if (!apiKey || offline) return;   // skip when offline
  // …fetch recommendations here…
}, [apiKey, offline, history?.length]);

This pattern prevents unnecessary network errors by skipping requests for trending data, recommendations, and user history updates. The UI adapts by hiding sections that require fresh data while continuing to display the "recently watched" carousel and other cached content.

SearchModal.jsx Offline User Feedback

The search functionality provides explicit user feedback when connectivity drops. In src/components/SearchModal.jsx (lines 142-159), a conditional render displays a friendly message instead of the search interface:

{offline && (
  <p>🌐 No internet, search is unavailable offline.</p>
)}

Global Fetch Gating in App.jsx

The root component in src/App.jsx (lines 71, 504-506, 543-546, 908, and 1012) uses the same offline check to short-circuit background data refreshes. The offline boolean propagates through the component tree as a prop, allowing child pages to implement consistent connectivity-aware behavior without duplicating detection logic.

Technical Architecture Benefits

Streambert's offline detection relies exclusively on standard Web APIs, eliminating the need for additional npm packages or native module dependencies. Because the offline flag exists as standard React state, the entire UI reacts automatically to connectivity changes through React's normal re-rendering cycle.

The implementation supports cross-platform compatibility across Windows, macOS, and Linux without platform-specific code, as all major browsers implement the online and offline window events consistently.

Summary

• Native Browser APIs: Streambert uses navigator.onLine and window event listeners rather than external libraries to detect connectivity changes in src/App.jsx.
• Conditional Fetching: Components like src/pages/HomePage.jsx check the offline flag before making API calls to TMDB, preventing network errors and unnecessary requests.
• Graceful Degradation: Search functionality in src/components/SearchModal.jsx displays user-friendly messages when offline, while cached content like viewing history remains accessible.
• Reactive Updates: The React state-based implementation ensures immediate UI updates when connectivity is lost or restored.
• Zero Dependencies: The solution works across all supported platforms without requiring additional packages.

Frequently Asked Questions

How does Streambert detect when a user goes offline?

Streambert initializes a React state variable from navigator.onLine in src/App.jsx and attaches event listeners to the window object's online and offline events. When the browser fires these events, the state updates, triggering a re-render throughout the application.

What content is available in Streambert when offline?

Users retain access to locally cached data including the "recently watched" carousel and saved items stored in the application's local state or storage. However, features requiring live API calls—such as TMDB search, trending recommendations, and subtitle fetching—are disabled or hidden.

Does Streambert require additional libraries for offline detection?

No. The implementation uses only native browser APIs (navigator.onLine and window event listeners) available in all modern browsers. This design choice keeps the bundle size small and ensures compatibility across Windows, macOS, and Linux without platform-specific dependencies.

How does the UI react when connectivity is restored?

When the browser fires the online event, the offline state in src/App.jsx flips to false. This state change propagates through React's context and props to all child components, which automatically resume their normal data fetching cycles and reveal previously hidden network-dependent features.

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