zephyr-native-cache

Zephyr Native Cache

Zephyr Cloud | Zephyr Docs | Discord | Twitter | LinkedIn

A React Native native cache layer for Module Federation Metro bundles. It verifies bundle hashes, caches validated bundles on device, and supports background polling for updates.

Installation

# npm
npm install zephyr-native-cache

# yarn
yarn add zephyr-native-cache

# pnpm
pnpm add zephyr-native-cache

# bun
bun add zephyr-native-cache

Usage

Configure the Module Federation runtime plugin in your Metro MF setup:

runtimePlugins: [require.resolve('zephyr-native-cache/runtime-plugin')];

Register the cache once at app startup before loading remotes:

import { register } from 'zephyr-native-cache';

register({
  maxCacheSizeBytes: 50 * 1024 * 1024,
  maxAgeMs: 3 * 24 * 60 * 60 * 1000,
  enablePolling: true,
  pollIntervalMs: 10 * 60 * 1000,
});

Configuration

register(config) accepts:

• bundleDir: custom storage directory for cached bundles
• maxCacheSizeBytes: max cache size before LRU eviction (default 20MB)
• maxAgeMs: stale threshold for cache entries (default 7 days)
• minCacheSizeBytes: minimum cache size to preserve during cleanup
• enablePolling: start automatic manifest polling (default true)
• pollIntervalMs: polling interval in ms (default 5 minutes)
• forceCacheInDev: enable cache in development mode (production is always enabled)

Runtime APIs

register returns a BundleCacheLayer instance:

• loadBundle(bundleUrl)
• checkForUpdates()
• startPolling(intervalMs?)
• stopPolling()
• clearCache()
• getLoadedBundles()

It also exposes globals for manual control:

• globalThis.__MFE_CHECK_UPDATES__()
• globalThis.__MFE_START_UPDATE_POLLING__(intervalMs?)
• globalThis.__MFE_STOP_UPDATE_POLLING__()

Events

Use CacheEvents to observe cache lifecycle events:

• bundle:load
• poll:start
• update:available
• update:downloaded
• poll:complete

Example:

import { register } from 'zephyr-native-cache';

const cache = register();

cache.events.on('bundle:load', (event) => {
  console.log('[cache]', event.status, event.remoteName);
});

cache.events.on('poll:complete', (event) => {
  console.log('[cache] poll complete', event.updated, '/', event.checked);
});

Requirements

• React >=19.0.0
• React Native >=0.79.0

License

Licensed under the Apache-2.0 License. See LICENSE for more information.