Codakey
Play
← Back to seajs/seajs

How to Deploy & Use seajs/seajs

Sea.js Deployment & Usage Guide

A complete guide to building, configuring, and deploying Sea.js — a Module Loader for the Web that implements the CMD (Common Module Definition) specification.

Prerequisites

  • Runtime: Node.js >= 0.10 (required for build tools and Node.js bridge)
  • Browser: Modern browsers (Chrome, Firefox, Safari, IE6+) or any environment with JavaScript support
  • Tools: Git, npm (Node Package Manager)
  • Optional: Make (for building distribution files)

Installation

1. Clone the Repository

git clone https://github.com/seajs/seajs.git
cd seajs

2. Install Dependencies

npm install

3. Build Distribution Files (Optional)

If modifying source code in src/, build the production files:

make        # or npm run build if available
# Generates dist/sea.js and dist/sea-debug.js

4. Direct Browser Usage (No Build Required)

Download the pre-built files and include directly in HTML:

<script src="https://cdn.jsdelivr.net/gh/seajs/seajs@master/dist/sea.js"></script>

Configuration

Configure Sea.js using seajs.config() before loading modules. Configuration supports path aliasing, variable substitution, and URL mapping based on the path resolution utilities in src/util-path.js.

Basic Configuration

seajs.config({
  // Base path for module resolution
  base: './assets/',
  
  // Path aliases (util-path.js: parseAlias)
  alias: {
    'jquery': 'lib/jquery/1.10.1/jquery',
    'underscore': 'lib/underscore/1.6.0/underscore'
  },
  
  // Path shortcuts (util-path.js: parsePaths)
  paths: {
    'gallery': 'https://cdn.example.com/gallery'
  },
  
  // Variable substitution in paths (util-path.js: parseVars)
  vars: {
    'locale': 'zh-cn'
  },
  
  // URL mapping for cache busting or CDN
  map: [
    [/^(.*\.js)(.*)$/, '$1?t=12345']
  ],
  
  // Preload modules before application starts
  preload: ['jquery', 'plugin/text']
});

Module Definition (CMD Format)

Define modules using the define function as shown in docs/assets/main.js:

// Standard CMD module format
define(function(require, exports, module) {
  var $ = require('jquery');
  var util = require('./util');
  
  exports.init = function() {
    // module logic
  };
});

Build & Run

Browser Environment

Development Mode:

<!DOCTYPE html>
<html>
<head>
  <script src="path/to/sea-debug.js"></script>
  <script>
    // Set configuration
    seajs.config({
      base: './js/',
      alias: {
        'jquery': 'jquery/3.6.0/jquery'
      }
    });
    
    // Bootstrap application
    seajs.use('./js/main');
  </script>
</head>
<body>
  <!-- Content -->
</body>
</html>

Production Mode:

Use sea.js (minified) instead of sea-debug.js. Combine modules using a build tool (spm, grunt, or webpack with appropriate plugin) to reduce HTTP requests.

Node.js Environment

Use the Node.js compatibility bridge in lib/sea.js to load CMD modules in Node:

// In your Node.js application entry point
require('./lib/sea');

// Now you can use seajs and define
seajs.config({
  cwd: normalize(process.cwd()) + "/"
});

// Load CMD modules
seajs.use('./server/app', function(app) {
  app.start();
});

Programmatic Module Loading:

// Access cached modules
var mod = seajs.cache[filename];
if (mod && mod.status < seajs.Module.STATUS.EXECUTED) {
  seajs.use(filename);
}

Deployment

Static Web Hosting

  1. Upload files: Deploy sea.js and your module files to a static server or CDN
  2. Set MIME types: Ensure .js files are served with application/javascript
  3. Cross-Origin: If loading modules from different domains, configure CORS headers
// Production configuration example
seajs.config({
  base: 'https://cdn.yoursite.com/app/1.0.0/',
  alias: {
    'app': 'app/index'
  },
  // Cache control
  map: [
    [/(.*)/, '$1?v=1.0.0']
  ]
});

seajs.use('app');

Node.js Server Deployment

For server-side CMD module usage:

// server.js
require('./lib/sea');

// Configure for server environment
seajs.config({
  cwd: __dirname + '/'
});

// Load server modules
seajs.use('./modules/server', function(server) {
  server.listen(3000);
});

Deploy using standard Node.js process managers (PM2, systemd, or Docker).

Package Managers

Sea.js can be distributed via npm for Node.js projects or Bower for client-side projects (legacy).

Troubleshooting

Module Loading Issues

Symptom: Module status shows ERROR (status 7) or 404 in network tab

Solution:

  • Check path resolution using seajs.resolve('module-id') in console
  • Verify base path is correctly set relative to the HTML file
  • Ensure file extensions are handled correctly (Sea.js auto-appends .js unless path contains ? or ends with / or .js)
// Debug path resolution
console.log(seajs.resolve('jquery')); 
// Should output full URL

Circular Dependencies

Symptom: Modules not loading or returning empty exports

Solution:

  • Check for circular require() calls between modules
  • Use require.async() for lazy loading to break circular chains:
define(function(require, exports) {
  exports.init = function() {
    // Lazy load to avoid circular dependency
    require.async('./circular-dep', function(dep) {
      dep.doSomething();
    });
  };
});

Node.js Bridge Issues

Symptom: Error: Cannot find module when using lib/sea.js

Solution:

  • Ensure file extensions are explicit in Node.js environment (the bridge in lib/sea.js normalizes paths but expects standard Node resolution)
  • Check that cwd is configured correctly in seajs.config()
  • Verify the module is registered in seajs.cache before accessing exports

Path Normalization

Symptom: Incorrect relative path resolution (../ or ./ not working)

Solution:

  • Paths are normalized using realpath() logic from src/util-path.js:
    • // → /
    • /./ → /
    • /foo/../ → removed
  • Avoid multiple slashes in base URLs
  • Use absolute paths for base configuration to prevent resolution ambiguity

Debugging Module Status

Inspect module loading states (defined in src/module.js):

// Check specific module status
var mod = seajs.cache[seajs.resolve('module-id')];
console.log('Status:', mod.status);
// 1: FETCHING, 2: SAVED, 3: LOADING, 4: LOADED, 5: EXECUTING, 6: EXECUTED, 7: ERROR
← Project overviewView alternatives to seajs/seajs →