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.

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