ResourceLoader.js: Dynamic Asset Loading Library

01 · The problem

Loading resources dynamically is messy.

Every resource type has its own loading mechanism, events, and error handling quirks. You end up writing the same boilerplate for every project:

// A script
const s = document.createElement('script');
s.src = url; s.onload = resolve; s.onerror = reject;
document.head.appendChild(s);

// A stylesheet — different element, different events
const l = document.createElement('link');
l.rel = 'stylesheet'; l.href = url;
document.head.appendChild(l);

// JSON — completely different approach
const data = await fetch(url).then(r => r.json());

// A font — yet another API
const font = new FontFace('MyFont', `url(${url})`);
await font.load();
document.fonts.add(font);

ResourceLoader.js normalizes all of this into one call:

await ResourceLoader.include([
  'https://cdn.example.com/theme.css',
  'https://cdn.example.com/vendor.js',
  'https://api.example.com/config.json',
]);
// All three loaded. Start your app.

Core features

Everything you need. Nothing you don't.

Retries and timeouts

Configure retries, delay between attempts, and a per-attempt timeout. Each retry gets its own fresh clock.

ResourceLoader.include([url], {
  retries: 3,
  retryDelay: 2000,
  timeout: 5000,
});

Concurrency and priority

Limit simultaneous loads to avoid saturating the browser connection pool. Higher-priority resources load first when slots are limited.

ResourceLoader.include([font], { priority: 10 });
ResourceLoader.include([img], {
  priority: 1, maxConcurrency: 4,
});

Deduplication

An internal registry tracks every URL. Requesting something already loaded or loading returns the existing Promise. No duplicate network requests.

ResourceLoader.getResourceState('app.js');
// 'loading' | 'loaded' | 'unloaded'

02 · Resource types

Auto-detected from the URL extension.

Category	Extensions	Loaded via
Scripts	`.js`	`<script>` element
Stylesheets	`.css`	`<link>` element
JSON data	`.json`	`fetch()` + `response.json()`
Images	`.jpg .png .gif .svg .webp`	`<img>` element
Fonts	`.woff .woff2`	`FontFace` API
Audio	`.mp3 .ogg .wav`	`fetch()` + `response.blob()`
Video	`.mp4 .avi .webm`	`fetch()` + `response.blob()`
Binary / PDF	`.pdf .zip .bin`	`fetch()` + `response.blob()`

03 · API reference

The full public surface.

Methods

Method	Description
`include(urls, opts?)`	Load one or more resources. Returns a Promise that resolves when all succeed, or rejects with a structured aggregate error.
`getResourceState(url)`	Returns `'loading'`, `'loaded'`, or `'unloaded'`.
`cancelResource(url)`	Abort an in-flight load.
`cancelAll()`	Abort all pending loads at once.
`unloadResource(url)`	Remove a loaded resource from the DOM and clear it from the state registry.
`setLoggingLevel(level)`	Set global log verbosity: `'silent'`, `'warn'`, or `'verbose'`.

Options (second argument to include)

Option	Default	Description
`retries`	0	Additional attempts after a `network` or `timeout` failure.
`retryDelay`	0	Milliseconds between retry attempts.
`timeout`	0	Per-attempt timeout in ms. 0 means no limit.
`maxConcurrency`	3	Maximum simultaneous loads.
`priority`	0	Queue priority. Higher numbers load first when slots are limited.
`cacheBusting`	false	Append a timestamp query string to prevent stale cache hits.
`onSuccess`	—	Callback fired for each successful load: `(data, url) => void`.
`onError`	—	Callback fired for each failure: `(error, url) => void`.
`logLevel`	'warn'	`'silent'`, `'warn'`, or `'verbose'`.

04 · Installation

CDN or npm.

CDN (pinned, recommended for production)

<script src="https://cdn.jsdelivr.net/npm/resourceloader-js@1.0.2/resourceLoader.js"></script>

CDN (always latest)

<script src="https://cdn.jsdelivr.net/npm/resourceloader-js/resourceLoader.js"></script>
<script src="https://unpkg.com/resourceloader-js/resourceLoader.js"></script>

npm

npm install resourceloader-js

// CommonJS
const ResourceLoader = require('resourceloader-js');

// ESM
import ResourceLoader from 'resourceloader-js';

Full example

ResourceLoader.include([
  'https://cdn.example.com/theme.css',
  'https://cdn.example.com/vendor.js',
  'https://api.example.com/config.json',
], {
  retries: 2,
  timeout: 8000,
  logLevel: 'verbose',
  onSuccess: (data, url) => console.log('Ready:', url),
  onError: (err, url) => console.warn('Failed:', url, err.message),
})
.then(() => initApp())
.catch((err) => console.error('Load failed:', err));

One API for every resource type.

MIT licensed. Zero dependencies. Available via jsDelivr, unpkg, and npm. Related: StorageManager.js for enhanced browser storage and EmbedManager for lazy-loaded embeds.

View on GitHub npm package