Options Reference

All options are passed as the second argument to include(). Every option is optional.

Quick Reference

Option	Type	Default	Description
`logLevel`	`'silent' \| 'warn' \| 'verbose'`	`'warn'`	Logging verbosity
`timeout`	`number`	`10000`	Load timeout in milliseconds
`retries`	`number`	`0`	Retry attempts on failure
`retryDelay`	`number`	`1000`	Milliseconds between retries
`maxConcurrency`	`number`	`3`	Max simultaneous loads
`priority`	`number`	`0`	Load order priority (higher = first)
`cacheBusting`	`boolean`	`false`	Append cache-busting query string
`cacheBustingQuery`	`string`	`'?_=<timestamp>'`	The query string to append
`cacheBustingTypes`	`string[]`	`['js', 'css']`	File types to apply cache busting
`restrictCacheBustingToLocal`	`boolean`	`true`	Only bust cache for same-origin URLs
`onSuccess`	`function`	—	Per-resource success callback
`onError`	`function`	—	Per-resource error callback
`appendToBody`	`boolean`	`false`	Append scripts to `<body>`
`deferScriptsUntilReady`	`boolean`	`true`	Defer scripts until DOMContentLoaded
`removeFailedElements`	`boolean`	`true`	Remove DOM elements on failure
`crossorigin`	`false \| 'anonymous' \| 'use-credentials'`	`false`	crossorigin attribute value
`attributes`	`object`	`{}`	Additional element attributes

Option Details

`logLevel`

Type: 'silent' | 'warn' | 'verbose' Default: 'warn'

Sets the logging verbosity for this call. Also updates the global level for subsequent calls.

ResourceLoader.include([url], { logLevel: 'verbose' });

See setLoggingLevel() for more details.

`timeout`

Type: number (milliseconds) Default: 10000

Maximum time to wait for a resource to load. If the timeout is exceeded, the load is aborted with error.type === 'timeout'. Each resource and each retry attempt gets its own independent timeout clock.

ResourceLoader.include([url], { timeout: 5000 }); // 5 seconds

`retries`

Type: number Default: 0

Number of additional attempts after the first failure. A value of 3 means 4 total attempts (1 initial + 3 retries).

ResourceLoader.include([url], { retries: 3 });

`retryDelay`

Type: number (milliseconds) Default: 1000

Time to wait between retry attempts. Requires retries > 0 to have any effect.

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

`maxConcurrency`

Type: number Default: 3

Maximum number of resources that load simultaneously. Additional resources queue and start as slots become available.

ResourceLoader.include(manyUrls, { maxConcurrency: 5 });

`priority`

Type: number Default: 0

Sort order for the load queue. Higher numbers load before lower numbers. Sorting happens across separate include() calls before the concurrency queue runs.

// These load before lower-priority calls
ResourceLoader.include([critical], { priority: 10 });
ResourceLoader.include([analytics], { priority: 0 });

`cacheBusting`

Type: boolean Default: false

When true, appends a cache-busting query string to resource URLs (subject to cacheBustingTypes and restrictCacheBustingToLocal).

ResourceLoader.include([url], { cacheBusting: true });
// URL becomes: https://example.com/app.js?_=1710000000000

`cacheBustingQuery`

Type: string Default: '?_=<timestamp>'

The query string to append when cacheBusting is enabled. Override this to use a version number or content hash instead of a timestamp.

ResourceLoader.include([url], {
  cacheBusting: true,
  cacheBustingQuery: '?v=2.1.0',
});

`cacheBustingTypes`

Type: string[] Default: ['js', 'css']

File extensions that receive the cache-busting query string when cacheBusting is true.

ResourceLoader.include([url], {
  cacheBusting: true,
  cacheBustingTypes: ['js', 'css', 'json'],
});

`restrictCacheBustingToLocal`

Type: boolean Default: true

When true, cache busting is only applied to URLs that share the same origin as the current page. Set to false to apply it to all URLs, including external CDNs.

ResourceLoader.include([url], {
  cacheBusting: true,
  restrictCacheBustingToLocal: false, // Apply to CDN URLs too
});

`onSuccess`

Type: function Default: none

Callback invoked once per resource as each one finishes loading. The argument varies by resource type:

Resource type	Argument
JS, CSS, images	URL string
JSON	Parsed JavaScript object
Audio, video, PDF, binary	`Blob` object
Fonts	`undefined`

ResourceLoader.include([url], {
  onSuccess: (data) => {
    if (typeof data === 'string') console.log('Loaded URL:', data);
    else if (data instanceof Blob) console.log('Loaded blob:', data.type);
    else console.log('Loaded data:', data);
  },
});

`onError`

Type: function Default: none

Callback invoked when a resource fails (after all retries are exhausted). Receives two arguments:

error: { type: 'network' | 'timeout' | 'abort' | 'unsupported', message: string }
url: The URL that failed

ResourceLoader.include([url], {
  onError: (error, url) => {
    console.error(`[${error.type}] ${url}: ${error.message}`);
  },
});

`appendToBody`

Type: boolean Default: false

When true, <script> elements are appended to <body> instead of <head>. Has no effect on CSS, JSON, or other types.

ResourceLoader.include(['https://cdn.example.com/app.js'], {
  appendToBody: true,
});

`deferScriptsUntilReady`

Type: boolean Default: true

When true, script elements are not inserted until the DOMContentLoaded event has fired. If the DOM is already ready when include() is called, this has no visible effect.

ResourceLoader.include([url], { deferScriptsUntilReady: false });

`removeFailedElements`

Type: boolean Default: true

When true, failed <script>, <link>, and <img> elements are removed from the DOM automatically. Set to false to leave them for debugging.

ResourceLoader.include([url], { removeFailedElements: false });

`crossorigin`

Type: false | 'anonymous' | 'use-credentials' Default: false

Sets the crossorigin attribute on <script> and <link> elements. Required when using Subresource Integrity (attributes.integrity).

ResourceLoader.include([url], {
  crossorigin: 'anonymous',
  attributes: { integrity: 'sha384-...' },
});

`attributes`

Type: object Default: {}

Additional HTML attributes to apply to the created DOM element. The most commonly used attribute is integrity for SRI:

ResourceLoader.include(['https://cdn.example.com/lib.js'], {
  crossorigin: 'anonymous',
  attributes: {
    integrity: 'sha384-abc123...',
    // Any other valid attribute for the element type:
    // nonce: 'abc123',
    // referrerpolicy: 'no-referrer',
  },
});