Converting a single module

Suppose you have an ES6 module like this:

import foo from 'foo';
var bar = foo.toUpperCase();
export default bar;

You can convert it to one of three formats:

• AMD (asynchronous module definition) - works with e.g. RequireJS
• CommonJS - works in node.js or with Browserify
• UMD (universal module definition) - works as an AMD module, a CommonJS module, or as a browser global

For the rest of this page, source refers to the contents of the module above. You can try converting modules in your browser here.

Understanding named/default imports/exports

Read the page on strict mode to understand the nuances around named versus default imports and exports. The standard behaviour is to only allow default imports and exports with one-to-one transformations - if you want to use named imports/exports, you must pass the strict: true option, but make sure you understand the trade-offs!

AMD

To create an AMD module:

var amd = esperanto.toAmd( source );

// amd.code
define(['foo'], function (foo) {

  'use strict';
	
  var bar = foo.toUpperCase();
  return bar;

});

With strict mode:

var amd = esperanto.toAmd( source, { strict: true });

// amd.code
define(['exports', 'foo'], function (exports, foo) {

  'use strict';

  var bar = foo.default.toUpperCase();
  exports.default = bar;

});

CommonJS

To create a CommonJS module:

var cjs = esperanto.toCjs( source );

// cjs.code
'use strict';
	
var foo = require('foo');
var bar = foo.toUpperCase();
module.exports = bar;

With strict mode:

var cjs = esperanto.toCjs( source, { strict: true });

// cjs.code
'use strict';

var foo = require('foo');
var bar = foo.default.toUpperCase();
exports.default = bar;

UMD

To create a UMD module (note that you must supply a name for the export):

var umd = esperanto.toUmd( source, { name: 'myModule' });

// umd.code
(function (global, factory) {
  typeof exports === 'object' && typeof module !== 'undefined' ? factory(require('foo')) :
  typeof define === 'function' && define.amd ? define(['foo'], factory) :
  global.myModule = factory(global.foo)
}(this, function (foo) { 'use strict';

  var bar = foo.toUpperCase();
  return bar;

}));

With strict mode:

var umd = esperanto.toUmd( source, { name: 'myModule', strict: true });

// umd.code
(function (global, factory) {
  typeof exports === 'object' && typeof module !== 'undefined' ? factory(require('foo')) :
  typeof define === 'function' && define.amd ? define(['foo'], factory) :
  factory((global.myModule = {}), global.foo)
}(this, function (exports, foo) { 'use strict';

  var bar = foo['default'].toUpperCase();
  exports.default = bar;

}));

The name doesn't have to be a valid identifier, so you can use things like SomeNamespace.MyPlugin.

Options

The second argument, if supplied, is an options object:

• strict - true if you want to use strict mode
• amdName - allows you to specify a name for your AMD module
• absolutePaths - if amdName is specified, you can set this option to true, and relative AMD module paths will be turned to absolute paths. (This is particularly useful if the dependencies themselves use module IDs.)
• name - what name to use for the global export if you're using .toUmd()
• banner - a string to prepend to the output
• footer - a string to append to the output
• sourceMap, sourceMapFile and sourceMapSource - see sourcemaps for info
• _evilES3SafeReExports - will cause re-exported bindings to be done with direct property assignment rather than Object.defineProperty(). In most cases, the resulting behaviour will be no different, but it could result in undefined bindings in cases of cyclical dependencies, and values are fixed at the time of re-export rather than live
• useStrict - not to be confused with strict. If false, a 'use strict' pragma will not be added. Defaults to true (since ES6 modules are always in strict mode automatically)

Bring your own AST (advanced)

If you've already got an AST that adheres to the ESTree spec, you can avoid the work of generating a new one:

var { code, ast } = someOtherTranspiler( source );
var amd = esperanto.toAmd({ code, ast });