cachel

Offline-first asset caching for the browser, powered by IndexedDB.

Fetch remote assets once, serve them forever from local cache. Works with any framework or none at all.

Features

• Fetch and cache remote assets in IndexedDB with one call
• Serve cached assets as object URLs, works fully offline
• Skips network requests for already cached assets
• Supports images, videos, audio and fonts
• No service worker required
• Zero dependencies
• ~1 kB gzipped

Install

npm install cachel

Usage

import Cachel from 'cachel';

const cache = new Cachel('my-app');

// fetch and cache a remote asset
await cache.load('https://example.com/logo.png');

// retrieve cached asset as an object URL
const url = await cache.get('https://example.com/logo.png');
img.src = url; // works offline

API

new Cachel(name?)

Creates a new cachel instance. name is used as the IndexedDB database name, prefixed internally as cachel:<name>.

const cache = new Cachel('my-app'); // opens "cachel:my-app" in IndexedDB

Defaults to 'idb' if no name is provided.

cache.load(url)

Fetches a remote asset and stores it in IndexedDB as a blob. If the asset is already cached, the network request is skipped.

await cache.load('https://example.com/hero.jpg');

Supported content types: image/*, video/*, audio/*, font/*

Throws if the fetch fails or the content type is not supported.

cache.get(url)

Retrieves a cached asset and returns it as an object URL. Returns null if not found.

const url = await cache.get('https://example.com/hero.jpg');
if (url) img.src = url;

cache.remove(url)

Removes a single cached asset.

await cache.remove('https://example.com/hero.jpg');

cache.keys()

Returns an array of all cached URLs.

const cached = await cache.keys();
console.log(cached); // ['https://example.com/logo.png', ...]

cache.clear()

Removes all cached assets from the store but keeps the database intact.

await cache.clear();

cache.delete()

Drops the entire IndexedDB database.

await cache.delete();

Framework Usage

Angular

@Directive({ selector: '[cachel]' })
export class CachelDirective implements OnInit, OnDestroy {
  @Input() cachel: string;
  private objectUrl: string;
  private cache = new Cachel('my-app');

  async ngOnInit() {
    await this.cache.load(this.cachel);
    this.objectUrl = await this.cache.get(this.cachel);
    this.el.nativeElement.src = this.objectUrl;
  }

  ngOnDestroy() {
    if (this.objectUrl) URL.revokeObjectURL(this.objectUrl);
  }

  constructor(private el: ElementRef) {}
}

<img cachel="https://example.com/logo.png" />

React

const cache = new Cachel('my-app');

export function useCachedAsset(url) {
  const [src, setSrc] = useState(null);

  useEffect(() => {
    cache.load(url).then(() => cache.get(url)).then(setSrc);
    return () => { if (src) URL.revokeObjectURL(src); };
  }, [url]);

  return src;
}

// usage
const src = useCachedAsset('https://example.com/logo.png');
<img src={src} />

Browser Compatibility

cachel uses IndexedDB which is supported in all modern browsers since 2015.

No service worker required. Works in any browser context.

License

MIT