Performant Vertical Feed in Expo: HLS Caching on iOS

In the world of modern mobile apps, users have been trained to expect instant. Whether scrolling through TikTok, swiping on Instagram Reels, or watching course content, they expect videos to play immediately—even in tunnels, elevators, or spotty network conditions.

To achieve this instant feel, offline caching is non-negotiable. You need to pre-download the next few videos in the feed so they are ready before the user even scrolls to them.

React Native Developers often rely on the Expo ecosystem to abstract away the complexity of native media players. With the release of Expo SDK 52, the team introduced the powerful new expo-video library (replacing the older expo-av). It brought a modernized player implementation, better performance, and, crucially, a native useCaching prop that stabilized in Expo SDK 53.

While Android (via the powerful ExoPlayer/Media3) and standard .mp4 files worked seamlessly with the new native caching, trying to cache HLS (.m3u8) streams on iOS resulted in... nothing.

The native iOS AVPlayer is fantastic at streaming, but it simply doesn't support a straightforward, "one-line code" way to cache complex HLS playlists to the disk for offline retrieval. This left us with a critical feature gap: our Android users enjoyed a smooth, offline-ready experience, while our iOS users faced buffering or playback failures the moment they lost connection.

To understand the solution, we first have to understand why HLS is fundamentally different from the video files you might be used to.

MP4: The "Single File" Approach

When you play a standard MP4 file, you are dealing with a monolithic file. Caching it is trivial:

HLS: The Tree Protocol

HLS (HTTP Live Streaming) is a file and streaming protocol. It behaves less like a single book and more like a library card catalog.

If you simply download the .m3u8 link, you have not downloaded the video. You have only downloaded a tiny text file (a few kilobytes) that contains links to other files.

To cache HLS, you must traverse a complex tree structure:

The iOS Roadblock. On Android, the native ExoPlayer is smart enough to handle this "tree walking" and caching internally.

On iOS, the AVPlayer is designed primarily for streaming. While Apple provides APIs for downloading HLS (like AVAssetDownloadTask), they are complex, restrictive, and often designed for long-form content (like downloading a movie on Netflix to watch on a plane) rather than the instant, short-form caching required for a TikTok-like feed.

Since we could not force AVPlayer to cache the stream natively, we decided to trick it. We built expo-video-cache using a Local Proxy Architecture.

The concept is simple but powerful: we spin up a tiny web server on the device itself (localhost) that sits between the video player and the internet.

Instead of feeding the player the remote URL: https://example.com/video.m3u8

We feed it a local URL pointing to our proxy: http://127.0.0.1:9000/proxy?url=https://example.com/video.m3u8

How It Works Under the Hood

The magic happens in three distinct phases:

1. Interception 

When the AVPlayer tries to load our localhost URL, it connects to our internal server instead of the internet. The player has no idea it is talking to a local script; it thinks it's streaming from a standard web server.

2. Manifest Rewriting 

This is the most critical technical step. To prevent the player from bypassing us, our proxy downloads the manifest and parses it line-by-line.

However, we added an optimization here. We check our local cache for each segment listed in the manifest:

This ensures the player only uses our proxy when we actually have the data, reducing overhead for new content.

3. Smart Caching 

Finally, when the player reads our rewritten manifest:

When building cross-platform modules, it is tempting to force both platforms to behave exactly the same way. However, we realized that Android's native caching (via ExoPlayer) is already excellent. It supports HLS caching out of the box.

We didn't want to add the overhead of a local proxy server on Android where it wasn't needed. We only wanted to intervene on iOS.

This led to a "Hybrid" Implementation Strategy:

1. Installation

2. The Global Server Setup

We spin up the local server once when the app launches. A great place for this is your root _layout.tsx file.

3. The Smart Source Helper

This is the most critical piece of code in your app. We created a utility function, getVideoSource, to abstract away the platform differences.

Critical Note on useCaching: On iOS, we explicitly set useCaching: false.

Using it in your component becomes trivial. You no longer need to think about platforms inside your UI code:

Here is the enhanced version of Part 5.

Building a native proxy server from scratch wasn't without its hurdles. Here are the key "Gotchas" we discovered during development that might save you some headaches.

1. The MP4 Trap 

In our first prototype, we got excited and tried to run everything through the proxy. This was a mistake.

2. The "App Launch" Race Condition 

We ran into an edge case where a video on the very first screen of the app would fail to load.

3. DRM Limitations 

This approach relies on Manifest Rewriting—literally opening the text file and changing the URLs.

We know that bundle size matters. We measured the impact of adding expo-video-cache to a production build to ensure it respects your app's footprint.

iOS Impact: ~2.5 MB

The iOS module includes a lightweight embedded Swift HTTP server (Swifter). In a production release build (stripped and optimized), this adds approximately 2.5 MB to your final .ipa size.

Android Impact: ~0 KB (Negligible)

Since Android relies entirely on the native ExoPlayer for caching, our module acts as a simple pass-through shim.

expo-video-cache was born out of necessity, but it has become a robust solution for our offline-first requirements. It bridges the critical gap between iOS's strict streaming protocols and the need for a modern, instant, cached user experience.

We’ve open-sourced this package for the community because we believe no one should have to write a Swift web server just to play a video loop.