loadjs

loadjs is a minimal, dependency-free JavaScript library for asynchronously loading scripts and stylesheets in the browser. It loads one or more files under a named “bundle,” fires success/error callbacks once every file in the bundle has loaded (or timed out), and lets you declare dependencies between bundles so a later bundle only starts loading once its dependencies have finished — all without a build step or module bundler.

At under 1KB minified and gzipped, loadjs targets use cases where pulling in a full module bundler or async-loading framework is overkill: conditionally loading third-party widgets, polyfills, or CSS files, or sequencing script execution order in plain HTML pages.

What You Get

• loadjs(paths, bundleId, options) to kick off async loading of one or more script/CSS files as a named bundle
• loadjs.ready(bundleIds, callbacks) to subscribe success/error callbacks to one or more bundle IDs, including bundles already loaded
• Dependency declarations between bundle IDs so a bundle only starts once its declared dependencies have finished loading
• Configurable per-call options (numRetries, before hook, css/async flags, timeout) for controlling how files load
• A sub-1KB minified/gzipped footprint with no runtime dependencies, distributed as UMD, AMD, and CommonJS builds

Common Use Cases

• Conditionally loading third-party widgets or analytics scripts only when a feature is used
• Loading polyfills before dependent application code runs, without a bundler-level dynamic import
• Loading CSS files asynchronously alongside JS bundles and firing a callback once both are ready
• Sequencing execution order between separately-hosted script bundles on a plain HTML page

Under The Hood

Architecture The entire implementation lives in a single file, src/loadjs.js (~319 lines), built around a publish/subscribe model: subscribe() registers callbacks against bundle IDs (checking a bundleResultCache for already-finished bundles first), and publish() fires those callbacks once a bundle’s underlying file loads resolve, tracking any paths that failed to load; a separate loadFile()/loadCss() pair does the actual DOM insertion (script/link tags) and attaches load/error/readystatechange handlers to detect completion across browsers.

Tech Stack Plain, dependency-free JavaScript (no framework, no runtime dependencies), built and packaged via Gulp into UMD/AMD/CommonJS distributions in dist/, keeping the published bundle at roughly 1KB minified and gzipped.

Code Quality The project has a dedicated test/tests.js suite plus browser-based example pages (examples/) used to manually verify CSS-loading edge cases (error handling, preload behavior, and performance) that are hard to unit test reliably across browsers; the small, single-file implementation keeps the surface area easy to audit even without extensive automated coverage of every browser quirk.

API Design The API centers on two calls — loadjs() to start loading and loadjs.ready() to subscribe — plus dependency declarations passed as extra arguments, which keeps common cases terse but means the dependency-graph and callback-registration behavior benefits from reading the README’s examples once before using it in anger.