Caching

The library caches every successful response and most errors in memory, keyed by URL. The cache is shared by every <LinkPreview /> and useUrlPreview call, so rendering the same URL twice — or ten times, or on a later screen — fires only a single network request.

Concurrent requests for the same URL are deduplicated automatically: if four components mount at once with url="https://github.com", exactly one fetch goes out and all four receive the same resolved promise.

Defaults

Setting	Default	Meaning
`maxSize`	`50`	LRU bound. The oldest entry is evicted past this size.
`ttl`	`5 * 60 * 1000` ms	Lifetime of a successful entry (5 minutes).
`errorTtl`	`30 * 1000` ms	Lifetime of a cached error (30 seconds).
`enabled`	`true`	Master switch. When `false`, every read misses.

LRU eviction promotes accessed entries on read, so frequently-viewed URLs stay warm. Expired entries are deleted lazily on the next read.

API

Three functions to control the cache, plus one type.

`configureCache(options)`

Configure once at app startup. configureCache accepts any subset of options; unspecified keys keep their current value.

Calling configureCache resets the cache — a clean slate is safer when changing sizing parameters.

import { configureCache } from 'react-native-preview-url';

configureCache({
  maxSize: 100, // larger LRU window for media-heavy feeds
  ttl: 10 * 60 * 1000, // 10-minute success TTL
  errorTtl: 60 * 1000, // 1-minute error TTL
});

`clearCache()` and `invalidateUrl(url)`

import { clearCache, invalidateUrl } from 'react-native-preview-url';

// Drop everything (e.g. on pull-to-refresh)
clearCache();

// Drop a single URL (success or error)
invalidateUrl('https://github.com');

Both functions are no-ops when the cache is disabled.

Disabling

configureCache({ enabled: false });

When disabled, every call falls through to the network. The dedupe-on-flight behavior still works (concurrent reads share a request) but no result is remembered after it resolves.

Useful in tests where you want each render to hit a mocked fetch, or in memory-constrained environments where you'd rather pay the network cost than hold metadata in RAM.

`CacheOptions`

import type { CacheOptions } from 'react-native-preview-url';

interface CacheOptions {
  maxSize?: number;
  ttl?: number; // success TTL in ms
  errorTtl?: number; // error TTL in ms
  enabled?: boolean;
}

Behavior details

Scoping by base URL

Cache keys are scoped by the base URL configured via setBaseUrl. Switching environments mid-session — say, pointing the lib at a staging API — does not leak entries from one environment into another. Each base URL gets its own slice.

What is not cached

Timeout errors. If a request times out, the result is not written to the error cache. Timeouts are treated as transient — the next render retries. Other server errors (4xx, 5xx with JSON body, etc.) are cached for errorTtl.
Invalid URL errors. URL is required and Invalid URL format short circuit before any network call and don't touch the cache.

Deduplication

When N components ask for the same URL concurrently, the cache stores the in-flight Promise — every consumer awaits the same one. Only one network call goes out. Once it resolves, the result is written to the entry cache and the in-flight slot is cleared.

On this page