Master SeaJS: Complete CMD Module Guide and Compare with RequireJS

1. Introduction

SeaJS is a JavaScript module loader that implements the CMD (Common Module Definition) specification. It improves code maintainability by defining modules and managing their loading and execution.

2. define

2.1 CMD Specification

In CMD, a module corresponds to a single file. The basic syntax is: define(factory) If factory is an object or string, the module exports that value directly.

If factory is a function, it receives require, exports, and module as arguments and should return or assign the exported interface.

// object export
define({ "foo": "bar" });

// function export
define(function(require, exports, module) {
    // module code
});

2.2 Transport Format

SeaJS also supports a Transport format that adds an optional id and deps array, enabling file concatenation: define(id?, deps?, factory) When multiple define calls exist in a single file, only the last one is recognized unless the legacy firstModuleInPackage feature (removed after v1.3.1) is used.

3. factory Parameters

3.1 Using factory

define(function(require, exports, module) {
    var a = require('./a');
    a.doSomething();

    exports.foo = 'bar';
    exports.doSomething = function() {};

    // Incorrect: reassigning exports
    // exports = { foo: 'bar' };

    // Correct: assign to module.exports
    module.exports = { foo: 'bar', doSomething: function() {} };
});

3.2 require Function

require(id)

– synchronously loads a module and returns its interface (or null if unavailable). require.async(id, callback?) – asynchronously loads a module and invokes the callback. require.resolve(id) – returns the resolved absolute path without loading.

3.3 exports Object

exports

is a reference to module.exports. Reassigning exports does not change the exported interface; use module.exports for that purpose.

3.4 module Object

module.uri

– resolved absolute path. module.dependencies – list of dependencies. module.exports – the value exposed as the module’s public API.

4. Module Identifier (id)

Identifiers follow a “path‑as‑id” rule and are used in require and require.async. Types include:

Relative ids (starting with . or ..) – resolved relative to the current module.

Top‑level ids (no leading . or /) – resolved against SeaJS’s base configuration.

Plain paths – treated as relative to the page; absolute paths start with /.

seajs.config({ base: 'http://code.jquery.com/' });
require.resolve('jquery'); // → http://code.jquery.com/jquery.js

5. Starting the Module System

<script src="../gb/sea.js"></script>
<script>
    seajs.use('./index.js');
</script>

Best practices: call seajs.use only for bootstrapping, and add an id attribute to the sea.js script tag to help the loader locate itself.

<script src="../gb/sea.js" id="seajsnode"></script>

6. Debugging Interface

seajs.cache

– object containing all loaded modules. seajs.resolve – resolves a module id to a URL. seajs.require – global require function. seajs.data – configuration and internal variables. seajs.log – logging function (provided by seajs‑log plugin). seajs.find – helper from seajs‑debug plugin.

7. Module Loading Flow

The overall flow:

Call seajs.use with an entry module; a callback receives the loaded module.

The loader fetches the module (from cache or network) and resolves its dependencies recursively.

Factory functions are executed in the order they appear, and document.createElement('script') injects the scripts.

8. Differences from RequireJS

8.1 Specification

RequireJS follows AMD, while SeaJS follows CMD.

8.2 Execution Timing

SeaJS executes factories only when required, preserving the order of require calls; RequireJS may execute dependencies earlier, affecting load order.

8.3 Focus

SeaJS targets browsers exclusively, keeping the loader lightweight; RequireJS also supports Rhino and Node, resulting in a larger file.

8.4 Philosophy

RequireJS provides many plugins that add functionality but increase complexity; SeaJS aims for simplicity and includes built‑in CSS module support.

9. References

https://github.com/seajs/seajs/issues/242

https://github.com/seajs/seajs/issues/258

https://github.com/seajs/seajs/issues/263

https://github.com/seajs/seajs/issues/266

https://github.com/seajs/seajs/issues/277

http://www.zhihu.com/question/21157540

http://annn.me/how-to-realize-cmd-loader/

http://chaoskeh.com/blog/why-its-hard-to-combo-seajs-modules.html

https://github.com/cmdjs/specification/blob/master/draft/module.md

https://www.douban.com/note/283566440/

https://imququ.com/post/amd-simplified-commonjs-wrapping.html

https://lifesinger.wordpress.com/2011/05/17/the-difference-between-seajs-and-requirejs/