npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

idb-sideloader

v2.0.0

Published

A tiny Javascript + TypeScript library for caching static assets

Downloads

1

Readme

idb-sideloader.js

Licensed under the MIT license.

What is idb-sideloader? It's a tiny Javascript + TypeScript library that "sideloads" static assets (link, and img tags) on webpages using the fetch() API and caches them in an IndexedDB store to eliminate dependency on the standard browser static asset cache, and to eliminate HTTP requests on subsequent page loads. CSS and image assets are stored in IndexedDB as Blobs.

idb-sideloader makes use of URLSearchParams Polyfill for backward compatibility with browsers without support for URLSearchParams.size (i.e. Safari and some WebKit Chromium builds).

Usage

To cache and sideload static assets:

  • Change the original src (href for CSS) attribute on tags to data-src.
  • Optionally give tags a unique ID with data-key. The cached items are stored in the database with this key. The actual filenames of the assets can change freely, like in the case of JS build systems.
  • Load and invoke indexed-cache at the end.

Simplest Usage - Vanilla HTML + Javascript Global Object

<head>
	<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/index.iife.min.js"></script>
</head>
<body>
	<img data-src="https://your-url.com/your-image.jpg" />
	<script type="text/javascript">
		const assetLoader = new IDBSideloader();
		assetLoader.load().catch(console.error);
	</script>
</body>

Simplest Usage - Vanilla HTML + ESM Javascript

<body>
	<img data-src="https://your-url.com/your-image.jpg" />
	<script type="module">
		import IDBSideloader from 'https://cdn.jsdelivr.net/npm/[email protected]/+esm'
		const assetLoader = new IDBSideloader();
		assetLoader.load().catch(console.error);
	</script>
</body>

Example - React + Recoil

Use-cases include webapps, PWAs, module federation, and other use-cases.

This pattern is useful in situations where an PWA isn't feasible (i.e. extending low-code platforms with federated react component modules), but where we still want to provide the user with progressive data loading for static assets.

The example below shows the following:

  1. Prime a lazily evaluated global state variable with an IDBSideloader cache object
  2. Initializing the IDBSideloader cache object with a useLayoutEffect hook component on first app render
  3. Load a cached images with a React img component wrapper
import { FunctionComponent, useLayoutEffect } from 'react';
import { atom, selector, useRecoilValue } from 'recoil';
import IDBSideloader from 'idb-sideloader';

// Initialize async read-only selector. Selector evaluated lazily.
export const assetLoader = selector({
	key: 'asset-loader-selector',
	get: async () => {
		const ic = new IDBSideloader();
		await ic.load();
		return ic;
	},
});

// Effectfully load data on initial app render
export const IDBSideloaderInitEffect: FunctionComponent = () => {
  const sideloader = useRecoilValue(assetLoader);
  useLayoutEffect(
    () => {
			sideloader.load().catch(console.error);
    },
    // eslint-disable-next-line react-hooks/exhaustive-deps
    [
      /** once */
    ]
  );
  return null;
};

// Load cache data when user-actions load images into the DOM
export const StaticImg: FunctionComponent<
	DetailedHTMLProps<ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>
> = (props) => {
	const { src, onClick, otherProps } = props;
	const imgRef = useRef<HTMLImageElement>(null);
  const loader = useRecoilValue(idbImgStoreAtom);
	useLayoutEffect(() => {
			if (!imgRef) return;
			loader.load([imgRef]).catch(console.error);
	}, [loader, imgSrc]);
	return (<img ref={imgRef} data-src={src} {...otherProps} />)
};

Example - Load modern and legacy bundle conditionally

Here is an example on how to load modern(ESM) bundle and legacy bundle conditionally based on browser support.

    <!-- Only modern browsers understand type=module and legacy browsers will skip this script -->
    <script type="module">
        // Use ESM bundle.
        import IDBSideloader from "https://cdn.jsdelivr.net/npm/[email protected]/+esm";
        const assetLoader = new IDBSideloader();
        assetLoader.load().catch(console.error);
    </script>

    <!-- This will only be executed on legacy browsers which doesn't support ES6 modules.
    Modern browsers ignore the script if its tagged `nomodule`. -->
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/index.iife.min.js" nomodule></script>
    <script nomodule>
        const ic = new IDBSideloader();
        const assetLoader = new IDBSideloader();
        assetLoader.load().catch(console.error);
    </script>

Optional configuration

One or more of these optional params can be passed during initialization. Default values are shown below.

new IDBSideloader({
    tags: ["img", "link"],
    dbName: "indexed-cache",
    storeName: "objects",
    // If this is enabled, all objects in the cache with keys not
    // found on elements on the page (data-key) will be deleted.
    // This can be problematic in scenarios where there are multiple
    // pages on the same domain that have different assets, some on
    // certain pages and some on other.
    prune: false,
    // Enabling this skips IndexedDB caching entirely,
    // causing resources to be fetched over HTTP every time.
    // Useful in dev environments.
    skip: false,
    // Default expiry for an object in minutes (default 3 months).
    // Set to null for no expiry.
    expiry: 131400
}).load();
  • load() can be called with a DOM Node or NodeList. When none are given, it scans the entire DOM.
  • To manually prune all objects in the database except for a given list of keys, after await init(), call .prune([list of keys]).

Use-case: persisted storage of static assets

Unlike the browser's asset cache, IndexedDB is not cleared automatically, providing a longer term static file storage on the client side.

Use if at least a few of these are true:

  • There are large static files (Image, CSS) that rarely change.
  • High traffic from a large number of returning users who access web pages with the same assets regularly and frequently.
  • The pages are mostly inside mobile webviews where browser cache gets evicted (OS pressure) causing the same assets to be fetched afresh over and over wasting bandwidth.
  • Bandwidth is a concern.
  • We don't care if the data remains cached in the user's browser.

Features

  • Supports img, link tags.
  • Respects lazy on image tags.
  • Can invalidate cached items with a TTL per tag.
  • Can invalidate cached items with a simple random hash per tag.

Gotchas

  • CORS.
  • First-paint "flash" (needs to be handled manually) as scripts and styles only load after HTML is fetched and rendered by the browser.

Consider:

img[src=""], img:not([src]) {
  opacity: 0;
}