@capgo/capacitor-asset-cache

Transparent persistent media cache for Capacitor images, videos, and other large CDN assets.

@capgo/capacitor-asset-cache lets app code ask for a media source and bind it directly to an <img>, <video>, React component, Vue template, or any other web UI.

• Pass a CDN path like videos/intro.mp4 and get a local display-ready URL back.
• Uses persistent app storage: iOS Application Support and Android internal files.
• src(...) and resolve(...) only resolve after a local file exists; if the plugin cannot create a local file, the call rejects.
• bind(...) updates an image or video element from loading to ready when the local file is available.
• Supports cache-only, TTL, ETag, Last-Modified, and always-revalidate modes.
• Keeps lower-level get, list, remove, and clear helpers for advanced cache management.

The cache is removed when the app is uninstalled, but it is not stored in the platform cache directory that the system may flush under pressure.

The most complete doc is available here: https://capgo.app/docs/plugins/asset-cache/

npm install @capgo/capacitor-asset-cache
npx cap sync

Configure the CDN once, then bind media elements to CDN paths. The element only receives the local webview URL after the native fetch is done.

import { AssetCache } from '@capgo/capacitor-asset-cache';

AssetCache.configure({
  cdnUrl: 'https://cdn.example.com/assets/',
  revalidate: {
    strategy: 'ttl',
    maxAgeSeconds: 86400,
  },
});

const video = document.querySelector('video');
if (video) {
  AssetCache.bind(video, 'videos/intro.mp4');
}

video[data-asset-cache-state='loading'],
img[data-asset-cache-state='loading'] {
  opacity: 0.4;
}

video[data-asset-cache-state='ready'],
img[data-asset-cache-state='ready'] {
  opacity: 1;
}

import { useEffect, useRef } from 'react';
import { AssetCache } from '@capgo/capacitor-asset-cache';

AssetCache.configure({ cdnUrl: 'https://cdn.example.com/assets/' });

export function HeroImage() {
  const imageRef = useRef<HTMLImageElement>(null);

  useEffect(() => {
    if (!imageRef.current) return;

    const binding = AssetCache.bind(imageRef.current, 'hero.jpg');
    return () => binding.cancel();
  }, []);

  return <img ref={imageRef} alt="" />;
}

<script setup lang="ts">
import { onMounted, onUnmounted, ref } from 'vue';
import { AssetCache, type AssetCacheBinding } from '@capgo/capacitor-asset-cache';

const image = ref<HTMLImageElement | null>(null);
let binding: AssetCacheBinding | undefined;

onMounted(() => {
  if (image.value) {
    binding = AssetCache.bind(image.value, 'hero.jpg', {
      cdnUrl: 'https://cdn.example.com/assets/',
    });
  }
});

onUnmounted(() => binding?.cancel());
</script>

<template>
  <img ref="image" alt="" />
</template>

Use src(...) when your framework already manages loading state. It resolves only after the local file is ready.

const src = await AssetCache.src('images/hero.jpg');

Pass headers to the native fetch. The web element receives only the local file URL returned by the plugin.

const src = await AssetCache.src('private/videos/intro.mp4', {
  cdnUrl: 'https://cdn.example.com/assets/',
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

Use resolve(...) when you also want metadata about the local file resolution.

const source = await AssetCache.resolve('images/hero.jpg');

console.log(source.src, source.fromCache, source.status);

Use get(...) directly only when you need the raw native file metadata.

const asset = await AssetCache.get({
  url: 'https://example.com/videos/intro.mp4',
  key: 'intro.mp4',
  revalidate: { strategy: 'etag' },
});

• iOS stores files under Application Support and excludes the cache root from iCloud backup.
• Android stores files under the app internal files directory.
• Web uses the browser Cache API and localStorage metadata as a development fallback.

• configure(...)
• resolve(...)
• src(...)
• bind(...)
• get(...)
• remove(...)
• clear()
• list()
• getCacheSize()
• getPluginVersion()
• Interfaces
• Type Aliases

Persistent asset cache for large Capacitor images, videos, and other media.

configure(options: AssetCacheConfigOptions) => void

Set defaults for future src(...), resolve(...), and bind(...) calls.

resolve(path: AssetCacheSourceInput, options?: AssetCacheSourceOptions | undefined) => Promise<ResolvedAssetSource>

Resolve a CDN path or remote URL into a local display-ready source URL.

Returns: Promise<ResolvedAssetSource>

src(path: AssetCacheSourceInput, options?: AssetCacheSourceOptions | undefined) => Promise<string>

Resolve a CDN path or remote URL into a local string ready for img.src or video.src.

Returns: Promise<string>

bind(element: AssetCacheBindableElement, path: AssetCacheSourceInput, options?: AssetCacheBindOptions | undefined) => AssetCacheBinding

Bind an image or video element to a local asset and update it when ready.

Returns: AssetCacheBinding

get(options: GetAssetOptions) => Promise<CachedAsset>

Resolve an asset URL into a local persistent file.

Returns: Promise<CachedAsset>

remove(options: AssetCacheKeyOptions) => Promise<RemoveAssetResult>

Remove one cached asset by key or URL.

Returns: Promise<RemoveAssetResult>

clear() => Promise<ClearCacheResult>

Remove every cached asset managed by this plugin.

Returns: Promise<ClearCacheResult>

list() => Promise<AssetCacheListResult>

List cached assets that still exist on disk.

Returns: Promise<AssetCacheListResult>

getCacheSize() => Promise<AssetCacheSizeResult>

Return total cached asset bytes.

Returns: Promise<AssetCacheSizeResult>

getPluginVersion() => Promise<PluginVersionResult>

Returns the platform implementation version marker.

Returns: Promise<PluginVersionResult>

Shared defaults used by AssetCache.src(...) and AssetCache.resolve(...).

Revalidation options for cached assets.

Result returned by AssetCache.resolve(...).

A cached asset stored in app-owned persistent storage.

Input used by AssetCache.src(...) and AssetCache.resolve(...).

Per-asset options used by AssetCache.src(...) and AssetCache.resolve(...).

Binding returned by AssetCache.bind(...).

Options used by AssetCache.bind(...).

Options used to resolve a remote asset into a local persistent file.

Remove result.

Identifies an asset by cache key or by URL. key wins when both are set.

Clear result.

List result.

Cache size result.

Plugin version payload.

Revalidation mode used when an asset already exists in persistent storage.

'never' | 'ttl' | 'always' | 'etag' | 'last-modified'

Convenience input accepted by AssetCache.src(...) and AssetCache.resolve(...).

string | ResolveAssetSourceOptions

Element supported by AssetCache.bind(...).

HTMLImageElement | HTMLVideoElement