@capgo/capacitor-asset-cache

Cache large images, videos and other CDN files on the device so they load instantly and work offline. One call turns a remote URL into a local file your WebView can display.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-asset-cache in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-asset-cache to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Local files: get() downloads an asset once and returns a persistent local file.
• Display ready: resolve() and src() turn a CDN path or URL into a value you can put in src.
• Revalidation: never, ttl (with maxAgeSeconds), always, etag or last-modified strategies, plus custom request headers.
• Cache management: list(), getCacheSize(), remove() and clear().
• Platforms: iOS, Android and Web. The web implementation keeps the same API in the browser.

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(...)
• resolve(...)
• src(...)
• bind(...)
• get(...)
• remove(...)
• clear()
• list()
• getCacheSize()
• getPluginVersion()
• Interfaces
• Type Aliases

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

configure(...)

configure(options: AssetCacheConfigOptions) => void

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

resolve(...)

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(...)

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(...)

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(...)

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

Resolve an asset URL into a local persistent file.

Returns: Promise<CachedAsset>

remove(...)

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

Remove one cached asset by key or URL.

Returns: Promise<RemoveAssetResult>

clear()

clear() => Promise<ClearCacheResult>

Remove every cached asset managed by this plugin.

Returns: Promise<ClearCacheResult>

list()

list() => Promise<AssetCacheListResult>

List cached assets that still exist on disk.

Returns: Promise<AssetCacheListResult>

getCacheSize()

getCacheSize() => Promise<AssetCacheSizeResult>

Return total cached asset bytes.

Returns: Promise<AssetCacheSizeResult>

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the platform implementation version marker.

Returns: Promise<PluginVersionResult>

Interfaces

AssetCacheConfigOptions

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

AssetCacheRevalidateOptions

Revalidation options for cached assets.

ResolvedAssetSource

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

CachedAsset

A cached asset stored in app-owned persistent storage.

ResolveAssetSourceOptions

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

AssetCacheSourceOptions

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

AssetCacheBinding

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

AssetCacheBindOptions

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

GetAssetOptions

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

RemoveAssetResult

Remove result.

AssetCacheKeyOptions

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

ClearCacheResult

Clear result.

AssetCacheListResult

List result.

AssetCacheSizeResult

Cache size result.

PluginVersionResult

Plugin version payload.

Type Aliases

AssetCacheRevalidateStrategy

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

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

AssetCacheSourceInput

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

string | ResolveAssetSourceOptions

AssetCacheBindableElement

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

HTMLImageElement | HTMLVideoElement