StealJS

Steal is an extensible, universal module loader. Its primary capability is the ability to load JavaScript modules defined in multiple formats simultaneously, including ES6, AMD, and CommonJS. This allows developers to mix and match different module styles within a single project.

Supported module formats include:

• ES6: Using import statements.
• AMD: Using define calls.
• CommonJS: Using require calls.

// ES6
import { hello, goodbye } from  "greetings";

// AMD
define(["greetings"],function(greetings){ ... });

// CommonJS
var hello = require('greetings').hello;
var goodbye = require('greetings').goodbye;

The homeAlias is a lookup scheme that roots module lookups to your project's base folder. By default, this is represented by the ~ symbol. This allows you to reference modules relative to your project root without using long relative paths (e.g., ../../) or the full package name.

To use it, prepend your module path with ~/.

If your package.json defines a specific library directory via steal.directories.lib, the ~ symbol will resolve relative to that directory.

The load object is a Plain Old JavaScript Object (POJO) provided during StealJS module loading lifecycle hooks. It contains information about the module being processed. The load object is instantiated after the steal.hooks.normalize step, meaning the module name is guaranteed to be available.

Key properties include:

• name: The moduleName of the module. This property is always present.
• address: The URL, filesystem path, or generic location where the module can be fetched (available after the steal.hooks.locate step).
• source: The actual source code of the module.
• metadata: An object containing metadata associated with the module, such as its module format.

A moduleIdentifier is a string used in import functions to specify which module to load. It is the raw string passed to functions like require() (CommonJS), import (ES6), or steal.import() (dynamic loading).

Common forms of a moduleIdentifier include:

• Relative paths: e.g., './foo'
• npm dependency names: e.g., 'lodash'
• Mapped names: A name that has been mapped to a different moduleName via configuration.

Internally, StealJS uses steal.hooks.normalize to convert these identifiers into moduleNames, which serve as the actual keys in the module registry.

In Steal, it is critical to distinguish between the string you use in your code and the canonical name Steal uses to track the module in its registry.

• moduleIdentifier: The raw string provided to import, require(), or other statements (e.g., ./dep, lodash, or styles.css). These are typically relative to the current module.
• moduleName: The canonical, unique string produced after the identifier is normalized (e.g., app/util/dep, lodash@3.0.0#main). This is used as the key in the module registry to ensure a module is only loaded and executed once.

The locate:// scheme allows you to rewrite paths using the StealJS path resolution system. This is useful for referencing resources that might be located in node_modules, relative to the baseURL, or within other stealable modules, without hardcoding complex relative paths.

Supported Extensions:

• CSS
• LESS
• Stache

Important Limitations:

• CSS Imports: The locate:// syntax is not supported in standard CSS @import statements because the browser handles those imports directly, bypassing the Steal CSS plugin's ability to rewrite the paths.
• Recursion: In LESS and Stache, the syntax is available recursively (it works in sub-imports).

Steal configuration can be established in three ways:

1. Global object: Set a steal object on the window before loading the script.

   <script>
     steal = {main: "myapp"};
   </script>
   <script src="../path/to/steal/steal.js"></script>

2. Script attributes: Use attributes directly on the steal.js script tag.

   <script src="../path/to/steal/steal.js" main="myapp"></script>

3. Programmatic call: Use steal.config() (typically inside a configuration module).

   steal.config({
     paths: {"can/*" : "http://canjs.com/release/2.0.1/can/*"}
   });

When calling clone(moduleOverrides), the moduleOverrides object maps module identifiers to their new definitions.

Module Identifiers

Identifiers can be any valid Steal module syntax, including:

• ES6 modules: The exact string used in your import statement.
• CommonJS: The exact string used in require().
• Relative paths: e.g., './moduleB'.
• npm packages: The package name used to resolve the dependency.

Module Definitions

The values in the moduleOverrides object define the exports for the overridden module. You must match the export structure of the original module (e.g., providing a default key for default exports, or named keys for named exports).

clone({
  'moduleB': {
    getName: function() {
      return 'moduleBOverride';
    },
    getExcitedName: function() {
      return 'moduleBOverride!';
    }
  }
});

The @loader module refers specifically to the loader instance that is currently loading the module where @loader is imported.

While @loader is often identical to the global steal.loader, you should use @loader instead of the global instance when:

1. You are in a build environment where multiple loaders may exist.
2. You are using steal.steal-clone to test injected modules.

Using @loader ensures you are configuring or importing modules through the correct loader context. It supports all standard Steal loader methods like .config() and .import().