Script.js - Asynchronous JavaScript Loader

Common errors

• Uncaught ReferenceError: $script is not defined

  cause The script.js library file has not been loaded into the page before your application code attempts to use the `$script` global.
  fix Ensure that `<script src="path/to/script.js"></script>` is included in your HTML before any custom JavaScript code that calls `$script()` methods.

• TypeError: Cannot read properties of undefined (reading 'ready')

  cause Similar to the `ReferenceError`, this occurs when the `$script` object is not available or fully initialized when its methods like `ready` are called.
  fix Verify the correct loading order and ensure the `script.js` file path is accurate. If dynamically loading `script.js` itself, ensure its load callback is fired before attempting to use `$script` methods.

• The script at 'http://example.com/missing.js' failed to load.

  cause A script specified in `$script()` or `$script.get()` could not be fetched due to a wrong URL, network issue, or server error.
  fix Check the script URL for typos. Verify the script exists at the specified path. Use the optional error callback in `$script.ready()` to handle cases where dependencies are not found: `$script.ready(['dep'], function(){}, function(depsNotFound){ /* handle missing deps */ });`

Warnings

• breaking This library is primarily designed for older browser environments and traditional server-rendered applications. It does not integrate well with modern JavaScript module systems (ES Modules, CommonJS) or bundlers (Webpack, Rollup, Vite) and might cause unexpected behavior or global scope pollution when used alongside them.
  Fix: For modern web development, consider using native ES Modules with import maps, or a module bundler like Webpack, Rollup, or Vite. If dynamic script loading is required, investigate `import()` for ES Modules or specialized libraries like SystemJS if broader module format support is needed.
• gotcha All scripts loaded via `$script.js` execute in the global scope. Variables and functions defined in these scripts will become global properties unless explicitly wrapped in IIFEs or closures, leading to potential naming conflicts.
  Fix: Encapsulate your script code using Immediately Invoked Function Expressions (IIFEs) or module patterns to limit scope pollution: `(function() { /* your code */ })();`.
• deprecated The `script.js` project appears to be largely unmaintained. While functional for its intended use case, it has not seen significant updates or new feature development for several years. This means it may not address modern web standards, security concerns, or performance optimizations.
  Fix: Evaluate alternatives that are actively maintained and align with current web development practices, such as native ES Modules with dynamic `import()`, or modern module bundlers.
• gotcha The `$script.urlArgs()` feature, while useful for cache busting, appends a query string to *all* subsequent script loads. This can prevent proxy caches (like Squid) from caching resources, potentially impacting performance for users behind such proxies.
  Fix: Use `$script.urlArgs('')` to clear previously set arguments when they are no longer needed. For cache busting, consider using versioned filenames (e.g., `app.v1.2.3.js`) or HTTP headers for cache control, which are generally more cache-friendly.

Install

• npm install scriptjs npm
• yarn add scriptjs yarn
• pnpm add scriptjs pnpm

Imports

• $script
  wrong:

  import $script from 'script.js'

  correct:

  <!-- In HTML --> <script src="script.js"></script>
  // In JavaScript, after loading
  $script('script.js', callback)

  $script.js operates by exposing a global `$script` object. It is typically loaded via a `<script>` tag in HTML. It does not use standard CommonJS `require()` or ES Modules `import` syntax.
• $script.ready
  wrong:

  import { ready } from '$script';

  correct:

  $script.ready('bundleName', function() { /* code */ });

  `$script.ready` is a method on the global `$script` object used to register callbacks that execute once specified script bundles or individual scripts are loaded and ready. It's the primary mechanism for dependency fulfillment.
• $script.path
  wrong:

  $script().path('/js/modules/');

  correct:

  $script.path('/js/modules/');

  `$script.path` is a global configuration method used to set a base path for all subsequent relative script loads. It must be called directly on the global `$script` object. To circumvent it for a single script, use `$script.get()`.

Quickstart

Demonstrates loading multiple scripts, grouping them into a bundle, setting a base path, and using the `$script.ready` callback for deferred execution based on named dependencies.

$script.path('/assets/js/');

// Load jQuery and a jQuery plugin concurrently, assigning them to a 'vendor' bundle ID
$script(['jquery-3.x.min.js', 'my-jquery-plugin.js'], 'vendor', function() {
  console.log('jQuery and plugin loaded. Initializing application...');
});

// Load a core application module separately
$script('app-core.js', 'appCore');

// Wait for both the 'vendor' bundle and 'appCore' module to be ready
$script.ready(['vendor', 'appCore'], function() {
  console.log('All core scripts are loaded and ready.');
  // Application initialization code that depends on all these scripts
  // For example, if jQuery is globally available via `window.$`
  if (typeof window.$ !== 'undefined') {
    console.log('jQuery version:', $.fn.jquery);
  }
  // Your application's main entry point
  // myApp.init();
}, function(depsNotFound) {
  console.error('Some dependencies were not found:', depsNotFound);
  // Optionally, try to lazy load missing dependencies
});