@capgo/capacitor-asset-cache

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

Why Asset Cache?

@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.

Documentation

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

Compatibility

Install

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

Usage

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;
}

React

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="" />;
}

Vue

<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>

Direct Source

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');

Protected Assets

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}`,
  },
});

Inspect the Resolution

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);

Advanced Cache Control

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' },
});

Platform notes

• 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.

API

configure(options: AssetCacheConfigOptions) => void

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

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

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

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

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

clear() => Promise<ClearCacheResult>

list() => Promise<AssetCacheListResult>

getCacheSize() => Promise<AssetCacheSizeResult>

getPluginVersion() => Promise<PluginVersionResult>